tc-operator

tc-operator is the command that installs and runs a Trusted Codes node on your own machine. One command on a fresh server turns the box into a complete, federation-capable home server.

This section is the path you walk: deciding whether you want one, installing it, configuring it, running it day to day, and taking it down again. What a federated server is — the mesh, admission, what crosses between servers — is covered in the Federated server section.

What You Get

The full backend on your box: the database, the sign-in service, the REST layer, the edge functions that hold all the business logic, the API gateway, file storage and realtime. It runs the same schema and the same code as the servers Trusted Codes runs, behind HTTPS on your own domain.

The node is backend-only. The clients are the mobile app, the desktop companion and MCP — there is no web client to deploy. The node does serve a set of web surfaces (the admin app, and optionally the user portal, business portal, verify and status pages) under your domain, and you choose which.

Your members’ accounts, connections, codewords and vaults live in your database and nowhere else.

What It Costs You

A machine you keep running. The reference box is Ubuntu 26.04 (anything from 22.04 works), 2 vCPU, 4 GB RAM, 20 GB disk. The installer provisions a 4 GB swapfile. Surface builds are memory-hungry; below 4 GB they get killed.

A domain and its DNS. The node needs an A record, and every surface you enable needs one of its own.

An email provider. One SMTP provider carries all of the node’s mail. A node without one cannot onboard anybody, and comes up with every federation surface forced off.

Backups you take yourself. The installer takes a database dump only when you uninstall. A live node needs your own schedule — and the dump alone is not enough to recover. See Backups and recovery.

Staying current. A node is not a private fork. Updates arrive as new distribution archives and you apply them.

What Is Not Yours to Run

Billing and mobile push credentials stay central. So does the entitlement ceiling your node runs under: it is granted and signed centrally, and your node’s admin role cannot raise it. The federation section explains why.

The Parts That Are One-Way

Read these before you start, not after.

• uninstall --purge destroys the node and its data. It takes a dump first and refuses without --purge when real users exist, but past that confirmation there is no undo.
• rollback reverts code only. The database schema is forward-only and is not reverted. Old code then runs against the current schema.
• Losing /etc/trusted-codes/secrets.env loses the node. Restored data is unreadable without the original encryption key, and the node gets a new federation identity. Back it up with every dump.
• home_server cannot be changed on a running node. Changing it is a new identity: new DNS, new TLS, new admission.

Where to Go Next

• Before you start — what only you can provide.
• Installing a node — the four steps and the two manual ones.
• operator.yaml — the one file you edit, and applying a change to a running node.
• Running the node — status, surfaces, admin accounts.
• Updating, backups and rollback — and what rollback does not do.
• Removing a node — the destructive path, stated plainly.