The daemon

The daemon is tcc running in the background: an HTTP endpoint on this machine and an MCP server for AI assistants. Given an account of its own it also runs a sync loop that keeps the local cache current.

It exists for machines with no desktop session — a Linux server, a build agent, a container. On macOS and Windows the desktop application already runs the same thing while its window is open, so you do not normally start the daemon by hand there.

Starting and Stopping

tcc daemon start
tcc daemon status
tcc daemon stop

start runs in the foreground and blocks until the process is stopped. It writes a PID file, so a second start refuses rather than fighting the first one for the port, and a stale PID file left by a crash is cleaned up on the next start.

stop asks the running daemon to shut down. status prints whether it is running, its process ID and its port — and says plainly when it finds a PID file for a process that is no longer alive.

What Account It Runs As

tcc daemon start runs machine-to-machine by default. It has no account of its own: it answers on behalf of whoever presents a platform API token, it keeps no local cache, and it runs no sync loop. Local endpoint tokens are refused in this mode, with a message saying so.

To give the daemon an identity of its own instead, sign in with tcc setup first and start it with TCC_MODE=hybrid set. It then keeps a local cache, syncs in the background, and accepts the local endpoint tokens described below. That is the mode the desktop application always runs in, and the mode to choose if you want the daemon to behave like the machine’s own signed-in client.

A hybrid daemon on an account that has never run tcc setup still starts and still serves. It does no syncing, because there is nothing to sync.

A daemon’s own session lasts at most 12 hours from sign-in; then sign in again with tcc auth login --code (see Signing in). Platform API tokens are not sessions and never end this way, so use one for anything that runs unattended.

What It Listens On

By default the daemon binds to 127.0.0.1 — the loopback address — on port 19821. Nothing outside this machine can reach it. That is what makes the local endpoint safe to use without a password from tools running beside it.

Two environment variables change that:

• TCC_HTTP_PORT — a different port, when 19821 is taken.
• TCC_HTTP_BIND — a different bind address.

Changing the bind address is the one setting here with real consequences. The moment the daemon listens on anything other than loopback it is reachable from your network, and the assumption the local endpoint rests on no longer holds. If you do it, put it behind something that authenticates.

As a System Service

On Linux:

tcc daemon install-service

This writes a systemd user unit, enables it and starts it, so the daemon comes back after a reboot. It restarts on failure. Check it the usual way:

systemctl --user status trusted-codes

The command is Linux-only. On macOS and Windows, use the desktop application’s own start-at-login instead.

Commands Find the Daemon On Their Own

When a daemon or the desktop application is already running, an ordinary tcc command does not duplicate the work — it hands the request to the running instance and prints the answer. You will see a line saying it connected. When nothing is running, the same command does the work itself.

You do not have to configure this, and the result is the same either way.

Reaching a Daemon on Another Machine

A tcc on your laptop can talk to a daemon running elsewhere — a shared machine, a CI runner — rather than acting as its own client.

For a single command:

tcc --server https://tcc.example.com --token <platform-api-token> code list

To make it the default:

tcc config set-remote https://tcc.example.com --token <platform-api-token>
tcc config show-remote     # the URL, with the token masked
tcc config clear-remote    # back to the local daemon

The setting is stored under your home directory and read on every invocation. The --server and --token flags, and the TCC_REMOTE_URL and TCC_API_TOKEN environment variables, override it for one run.

A token is required whenever a remote server is set. Use one from tcc api-token generate, not one from tcc config create-api-token. When a remote is configured, commands go there and nowhere else — if the remote cannot be reached the command fails rather than quietly running against your own account instead.

Tokens for the Local Endpoint

Tools on this machine that speak to the desktop application, or to a daemon started in hybrid mode, use a token you issue:

tcc config create-api-token --label claude --scope read
tcc config list-api-tokens
tcc config show-api-token claude
tcc config revoke-api-token claude

--scope is read, write or full, and defaults to full. --ttl-hours gives the token an expiry; leaving it out means no expiry, which is only sensible for a token that never leaves this machine. list-api-tokens masks the values — show-api-token is the one that prints a whole token, so keep it out of shared terminals and logs.

These are separate from tcc api-token, which issues tokens for the Trusted Codes platform itself. A machine-to-machine daemon — the default for tcc daemon start — refuses local tokens and takes a platform token instead, and so does a remote daemon reached with --server.

AI Assistants

tcc also speaks MCP, which is how an AI assistant on your machine can look up a code or verify words for you. This does not go through the daemon: configure writes an entry telling the assistant to launch tcc mcp itself, and that process talks to your account directly. You do not need a daemon running for it.

tcc mcp status              # which AI apps are configured
tcc mcp configure cursor
tcc mcp remove cursor

For Claude Code, use claude mcp add as shown in Connecting an Assistant. The current configure claude-code writes a file that Claude Code does not read.

configure supports claude-desktop, claude-code and cursor. The MCP server is a separate part of your plan from the desktop application itself.