# The organism > What runs when you type nodecode, what it keeps, and what happens when it stops. Source: https://nodecode.ai/docs/organism Updated: 2026-10-07 An organism is a running Nodecode. There is one per home, and every terminal you open talks to it. Below are five things people do to it, each done two ways. ## A second agent A home has one store, and one process owns it: a `nodecode serve` that the first shell started. Anything else that wants the store finds it taken. **Mistake: `nodecode serve`** A shell: ```text $ nodecode serve cell ada: layer, 1 definition [CP-ISSUE-20260912-001] gateway ready (exit 0) ``` Afterwards: ```text $ ps -o pid,ppid,args PID PPID COMMAND 86 83 nodecode 1115 1113 nodecode 2111 86 setsid -w nodecode serve --store /home/you/.nodecode/history.db 2113 2111 nodecode serve --store /home/you/.nodecode/history.db ``` The store is taken, so it says ready and exits 0. Nothing new is running. **Instead: `nodecode -p work`** With both running: ```text $ ps -o pid,ppid,args PID PPID COMMAND 294 292 nodecode 306 294 setsid -w nodecode serve --store /home/you/.nodecode/history.db 307 306 nodecode serve --store /home/you/.nodecode/history.db 418 416 nodecode -p work 443 418 setsid -w nodecode serve --store /home/you/.nodecode/profiles/work/history.db 445 443 nodecode serve --store /home/you/.nodecode/profiles/work/history.db ``` The work profile's shell: ```text profile work · ~/.nodecode/profiles/work Ask anything, or describe a task - gateway's warm, ready when you are nodecode nodecode-axolotl-cyber (max) · ? help · ← sessions work · ~/work · Gateway 127.0.0.1:33609 • connected ``` A home of its own: its own store, port, layer and organism. See [Profiles](https://nodecode.ai/docs/profiles). ## Done with a terminal The organism is a child of the shell that started it, and it lives as long as that shell does. Later shells only attach. **Mistake: `/exit in the first terminal`** Second shell, mid-turn: ```text the organism stopped; this shell × How many lines in README.md? started it again (count-lines "README.md") ⎿ 3 README.md has 3 lines. • nodecode/nodecode-axolotl-cyber (max) · 1.1s completed · ↑84 c96.0% ↓19 Check the Markdown files for broken links. ⠸⠇ nodecode/nodecode-axolotl-cyber (max) · 3.1s thinking — esc interrupts · type to steer · ctrl+o details ``` One second later: ```text $ ps -o pid,ppid,args PID PPID COMMAND 86 83 nodecode 707 86 setsid -w nodecode serve --store /home/you/.nodecode/history.db 709 707 nodecode serve --store /home/you/.nodecode/history.db ``` The organism stops with it. The other shell starts a new one within a second, on the same port, and its turn picks up where it stopped. A value set with `setf` is gone. **Instead: `/exit in a later one`** First shell, after the second quit: ```text Kept *editor*. • nodecode/nodecode-axolotl-cyber (max) · 1.6s completed · ↑470 c76.5% ↓32 Completed nodecode nodecode-axolotl-cyber (max) · ? help · ← sessions Gateway 127.0.0.1:41075 • connected ``` Afterwards: ```text $ ps -o pid,ppid,args PID PPID COMMAND 18 15 nodecode 34 18 setsid -w nodecode serve --store /home/you/.nodecode/history.db 36 34 nodecode serve --store /home/you/.nodecode/history.db ``` Only that shell closes. The organism, and everything in it, goes on. With the background gateway on, the service manager runs the organism instead, and no terminal stops it. See [The gateway](https://nodecode.ai/docs/gateway). ## A launch looks stuck The owner holds a lock on `history.db.lock`. The operating system frees it when the owner exits, however it exits. **Mistake: `rm ~/.nodecode/history.db.lock`** After the next nodecode: ```text $ ps -o pid,ppid,args PID PPID COMMAND 20 15 nodecode 34 20 setsid -w nodecode serve --store /home/you/.nodecode/history.db 36 34 nodecode serve --store /home/you/.nodecode/history.db 122 119 nodecode 130 122 setsid -w nodecode serve --store /home/you/.nodecode/history.db 132 130 nodecode serve --store /home/you/.nodecode/history.db ``` The new shell: ```text ■ Back after a hard stop. Nothing was running. Ready nodecode nodecode-axolotl-cyber (max) · ? help · ← sessions Gateway 127.0.0.1:39287 • connected ``` The first organism still holds its lock, on a file that no longer exists. The next launch starts a second organism on the same store, on a new port. Two processes now write one history. **Instead: `/exit in every shell`** Afterwards: ```text $ ps -o pid,ppid,args PID PPID COMMAND $ ls ~/.nodecode | grep history composer-history history.db history.db.lock history.db.stdio.log ``` Nothing runs and nothing holds the lock. The file stays, and the next `nodecode` takes it. If a launch still fails, the reason is in `history.db.stdio.log`. ## Remember a value The organism keeps a definition, not a state. A top-level `defun` or `defparameter` is written to your layer and loads at every start. Anything else lives only as long as the process. **Mistake: `(setf *editor* "helix")`** Before: ```text Remember that my editor is helix. (setf *editor* "helix") ⎿ [warning: undefined variable: NODECODE.EVOLVED::*EDITOR*] "helix" Set. ``` After a restart: ```text What is my editor? (list (boundp '*editor*) (fboundp 'count-lines)) ⎿ (NIL #) No editor is set: that value died with the last process. count-lines is still here. ``` Set in this process only. After a restart, `boundp` says `NIL`, while a `defun` from the same hour is still there. **Instead: `(defparameter *editor* "helix")`** Before: ```text Keep my editor: helix. Defined *editor* ⎿ [layer: kept *editor*; sent to 2 shells] *EDITOR* ■ [_editor_.lisp — this shell: live here: *editor*] ``` After every shell quit and a new start: ```text Which editor do I use? *editor* ⎿ "helix" [watching: shown again when its value changes] helix. It came back with the restart. ``` A file in your layer, `~/.nodecode/cells/ada/` here, and a git commit. It loads at every start, in every shell. See [Eval and the layer](https://nodecode.ai/docs/eval). ## Change a kernel function The kernel, `nodecode.kernel`, holds the store, the lock and the loader. The organism locks it at boot. Everything else, the turn loop included, is `nodecode.evolved`, and the model may redefine it. **Mistake: `(defun nlk:home-abbreviated …)`** First shell: ```text Defined nlk:home-abbreviated failed ⎿ ERROR: SYMBOL-PACKAGE-LOCKED-ERROR: Lock on package NODECODE.KERNEL violated when setting fdefinition of HOME-ABBREVIATED while in package NODECODE.EVOLVED. See also: The SBCL Manual, Node "Package Locks" ``` The lock refuses it, and nothing is written to the layer. **Instead: `(define-hook nlk:home-abbreviated …)`** First shell: ```text Defined nlk:home-abbreviated ⎿ [layer: kept home-abbreviated full-path; sent to 2 shells] "full-path" ■ [home-abbreviated-full-path.lisp — this shell: live here: home-abbreviated full-path] ``` A shell opened later: ```text profile default · /home/you/.nodecode/ layer ada · 1 definition · 882689d Ask anything, or describe a task - gateway's warm, ready when you are ``` The hook runs around the kernel function, is kept in the layer, and loads in every process: here the home screen shows the full path. ## One tool, one log The organism has one tool, `eval`. A shell command, a file edit and a new definition are each a Lisp form in an `eval` call. Every fact is an event in `~/.nodecode/history.db`: a prompt, an answer, a tool call, its result. The transcript in every shell and the model's context are both read from it. History the model no longer sees stays in the log. See [Context and recall](https://nodecode.ai/docs/context). The gateway answers on `127.0.0.1`, on the port this store used last. There is no port option. Shells find it in `history.db.owner`. See [Files](https://nodecode.ai/docs/files).