Reference·Gateway operationsIndexClose
Gateway operations
Choose an owner, inspect it, recover from a crash, apply config changes, and know what survives a restart.
The gateway is the local server that shells attach to. The process that serves it owns the organism, a running Nodecode.
Choose an owner
One process owns a home's store at a time. The home is ~/.nodecode/. A shell is the terminal UI.
| Owner | Start it | Lives until | Restarted after a crash |
|---|---|---|---|
| A shell | nodecode | You quit the shell. | By the attached shells. See Recover. |
| The background gateway | nodecode gateway on | You run nodecode gateway off. | By the service manager, after 5 s. |
| A headless process | nodecode serve | You stop it. | By the attached shells. With no shell attached, nothing restarts it. |
Later shells attach to the owner. See The organism.
Use the background gateway for bots, cron jobs and the link. See The gateway.
Windows: no background gateway. Use nodecode serve in a terminal you keep open.
Inspect
nodecode gateway
nodecode gateway logs
nodecode gateway logs --follow
| Status line | Do this |
|---|---|
off | Run nodecode gateway on. |
on, but it failed | Run nodecode gateway logs. Then nodecode gateway restart. |
on, restarting after it exited | Run nodecode gateway logs. |
on, but stopped | Run nodecode gateway restart. |
waiting | A shell owns the organism. The gateway takes over when that shell closes. |
unavailable, naming a missing user manager | Run sudo loginctl enable-linger $USER. Then nodecode gateway on. |
Inside a shell:
| Command | Shows |
|---|---|
/gateway | The same status. |
/doctor | What is missing, with a remedy for each item. |
/cells | Each cell folder: loaded, failed, skipped files, standing notices. |
/doctor checks these:
- The model the shell will use.
- Cell folders that failed, with the reason.
- The store, read back whole.
- The build on disk.
- Free disk space.
config.jsoncand every declared section.- The default provider's key.
- A waiting release.
Log files:
| File | Holds |
|---|---|
| The user journal (Linux) | The background gateway's output. Read it with nodecode gateway logs. |
~/Library/Logs/nodecode/nodecode-gateway.log (macOS) | The same. |
~/.nodecode/history.db.stdio.log | Stdout and stderr of a process that runs a shell. This is the boot log. |
~/.nodecode/history.db.resurrect.log | Output of replacement owners spawned after a crash. |
Set NODECODE_PHASE_LOG to a file path to log one line per boot phase.
The web page shows the same under Control, in the Gateway and Logs tabs.
Recover
Dirty death
A dirty death: the owner died, the lock is free, history.db.owner is still there.
- Each attached shell sees the connection drop.
- With the background gateway on, the shell asks the service manager to start it.
- Otherwise the shell spawns a detached
nodecode serve --store PATH. - One candidate wins the lock. It publishes its port. The others exit.
- Every shell attaches to the winner.
| Limit | Value |
|---|---|
| Spawns per outage, per shell | 3 |
| Time between spawns | 30 s |
After the third spawn the shell stops spawning. It keeps watching for an owner. Start one by hand:
nodecode serve
A clean stop is never respawned. With no background gateway, an attached shell takes the organism over.
Interrupted turns
A turn that was running when the owner died is resumed at the next boot.
| Rule | Detail |
|---|---|
| Unanswered tool calls | Each gets the result interrupted by process restart. |
| Resume attempts | 3 boots. After that the turn is recorded as failed. |
| Cost | A resumed turn calls the provider again. It spends tokens. |
| Background evals | Lost. Their output is live only. |
Apply config changes
A cell is a folder of code under ~/.nodecode/cells/. It reads its config section when it starts.
| Change | Apply with |
|---|---|
| A cell's section | (restart-cells) |
| One cell's section | (restart-cells "folder") |
| Anything, background gateway | nodecode gateway restart |
| Anything, shell owner | Quit the shell. Run nodecode again. |
| A cell turned off | A restart. Its code stays loaded until then. |
restart-cells stops the cells, reads the config again and starts them. The agent runs it through eval:
(restart-cells)
| Form | Does |
|---|---|
(config-get '("a" "b")) | Reads the config at a path. A secret reads as "[set]". |
(config-set '("a" "b") value) | Writes one member. Keeps every comment. Answers the diff. |
See Config.
What survives a restart
| Survives | Where |
|---|---|
| Sessions, turns, tool results, model pins, checkpoints | ~/.nodecode/history.db |
| Cron jobs | ~/.nodecode/history.db |
| The layer: the definitions the agent wrote and kept | ~/.nodecode/cells/<name>/ |
| Memory | ~/.nodecode/memory/ |
| Skills | ~/.nodecode/skills/ |
| The operator token | ~/.nodecode/operator-token |
| The gateway's port, when it is still free | ~/.nodecode/history.db |
| The link switch and allowed browsers | ~/.nodecode/link/state.json |
| The gateway off mark | ~/.nodecode/gateway-off |
| Lost | Why |
|---|---|
| Background evals and their output | Live only. |
Values set with setf | Only defining forms are kept. |
Hooks added with (hook ...) | Live only. define-hook is kept. |
| A held definition that never ran | It is written only after its first clean run. |
Back up the home with /backup. It writes one archive under ~/.nodecode/backups/. The archive holds your keys.
Restore an archive as a profile:
nodecode profile import FILE --name NAME