The Durable Runtime
How cordy-runtime keeps terminals, TUIs, and agents alive — supervision, runtime states, and environment overrides.
Underneath Cordy's terminals and agents runs cordy-runtime, a durable, cross-platform process supervisor written in Rust and bundled with the app. It is the reason your shells, TUIs, and CLI agents survive a window reload, a renderer crash, or — on Windows — closing to the tray.
cordy-runtime is a terminal and process supervisor, not an LLM gateway. It makes no model calls, assembles no prompts, and manages no context windows — that is entirely the job of the external CLI agents it launches.
Why terminals and agents are durable
Your terminal sessions (the PTYs) and CLI agent child processes do not live inside the Electron window. They live inside the separate cordy-runtime process. The window only attaches to and detaches from a session over a local channel — it never owns the process itself.
- Switching workspaces, unmounting a panel, or reloading the renderer only detaches.
- Only when you close a terminal tab, or the process exits, does the session end.
So a long-running build, a vim session, or a running agent keeps going while the runtime remains alive and the UI detaches and returns. A full application quit ends the PTY and process.
Attach as snapshot
Each session runs a headless terminal emulator inside the runtime, fed every byte of PTY output and resized in lockstep with the real terminal. When the UI re-attaches, the runtime returns one of two things:
- a delta — just the frames buffered since the UI last saw the session (used when the same view is still alive and the gap is small); or
- a snapshot — the full serialized screen state at the terminal's current size (used after a fresh reload, a tray restore, or when the buffered delta window has been evicted).
Reattaching from the runtime emulator snapshot lets full-screen TUIs return without replaying the renderer's old byte stream.
Cold restore after a full quit
Before a renderer releases a terminal, it stores a bounded local screen/history snapshot with its captured dimensions, excluding alternate-screen and terminal-mode sequences. After a full quit, Cordy restores that text and starts a fresh shell below it. The history is durable; the old process is not. See Terminal.
Supervision and auto-restart
The Electron main process supervises the runtime and restarts it if it exits unexpectedly. Restarts use exponential backoff so a runtime that crashes on every launch cannot hammer your machine:
- Backoff grows 1s → 2s → 4s → 8s → 16s, capped at 30s.
- Once the runtime has stayed healthy (
ready) for 60 seconds, the backoff resets to its base delay. - There is no fixed cap on restart attempts; each crash schedules exactly one more bounded restart.
Every auto-restart (attempt number, backoff, exit code, signal) is written to the diagnostics log. After a runtime restart, terminals are usable again and agent status is accurate; runs from before the restart are not shown as still running.
To restart the runtime yourself, click the runtime status indicator and use its restart action. If agents are running, Cordy says how many will stop and asks first.
The runtime keeps terminals alive across renderer reloads and tray-close detaches. Restarting or crashing the runtime ends its sessions.
Runtime states
The runtime status indicator shows Runtime: <state>. The first time the runtime enters a failure state, Cordy also shows a toast.
| State | Meaning | What to do |
|---|---|---|
starting | The runtime process is launching. | Wait a moment. |
ready | Healthy and connected; terminals and agents work normally. | Nothing. |
unresponsive | The runtime process is still running but has sent no response for some seconds. It returns to ready as soon as it responds again. | Wait. If it stays unresponsive, restart the runtime. |
binary-missing | No runtime binary was found. The app lists every path it tried. | Reinstall Cordy. |
incompatible | The runtime's protocol version does not match this app build. | Reinstall Cordy so the app and runtime come from the same build. |
crashed | The runtime exited unexpectedly; a bounded auto-restart is scheduled. | Usually self-heals. If it keeps restarting, check the diagnostics log. |
stopped | The runtime was stopped deliberately (for example, at app shutdown). | Restart the app or the runtime. |
There is no separate "crash-loop" state — a crash loop shows up as crashed recurring in the diagnostics log with an increasing restart count.
Environment overrides
These environment variables are optional; the defaults are correct for normal use.
CORDY_WINDOW_CLOSE_MODE
Controls what happens when you close the window to the tray on Windows. Values: hide or destroy. Default: destroy.
destroy(default) tears down the renderer after a data-safety suspend handshake to release its memory, while the runtime, PTYs, and agents keep running. Reopening reattaches to everything.hidekeeps the renderer resident in memory instead.
CORDY_USER_DATA_DIR
Overrides where Cordy stores its user data (projects, workspaces, notes, layout, settings, themes). When unset, Cordy uses the per-OS location listed in Privacy.
The shell for new terminals is chosen in Settings → Shell, not by an environment variable. Cordy has no per-repository config file; it does not read or run anything from a .cordy/ folder.
No model calls, ever
cordy-runtime supervises terminals and processes. It makes no language-model calls and does not manage agent credentials or context windows. It does process terminal output for rendering, scrollback, and status; the renderer can persist a terminal history snapshot locally. Each CLI agent talks to its own provider in its own process. See Agents and Privacy.
Related pages
- Troubleshooting — runtime failure states and diagnostics.
- Agents — the CLI agents the runtime launches.
- Privacy — where user data is stored.