termdeck
Reference
Settings reference
Everything with an exact name: variables, paths, service names, URLs, routes, shortcuts.
Agent environment variables
Set these in ~/.termdeck/agent.env on macOS and Linux, and restart the agent. On Windows the equivalent file is %USERPROFILE%\.termdeck\agent.env.cmd using set NAME=value lines.
The machine token, starting with agt_. Written by the installer. Regenerate it from the machine card if it is ever exposed.
Where the agent dials. Written by the installer as https://termdeck.io.
Moves the agent directory, token file, log, and policy file somewhere else. Set it before installing.
Use this exact Claude Code binary rather than looking it up on the path.
Same, for Codex.
Same, for Grok.
A hard per turn spend ceiling for this machine. The smaller of this and any per turn setting wins. Values are clamped to a sane range so a mistyped tiny number cannot kill every turn instantly.
How long a running engine is kept alive with nobody attached before it is stopped. Raise it if you routinely disconnect for longer than three minutes mid run.
How much output is buffered for a parked run. Beyond this the run is stopped rather than replayed incompletely.
Skips the installer's read the source prompt. Used by the repair script for unattended runs.
Engine environment variables
These belong to the coding CLIs. Termdeck follows them rather than defining them, so a machine with a relocated config directory works without extra configuration.
| Variable | Effect |
|---|---|
CLAUDE_CONFIG_DIR | Where Claude Code keeps its configuration, projects, and file history. Defaults to ~/.claude. |
CODEX_HOME | Where Codex keeps its configuration and session rollouts. Defaults to ~/.codex. |
GROK_HOME | Where Grok keeps its configuration and credentials. Defaults to ~/.grok. |
File locations
| Path | Holds |
|---|---|
~/.termdeck/agent/ | The agent and its two dependencies. |
~/.termdeck/agent.env | Token and master URL, mode 600. |
~/.termdeck/logs/agent.log | The agent's activity log. |
~/.termdeck/logs/agent-crash.log | Windows only. Crashes that happen before the agent's own handler runs. |
~/.termdeck/persistence.json | How the agent was registered, so the dashboard can warn about fragile installs. |
~/.termdeck/policies.json | Auto allow rules and hard deny switches, mode 600. |
~/.claude/projects/<slug>/<id>.jsonl | Claude Code session transcripts. |
~/.claude/file-history/<id>/ | Claude Code checkpoint snapshots, used by Restore files. |
$CODEX_HOME/sessions/ | Codex session rollouts. |
$CODEX_HOME/config.toml | Codex configuration, including MCP servers. |
~/.claude.json | Claude configuration, including MCP servers. |
<project>/.mcp.json | Project scoped MCP servers. |
<project>/CLAUDE.md or AGENTS.md | The project instruction file Termdeck can edit. |
Service names
| Platform | Registered as | Managed with |
|---|---|---|
| Linux | termdeck-agent, a systemd user unit | systemctl --user status termdeck-agent |
| macOS | io.termdeck.agent, a launch agent | launchctl list | grep termdeck |
| Windows | TermdeckAgent, a scheduled task | Get-ScheduledTask -TaskName TermdeckAgent |
| Fallback | A @reboot cron entry | crontab -l |
URLs
| URL | Purpose |
|---|---|
/install.sh, /install.ps1 | The installer. Needs TERMDECK_AGENT_TOKEN in the environment. |
/uninstall.sh, /uninstall.ps1 | Stop the service and remove the agent. |
/heal.sh, /heal.ps1 | Uninstall and reinstall, reusing the token on the machine. |
/download/agent/manifest.json | The current agent file list. |
/download/agent/<file> | Any agent file, readable without an account. |
/VERSION | A quick reachability check from a machine. |
App routes
Every one of these is linkable and survives a reload.
| Route | Opens |
|---|---|
/dashboard | The app, on the fleet board. |
#/new | The new chat page, remembering the machine, folder, and engine you picked. |
#/<session id> | One chat. An eight character prefix is enough. |
#/approvals | The approval inbox. |
#/terminals | The multi window session canvas. |
#/usage | Usage and cost. The date range rides in the URL. |
#/archive | Archived chats. |
#/settings/<section> | A settings section directly, for example #/settings/approvals. |
#/account | Profile and subscription. |
Keyboard shortcuts
| Keys | Action |
|---|---|
| Ctrl B | Collapse the sidebar, or open the drawer on a phone. |
| Ctrl Shift F | Open the project file explorer. |
| Ctrl F | Find inside the file open in the dock. |
| Ctrl R | Search prompt history, with the composer focused. |
| Alt 1 to 9 | Jump to a pinned tab, or raise a window on the Terminals page. |
| Esc | Close the open menu, sheet, or dialog. |
Slash commands
Typing / in the composer opens a palette. Every row carries the command's description and its arguments, read off disk, so your own commands and skills are described alongside the built ins below, including any this project defines.
| Command | Effect | Engines |
|---|---|---|
/compact | Summarise the conversation so far and continue with the shorter version. | Claude, Grok |
/clear | Clear the conversation. | Claude, Grok |
/context | Report context usage. | Claude, Grok |
/model | Change model from the composer. | Claude, Grok |
/session-info | Session details. | Grok |
Codex has none of its own. Its palette lists the skills installed for the chat, and picking one writes it into the composer as text for the model rather than running a command.
Two composer inputs are handled by Termdeck itself rather than sent to the engine, so they work on all three:
| Input | Effect |
|---|---|
# followed by text | Appends that line to the project instruction file. Never destructive, so it needs no confirmation. |
| Recap, from a chat's menu | A factual summary of what the chat did, derived from its own transcript rather than generated. |
Naming rules
- Machine names are lowercase letters, digits, and dashes, up to 32 characters. The name appears in every route addressing that machine.
- Display names are free text and only affect what you see.
- Machine tokens start with
agt_and are stored hashed on the server.