# Cells

> What a cell is, where to find one, how to turn one on or off, the hub, how cells load.

Source: https://nodecode.ai/docs/cells
Updated: 2026-10-06

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 `cells` is ignored with a warning.
- A cell runs inside Nodecode with full authority over the host. See [Security](https://nodecode.ai/docs/security).
- A profile has its own `cells/` folder. See [Profiles](https://nodecode.ai/docs/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](https://nodecode.ai/cells/browse) in the bar.

| Where | What it shows |
| --- | --- |
| [Cells](https://nodecode.ai/cells/browse) | 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](https://nodecode.ai/docs/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. |

```sh
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:

```jsonc
"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.

```sh
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:

1. Every folder is registered.
2. Dependencies load first.
3. Other folders load in alphabetical order.
4. 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.