Self-host an open-source AI agent with its own machine and file
A self-hosted AI agent is two things: the machine its session boots on, and the file in your repo that says what the agent may touch. Kortix is open source, my pick, and both artifacts are readable before the first session starts; I work at Kortix, so weigh that accordingly. In many stacks that call themselves self-hosted, the machine half is rented.
The harness turns a model into a session
A session runs the pi runtime, and an extension is a package pinned to an exact version in the manifest, loaded when the runtime starts.
extensions:web-access:pi: npm:pi-web-access@0.30.0The manifest says what an agent may touch
Grants live in the agents map: an omitted skills, subagents, commands, extensions, connectors, secrets, apps or kortix_permissions grant is none, while tools defaults to every tool with a warning.
agents:support:prompt_file: agents/support.mdsubagents: [researcher]commands: "*"extensions: [web-access]connectors: [helpdesk]secrets: [HELPDESK_TOKEN]A template names the machine each session boots
The reference gives the order: a template can come from the request, the agent, or the project default, and with none of them sessions boot on the platform image.
A session picks its sandbox template in this order: the template the session request names, the sandbox of the agent the session runs, sandbox.default, the platform image.Which layer becomes yours
People use "self-hosted" for three different layers, and each layer is owned separately. The model is inference: a hosted API behind your own key, a subscription you already pay for, or a server on your hardware. The harness is the program that turns a model into a session with tools, and in Kortix a new session runs pi; OpenCode is deprecated. The machine is the sandbox one session runs on, created at the start of the session and discarded at the end.
A self-hosted AI agent, in the sense that matters here, is those parts placed by you: the harness, the file that governs what the agent may reach, and the machine its session runs on. Two of the three are code in a git repo. The third is compute, and in most setups that call themselves self-hosted it is rented from a provider even when the platform runs on your own server.
Kortix is open source, which matters here for a narrow reason. The manifest and the template are readable at a public URL before you install anything, at the same address a reviewer will open later.
The template decides the machine
The project manifest, kortix.yaml, carries a sandbox.templates list. Each entry has a slug and either an image or a dockerfile from the repo, plus cpu in cores, memory in GiB and disk in GiB. A project default is set once with sandbox.default, and a single agent can point at a different template through agents.<name>.sandbox. Leave the block out and sessions boot on the platform's default image, which clones the repo into /workspace at start.
An agent that runs a build and an agent that drafts a reply do not need the same memory, and the difference becomes a number in a diff instead of a support request. The template also states a ceiling. A session cannot grow past the box it names, so an agent that runs out of memory is a line to edit.
The file says what an agent may touch
The agents.<name> block carries behavior and grants: prompt file, model, mode and permission, plus connectors, secrets, skills and permissions. The prompt lives in the agent's markdown file, which any editor opens. A grant you leave out resolves to none for skills, subagents, commands, extensions, connectors, secrets, apps and kortix_permissions. tools is the exception: it defaults to "*", and kortix validate warns when an agent omits it.
The permission model is a file your review already covers. Grant a connector and the agent can call it. Grant a secret by name and the value stays out of the repo, in the project's secrets, so the file records what is allowed without holding what it unlocks. One line decides what a session can change before it starts. workspace.project_repository: true gives each session a checkout on its own branch, and false gives the session no repository access at all.
Connector credentials are brokered server-side and never enter the machine. The file names a connector, and the key stays outside the repo.
Where the session machine comes from
The Compose project on your server runs the web app, the API, the LLM gateway, the database, auth and storage. None of those services executes an agent turn. Each session runs on Platinum, the reference sandbox provider: kortix-api creates the sandbox with your PLATINUM_API_KEY, and the sandbox calls back to the instance's public API URL. The self-hosting docs put the split in one line: "Sessions run on Platinum sandboxes, not on the server."
The self-host README states the consequence without softening it: sandboxes are "managed compute, not part of this box". Platinum is the provider its opening paragraph names, and PLATINUM_API_KEY is the setting the sandboxes run on (checked 1 November 2026).
You hold the file, the review and the stack. You rent the machine, per session, on Platinum, with a key that is yours. A security reviewer will ask both questions, and they have different answers.
Renting the machine buys one that is already built: a session starts in seconds, and the work stays off a laptop. The disk it ran on still sits under the provider, under the terms you accepted, which is a boundary worth naming in writing. A team that needs the machine inside its own perimeter is making a second decision, and installing the platform does not make it for them. What the install does leave you is the model: any model provider with your own keys, attached per project after the first sign-in, or a custom OpenAI-compatible endpoint in front of a server in your own rack.
One isolated sandbox per session. Each session has its own isolated machine and branch.
What setup asks for
The README puts the floor at 2 vCPU and 4 GB of memory, with 4 vCPU and 16 GB or more for real use. The server needs a public IP, DNS records for the domain and its API subdomain, and ports 80 and 443 open, as the self-hosting docs lay out. kortix self-host init then asks about reachability, an admin email, the deployment shape, the Platinum API key its sandboxes run on, the optional connector catalog, and the update policy.
No model key appears in that list. A self-hosted instance has no managed models, so the key goes in after the first sign-in, per project (models docs). Any model provider with your own keys. A custom OpenAI-compatible endpoint takes the same slot, which is how a local model server joins a self-hosted instance.
Do DNS first, because it is the step that fails. A missing wildcard record for previews turns a link that should open into a path proxy that breaks it.
Self-hosted or managed, decided by the file
The file travels with the product across placements, so the choice is about who holds what.
- Self-host when the grants, the agent files and the review need to sit behind your own access control, or when a reviewer wants to read the permission file rather than a settings screen.
- Choose the managed cloud when you want the same repo and the same review without owning Postgres, backups and upgrades.
- Self-hosting makes the platform yours. It does not move the session machine, which runs on Platinum either way. If that machine has to stay on infrastructure you control, the install will not get it there, and that gap is the one most guides in this category skip.
The test is two questions. Who can change a grant, and where does the machine that executes it live?
Questions people ask before they choose
Can I host my own AI agent?
Yes. Kortix is open source and self-hosts as one Docker Compose stack on a Linux server you control. Sessions still boot on Platinum, the reference sandbox provider, so the platform is yours while the session machine is rented.
What is a self-hosted AI agent?
It is an agent system you run on infrastructure you control: a harness, a file that governs what the agent may reach, and a machine per session. The machine is rented even when the platform sits on your own server, and in Kortix it runs on Platinum.
Which self-hosted AI agent is best?
Pick the one whose permission file you can read and review. Kortix suits teams that declare connectors, secrets and workspace access in a repo, with session work landing through a change request a person approves.
What AI platform is best for agents?
One where configuration lives in a repo you own, the model takes your own key, and each session gets its own machine. Kortix is open source and meets all three, on its cloud or on your server.
opensourceclaudecowork.com
© 2026
Read the manifest, then run it
One repo holds the agents, the grants and the machine templates.