What self-hosted open-source AI agents keep on your server

The part you own: control plane, database, files

Self-hosting an AI agent puts a named set of things on your machine. Knowing the list is most of the decision. For Kortix that list is the control plane, the Postgres database and the stored files. The control plane is the part that decides: accounts, projects, git repositories, secrets, connector grants and policies. kortix self-host init writes docker-compose.yml, .env, a Caddyfile and updater.sh into ~/.config/kortix/self-host/default/. One Compose project, kortix-<instance>, holds every service in it.

That directory is also the backup unit. .env carries the signing keys and the secret that decrypts stored credentials. volumes/db/data is Postgres, and volumes/storage keeps the files people uploaded. Archive the three and the instance is archived with them. That is why backup.sh refuses to run without API_KEY_SECRET.

Self-host is free. The stack has no Redis and no separate worker, so one project runs on the box instead of a queue and a worker pool beside it.

The part that stays remote, and why

Execution leaves the box on every session. kortix-api creates each session on a Platinum sandbox with PLATINUM_API_KEY, and that sandbox calls back to the instance's public KORTIX_URL. That callback is why the install wants an api.<domain> record even though the database never leaves the server. Local mode makes the dependency visible. Every port binds to 127.0.0.1, the app answers on 13737, and no session starts, because a remote sandbox has no route back in.

Inference leaves too. The gateway runs inside your stack, and the requests it makes go to the providers your projects connect, on keys you add after the first sign-in. Each project keeps its own key. The prompt reaches that provider's API. Self-hosting the platform does not move that leg onto your server.

Put plainly: the platform, the database and the files are yours. The sandbox is a remote machine your instance leases and calls back to. The model provider sees the prompt. Write those three sentences into the runbook before anyone sizes the server or answers a security questionnaire.

A local model is a separate decision

Keeping the weights on your hardware and keeping the control plane on your hardware are two decisions. A team can make them in either order. A model server handles inference: weights, GPU memory, context window, throughput. The control plane handles everything around the model: who may run what, which repository holds an agent's configuration, where skills and memory live, which connector account a call uses, and what gets backed up on Sunday.

A team usually needs the second layer first. An agent with no repository, no secret store and no place to land its work is a chat window. The platform is what turns a model into something a team can run: a home for configuration, keys, permissions and memory that outlives any one session.

What the server needs before the first command

Six things, and five of them you settle before the first start.

• A Linux server with a public IP, Docker Engine and the Compose plugin.
• Ports 80 and 443 open inbound.
• DNS records for <domain> and api.<domain>, plus a wildcard *.p.<domain> for previews.
• 2048MB free on /, the floor where the daily updater stops.
• Roughly 6GB of RAM for the published service limits: 5888MB across the services, and preflight.sh fails below 6000MB.
• A PLATINUM_API_KEY, without which sessions do not start, and a model provider key per project, added in the web app.

A 4GB server fails in the preflight rather than three days later. That is what the check is for. ./bin/preflight.sh kortix.example.com resolves the apex, the API host and a random label under the wildcard. It checks both ports, disk and memory, and stops on the first missing record.

Three readings before you hand it to a team

A closed sign-up. A new domain-mode instance confirms accounts without sending mail. Until EMAIL_URL is set or DISABLE_SIGNUP=true, any address that reaches the host gets a confirmed account, the admin address included. Whoever claims an admin-listed address first becomes platform admin. ./bin/check-signup.sh https://kortix.example.com reads the auth settings and exits 0 for closed or email-verified, 1 for open, 2 when it cannot tell.

A callback that resolves. This failure has no visible symptom. Every service reports healthy, the app loads, and each session sits at nothing. Point api.<domain> at the server, then rerun the preflight after any DNS, proxy or certificate change.

A backup that carries its key. A database dump is not a backup of the instance. backup.sh stops the stack so the Postgres files are consistent, archives the directory, and writes a sha256 plus a 16-hex fingerprint of API_KEY_SECRET. restore.sh compares that fingerprint with the live key. When they differ it refuses the swap that would leave every stored credential unreadable. Run the drill on a spare instance before you need it.

./bin/doctor.sh default folds seven readings into one table with a fix line per failure, and six of seven is the usual first result. The install sequence, in the order the stack expects it, is on the stack page. Every variable is in Read the docs.