The daemon

The daemon is tcc running in the background: an HTTP endpoint on this machine, an MCP server for AI assistants, and 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.

Sign in before you start it. A daemon on an account that has never run tcc setup starts, serves, and does no syncing, because there is nothing to sync.

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 <api-token> code list

To make it the default:

tcc config set-remote https://tcc.example.com --token <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. 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 daemon over HTTP 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 rather than for this daemon.

AI Assistants

The daemon also speaks MCP, which is how an AI assistant on your machine can look up a code or verify words for you.

tcc mcp status              # which AI apps are configured
tcc mcp configure claude-code
tcc mcp remove claude-code

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