termdeck
Reference
Security and privacy
You are installing a program that can drive a coding agent on your machine. That deserves a straight account of what it can do, what it cannot, and what you are trusting.
The design in one sentence
The agent is a narrow set of typed capabilities rather than a remote shell, so the worst a compromised Termdeck could do to your machine is bounded by that list rather than by your file permissions.
What the agent will do
This is the complete surface. Everything Termdeck does is composed from these.
| Capability | Bounded by |
|---|---|
| Read, stat, list, and watch files | The transcript directories of the installed engines, and nothing above them. |
| Browse and read project files | The folder the chat was opened in, read only, enforced on both ends. |
| Start a process | The three known engines only. There is no capability that runs a command of the caller's choosing. |
| Write to a process, read it, stop it | Processes it started itself. |
| Report machine facts | Installed CLIs, login state, rate limit percentages, agent log. |
| Restore a checkpoint | Files that the engine itself snapshotted for that session. |
| Write the project instruction file | A fixed two entry filename table, resolved from a real session's own record. The caller names a session and an engine, never a path. |
| Switch saved account | Moving a credential file the CLI itself wrote. |
A request that is not on this list has no handler. There is no escape hatch, no generic exec, and no path parameter that reaches outside its confinement.
What the agent will not do
- Run an arbitrary command. The capability does not exist.
- Read an arbitrary file. Reads are confined to transcript roots and the open chat's project folder.
- Write an arbitrary file. Two narrow writes exist, both described above.
- Accept an inbound connection. It dials out and listens for nothing.
- Send your source code anywhere. Repository content crosses the wire only when you open a file or a diff in the dock, and then only to your own browser.
What crosses the wire
| Crosses | Does not cross |
|---|---|
| Transcript content for chats you open, streamed on demand | Your provider passwords, API keys, or subscription tokens |
| Live turn output while you are watching | Repository content you have not opened |
| File contents and diffs you explicitly open in the dock | MCP auth headers, environment values, and credentials in URLs |
| Rate limit percentages | The tokens those percentages were read with |
| Token counts for the usage page | The transcripts those counts were derived from |
Rate limits are read on your own machine against the provider's endpoint, and only the resulting percentage is sent. Usage totals are computed on your machine as well; the scan does not upload the transcripts it scans.
What the master stores
- Your account: email, authentication, subscription, and plan grants.
- Your machine list, with each machine's token stored as a hash rather than the token itself.
- Push subscriptions for the devices you enabled notifications on.
- Per chat preferences you set here, such as a custom title, pinned state, or archived state.
- Aggregate operational counters, for example turns per day, used for billing and for the admin console.
It does not store transcripts, source code, provider credentials, or diffs. Nothing is persisted from a chat you open beyond what is listed above.
What you are actually trusting
Two things, and it is worth naming them plainly rather than burying them.
The agent updates itself from the master
That is a real trust relationship: whoever controls the master controls what code the agents fetch. It is the reason the agent is deliberately tiny and its capability list is deliberately fixed, why the installer offers to print the whole source before running it, and why a bad update rolls itself back and quarantines the version rather than needing hands on the machine.
If you want to inspect what your machines are running, the same files the installer downloads are readable at any time:
curl -fsSL https://termdeck.io/download/agent/manifest.json
curl -fsSL https://termdeck.io/download/agent/capabilities.jsThe coding agent is the powerful part
Termdeck's own capability list is narrow. The coding agent it drives is not: an agent in full access mode can do anything you can do in a shell. That is what the permission system is for, and it is the layer that deserves your attention.
The refusals that do not depend on you
A set of guards refuse certain calls before any of your settings are consulted, and before the default read only auto allow list gets a look. The motivating case: Read is auto allowed because reads cannot mutate anything, and reading an SSH private key is a read.
Credential files, remote scripts piped into a shell, sudo, shell startup files, system paths, deleting outside the project, and broad recursive deletes are all refused by default. Each can be switched off individually, only from the settings page, and no auto allow rule can override one. Full detail on Approvals and permissions.
Notification actions
The Allow and Deny buttons on a push notification work without the app being open, so the notification carries its own authorisation: a single use token that expires after 15 minutes and is invalidated on first use. It authorises exactly one answer to exactly one pending prompt.
Account isolation
Every route is addressed by machine name and scoped to the owning account. Nothing is ever keyed on a bare session id, because session ids are generated locally and can collide between users. Message fan out is scoped the same way.
Rendering your code
File contents and diffs are built as document nodes, never as markup, on every path and for every file type. A file that contains HTML is displayed as text.
Practices worth adopting
- Open chats in the narrowest folder that contains the work. It bounds what the agent can reach and sharpens the risk scoring on every approval.
- Leave the hard denies on. They cost nothing on a normal day.
- Keep auto allow rules tight, with a specific glob and a low risk cap.
- Use full access only in a repository you would be happy to delete.
- Treat the machine token like an SSH key. Regenerate it if it has been anywhere it should not.
- Remove machines you no longer use, which revokes their tokens.
Reporting a vulnerability
Email [email protected] with the detail. Please do not open a public issue for a security report.