Reference·CellsIndexClose
Cells
What a cell is, where to find one, how to turn one on or off, the hub, how cells load.
A cell is a folder of code under ~/.nodecode/cells/ that carries an .asd file.
Rules
- A folder that is present is on. Every Nodecode process loads it at boot.
- Remove the folder to remove the cell.
- No config key names cells. A config key
cellsis ignored with a warning. - A cell runs inside Nodecode with full authority over the host. See Security.
- A profile has its own
cells/folder. See Profiles.
| Kind | What it is |
|---|---|
| Layer | The definitions the agent wrote and kept, one file each, in a git repository. You do not write it. |
| Peripheral | Any other cell. It exports start-cell, which the gateway calls with the parsed config. |
| Library | A folder with no start-cell. It loads. Nothing starts. |
The gateway is the local server that shells attach to. A shell is the terminal UI.
Find one
Every cell you can add is listed under Cells in the bar.
| Where | What it shows |
|---|---|
| Cells | Nodecode's cells and the community's, each pinned to one commit. |
/cells in the shell | The cells installed here, their state, and every standing notice. |
(help :TOPIC) through eval | A running cell's manual. |
How a cell is written: Cell API.
Turn one on
| Way | How |
|---|---|
| Setup | Run nodecode setup or /setup. Pick a tier. |
| Shell | Run /cells. Press Space on the highlighted cell. |
| Web page | Open Control, then the Cells tab. |
| Command line | Run nodecode add nc://NAME. |
Setup tiers:
| Tier | Installs |
|---|---|
| Recommended | Shipped cells that need no key, account or server first. |
| Everything | Every shipped cell this build can load. Never a hub cell. |
| Choose | A checklist of the shipped cells, then the hub's entries. |
| Esc | Nothing. |
nodecode add nc://NAME [--yes]
| Case | Result |
|---|---|
NAME | The cell's name. The nodecode- prefix is optional. |
| Hub cell | Its repository, pinned commit and contents are shown first. It installs on a yes. |
--yes | Answers yes on the line. |
No terminal, no --yes | Nothing is installed. |
| Nodecode is running | The cell turns on at once, in every attached shell. |
| Nodecode is stopped | The cell loads at the next launch. |
A shipped cell is installed as a symlink to the build's own folder. Windows gets a copy.
Turn one off
Use the same toggle: Space in /cells, or the Cells tab of the web page.
| Case | Result |
|---|---|
| Symlink, shipped copy or hub clone | The folder is removed. The cell stops. |
| Another installed cell depends on it | Refused. Turn that one off first. |
| A folder you put there yourself | Refused. Remove it by hand. |
| After turning off | The code stays loaded until Nodecode restarts. |
To keep the folder but start nothing, set "enabled": false in its config section:
"NAME": { "enabled": false }
After a config change, run (restart-cells) through eval, or (restart-cells "NAME") for one folder.
Hub
Cells outside the release are listed in two indexes.
| Index | URL | Override |
|---|---|---|
| Nodecode's own | https://preview.nodecode.ai/dl/cells/index.json | $NODECODE_HUB_INDEX |
| Community | https://nodecode.ai/cells/community.json | $NODECODE_COMMUNITY_INDEX |
Nodecode's own index is private for now. Only the operator's and the testers' addresses reach it.
Entry fields:
| Field | Meaning |
|---|---|
name | The primary system's name. |
git | The repository. HTTPS only. |
commit | A full commit id. The entry is pinned to it. |
description | What the folder's .asd says. |
license | The license. |
depends_on | What the folder's .asd depends on. |
platforms | Optional. Any of linux, macos, windows. |
path | Optional. The folder inside the repository. |
Install checks:
- HEAD is the pinned commit.
- The primary system has the entry's name, description and
depends_on. - The clone holds no symbolic link.
- Every dependency is found.
- No git hook runs. No submodule is fetched.
A hub cell gets a .hub marker file. A release never moves it from its pinned commit.
Install from git
Clone the repository into the cells folder. It loads at the next launch.
git clone <url> ~/.nodecode/cells/<name>
Updates
Shipped cells follow the binary. The check runs at launch, before the folder loads.
| Installed as | At launch |
|---|---|
| Symlink into another build | Pointed at this build's folder. |
| Copy made by another build | Made again from this build. |
| Folder this build no longer ships, from another release | Removed. The boot line says so. |
| Hub cell | Left at its pinned commit. |
Your own cells and hub cells compile into ~/.cache/nodecode/peripherals/<build stamp>/ at their first load under each build.
Loading
Order:
- Every folder is registered.
- Dependencies load first.
- Other folders load in alphabetical order.
- Layers load after every peripheral.
The gateway starts each peripheral after recovery.
| Failure | Result |
|---|---|
| A folder fails to load | The other folders still load. /cells lists the failure. |
| A config section is wrong | /cells shows REFUSED. A notice names the folder. The other cells still start. |
| An installed folder is gone | The boot reports it as failed. |
The gateway always boots.