SSD Nodes Learn Hosting plans →
Guides Matt ConnorBy Matt Connor

Self-host OneCLI: one agent per person

OneCLI hands every person a sandboxed agent and keeps the keys in one gateway. Self-host it on a VPS: Docker Compose, PostgreSQL, and real sizing numbers.

What you get when you self-host OneCLI

Self-host OneCLI and every person in your team gets their own agent, each one running in its own sandbox, with the API keys held in a gateway that the agents never read. The install is a Docker Compose stack with PostgreSQL behind it, reachable at http://localhost:10254. Plan for a real box. The documented default is a 2 GiB memory cap per agent sandbox, so budget for the base stack and the agents' actual working memory separately.

Eight pieces ship in that stack, and knowing which is which makes the rest of this guide easier to read.

  • Web dashboard (Next.js), port 10254. Agent creation, chat, memory and skills editing, connections and secrets.
  • API server, port 10256. The control plane: database, conversation handling, work queues.
  • Rust gateway, port 10255. Intercepts outbound requests from agents and injects credentials.
  • Runner. The README describes it as the component that "starts, parks and reaps agent sandboxes. Outbound-only, and never touches the database."
  • Sandbox Supervisor. The README describes it as running "inside each sandbox, speaking a vendor-neutral harness interface so the agent runtime is swappable."
  • SSH terminator, port 10257. The README calls it "the SSH front door": it terminates SSH with short-lived certificates the API issues and bridges each session into an agent's sandbox. It runs under the same runner profile as the runner.
  • Channel adapter. A daemon that connects a Slack app, so an agent answers in channels and DMs under its own name.
  • PostgreSQL. The shipped compose file runs postgres:18-alpine with a pgdata volume.

The name says CLI, the product is a server

OneCLI is a server platform. The name points at a command line tool you install on a laptop, and that picture is wrong for the thing in this guide. A separate command line client does exist, in the onecli/onecli-cli repository, and it routes a local coding agent's traffic through a gateway. What you deploy here is a multi-user web application: an account system with organizations and invitations, a database of conversations and secrets, and a runner that starts containers.

The per-person model is the whole design. From the README: "You create an agent per person, give each agent the access it needs, and it works in a sandbox, routed through a gateway that injects the credentials and enforces your policy." Each agent has its own filesystem and shell, its own conversation page, memory the platform keeps, and skills you write once. Credentials work the opposite way round from the usual setup. Rather than copying an API key into each person's environment, you store the key once and grant it to the agents allowed to use it.

What the box needs before you start

  • Docker, with the Compose plugin at version 2.24.0 or newer. The shipped compose file uses optional env_file mappings with required: false, which Docker supports from 2.24.0. Its migration comments explain the stated 2.19 floor as support for one-shot dependencies under up --wait, but that does not cover the file's optional environment files.
  • Memory, which is the real constraint. Read the sizing section below before you pick a plan.
  • Free loopback ports 10254, 10255, 10256, 10257 and 5432. Port 10257 is the SSH front door, which starts with the runner profile this guide enables.

You do not need to install PostgreSQL yourself: the compose file runs it as a service. The setup wizard below needs Node.js and pnpm on the host. Working on the code itself also uses mise to pin the toolchain, including Rust for the gateway.

How many agent sandboxes fit on your VPS?

The runner's own documentation gives real numbers instead of vibes. Each sandbox is capped at 2048 MB of memory (RUNNER_SANDBOX_MEMORY_MB), one CPU (RUNNER_SANDBOX_CPUS) and 512 processes (RUNNER_SANDBOX_PIDS). The concurrency cap is 4 (RUNNER_MAX_SANDBOXES), and the documentation recommends around 10 GiB of free memory beyond the base stack to serve that cap.

ChartAgent memory budgets per box, using the documented 2 GiB cap
The data behind this chart
[
  {
    "plan": "2 GB box",
    "ram_gb": 2,
    "sandbox_slots": 0
  },
  {
    "plan": "4 GB box",
    "ram_gb": 4,
    "sandbox_slots": 1
  },
  {
    "plan": "8 GB box",
    "ram_gb": 8,
    "sandbox_slots": 3
  },
  {
    "plan": "16 GB box",
    "ram_gb": 16,
    "sandbox_slots": 7
  },
  {
    "plan": "32 GB box",
    "ram_gb": 32,
    "sandbox_slots": 15
  }
]

Those slot counts are arithmetic, not a benchmark: total memory, minus an assumed roughly 2 GB for PostgreSQL and the other long-running services, divided by the 2 GiB sandbox cap. On that basis the 2 GB box budgets for 0 sandboxes at their full memory cap; zero means no full-cap budget under these assumptions, not that Docker refuses to start an agent. A 16 GB box leaves room for 7, comfortably above the default cap of four and above the roughly 10 GiB of free memory the runner documentation asks for. The 32 GB box takes you to 15. Running more than four at once also requires raising RUNNER_MAX_SANDBOXES.

Two things bend that arithmetic. A sandbox with a background process running never parks, so it holds its slot permanently, which means you size RUNNER_MAX_SANDBOXES for sustained load and not for the busiest minute. The platform does put a ceiling on this: by default each runner keeps at most RUNNER_MAX_SANDBOXES minus one held-awake sandboxes (never fewer than one, overridable with MAX_HELD_AWAKE_SANDBOXES on the API), and above that it evicts the longest-idle one and reports its watched process as lost. Memory and CPU use depend on the work. Each sandbox is capped at one CPU, so four busy agents can use four cores, but the 2 GiB memory setting is a ceiling, not a reservation: four idle-but-awake agents do not automatically consume 8 GiB.

Runner settings you may want to change
  • RUNNER_MAX_SANDBOXES (default 4): how many sandboxes run at once.
  • RUNNER_SANDBOX_MEMORY_MB (default 2048): memory cap per sandbox.
  • RUNNER_SANDBOX_CPUS (default 1): CPU cap per sandbox.
  • RUNNER_SANDBOX_PIDS (default 512): process cap per sandbox.
  • RUNNER_NETWORK_INTERNAL (default true): keeps the sandbox network with no route out. Leave it on.
  • RUNNER_SANDBOX_NETWORK (default onecli-sandboxes): the network sandboxes join.
  • RUNNER_RECONCILE_SECONDS (default 60): how often the runner reconciles state.
  • RUNNER_ORPHAN_GRACE_SECONDS (default 3600): age at which orphaned containers and volumes are destroyed.
  • RUNNER_AGENT_IMAGE: overrides the sandbox image, which otherwise follows ONECLI_VERSION.

Install OneCLI with Docker Compose

The upstream self-hosting document's raw sequence writes three secrets into docker/.env beside the compose file. That sequence omits the runner token, Docker socket group and SSH credentials required by the services it enables, so run the setup wizard before starting the stack.

git clone https://github.com/onecli/onecli.git && cd onecli/docker
cat > .env <<EOF
SECRET_ENCRYPTION_KEY=$(head -c 32 /dev/urandom | base64)
GATEWAY_INTERNAL_SECRET=$(head -c 32 /dev/urandom | base64)
BETTER_AUTH_SECRET=$(head -c 32 /dev/urandom | base64)
COMPOSE_PROFILES=runner
EOF
chmod 600 .env
cd ..
pnpm install
pnpm run setup
cd docker
docker compose up -d --wait

Read that block before you run it. The heredoc marker is unquoted, so your shell runs each head -c 32 /dev/urandom | base64 and writes the result rather than the literal text. SECRET_ENCRYPTION_KEY is the AES-256-GCM key for every secret in the database. GATEWAY_INTERNAL_SECRET authenticates the gateway to the API. BETTER_AUTH_SECRET signs session cookies. COMPOSE_PROFILES=runner is the line that matters most, because the runner service sits behind a Compose profile: leave it out and the stack comes up healthy while no agent sandbox ever starts.

--wait waits for services to be running or healthy and for the migrations dependency to complete successfully, so a non-zero exit is your first signal that something is wrong. Then look at what actually came up.

docker compose ps
docker compose logs migrations

Pin the version. ONECLI_VERSION sets the tag for every service at once, and the agent sandbox image follows it unless RUNNER_AGENT_IMAGE points somewhere else. Use the bare version number: the published image tags carry no v prefix. As of 1 November 2026 the current release is v2.17.0, published on 31 October 2026. Add it to the same file, then use the documented upgrade path so running sandboxes move to that image too.

echo 'ONECLI_VERSION=2.17.0' >> .env
cd ..
pnpm run setup --upgrade
cd docker

An installer also exists, curl -fsSL https://onecli.sh/install | sh, which writes its configuration to ~/.onecli/.env and does the same work. It sets ONECLI_VERSION=latest for its own run, which overrides a pin kept only in that .env file. The Compose path is the one where you can read every file before anything runs, and it is the one to use on a box that already carries other Compose stacks. The checkout setup above upgrades with pnpm run setup --upgrade. That path wants Node.js and pnpm on the host, and working on the code itself adds mise and Rust for the gateway, so it suits people who intend to change OneCLI. For Kubernetes, release v2.11.0 (8 October 2026) added a Helm chart; the current chart runs agent sandboxes as Jobs with persistent volumes, without a Docker daemon, and documents the required secrets, database and routing configuration.

Reaching the dashboard from your laptop

Every published port in the shipped compose file binds to ${ONECLI_BIND_HOST:-127.0.0.1}. On a VPS that means the dashboard is running and nothing outside the box can reach it. That default is correct. Keep it, and tunnel:

ssh -N -L 10254:127.0.0.1:10254 you@your-server

Now open http://localhost:10254 on your laptop. The traffic rides the SSH connection, so there is no unencrypted dashboard on the public internet and no extra port to firewall.

Setting ONECLI_BIND_HOST=0.0.0.0 publishes the dashboard over plain HTTP, and it publishes PostgreSQL alongside it, with the compose file's default password of onecli unless you set POSTGRES_PASSWORD. It also publishes the SSH front door on port 10257, a service that mounts the Docker socket. If several people need the dashboard, put a reverse proxy with TLS (transport layer security) in front and leave the bind host alone. Set ONECLI_EXTERNAL_URL to its HTTPS URL and use upstream's reverse proxy configuration, which routes the dashboard, API and gateway paths to their respective services. A proxy on its own does not keep strangers out. The self-hosting document states that registration is open by design and has no switch to turn it off: anyone who reaches the dashboard can create an account, which gets its own organization, and only joining your organization needs an invitation. Its advice is to keep the dashboard behind your network boundary. If that proxy already fronts your other self-hosted apps, forward auth through a self-hosted single sign-on layer puts the dashboard behind the login your team already has, so removing someone in one place closes this door too.

Create the first account, then grant a model key

Open the dashboard and create your account straight away. Each new account gets its own organization, and teammates join yours by invitation. Registration stays open after that, which is one more reason the dashboard belongs behind the tunnel or an authenticated proxy. If you are upgrading from a release that predates logins, register immediately: the self-hosting document says the existing data goes to the first account that registers, so on a reachable host you want that account to be yours.

Then store a model key before you create an agent. A hosted agent needs a granted model key, and the order matters: store the key in the dashboard, grant it to the agent, and only then start a conversation. Skip the grant and the sandbox never launches; the agent replies in the thread explaining that it needs a model key.

Grant narrowly. Each agent gets only what you granted it and the gateway enforces that on every request, so an agent that reads one repository has no path to your payment provider's key. The same grant list is your lever on spend. A per-person agent that can call any model you own is a per-person invoice, so it is worth reading how to cap what an agent can spend on model calls before you hand out ten of them.

How the gateway keeps keys out of the agents

The gateway is an HTTPS proxy written in Rust, listening on port 10255. An agent's HTTP client is pointed at it and the agent carries a placeholder credential instead of a real one. The gateway matches the outbound request against that agent's grants, decrypts the real secret, swaps it into the request, and forwards it. Secrets sit in PostgreSQL encrypted with AES-256-GCM (advanced encryption standard, 256-bit, Galois/counter mode) and are decrypted only at request time. Every call is logged with the agent's identity and its target, which is an audit trail you cannot get when keys live in ten people's shell profiles.

Two mechanics decide how you deploy it.

  • HTTPS interception is a man-in-the-middle. The gateway generates a local certificate authority, the agent trusts it, and the gateway terminates the agent's TLS connection then opens a fresh one to the upstream service. That is why an agent whose HTTP client does not trust the gateway certificate authority fails with a certificate verification error rather than an authentication error.
  • The agent identifies itself with a Proxy-Authorization header. On a single box, where agents and gateway share an internal Docker network, that header never crosses a network you do not own. Point an off-box agent at the gateway and protect the connection with a VPN or TLS transport, because that header is a bearer token; upstream recommends a VPN for the raw CONNECT proxy port.

The honest trade: the gateway reads every request your agents make, in plaintext, by design. It is the most sensitive process on the machine. Treat its host accordingly, and keep the number of people who can log in small with least-privilege Linux users.

Why the runner needs no inbound port

The runner is outbound-only. From its documentation: "it holds no ports the outside world can reach, so a laptop, a homelab, or a VPC behind NAT all work with no ingress, no tunnel, and no TLS termination story." NAT is network address translation, the thing a home router does. The runner dials out to the control plane and pulls work from it, so there is nothing to forward and nothing to open.

That design pays off in the sandbox network. The compose file defines a second network marked internal: true, which in Docker means no external network connectivity. Sandboxes join it. The gateway is dual-homed across both networks, so it is the only way out. The runner documentation states the point plainly: "an internal network with the gateway dual-homed onto it is what makes gateway-only egress a boundary rather than a suggestion." An agent cannot bypass the gateway by opening a direct connection to an external address; the gateway's policy still decides which requests it permits.

Confirm it on your own box rather than trusting the paragraph above.

docker network ls
docker network inspect onecli-sandboxes | grep -i internal

You should see "Internal": true. If it reads false, the egress control is off and the gateway is a suggestion again. Use whichever sandbox network name docker network ls prints, since onecli-sandboxes is only the default.

How strong is the OneCLI sandbox?

Read this section slowly, because "sandboxed" carries a lot of weight in the project's own description while the mechanism is documented in the runner documentation and backend code.

The README says each agent gets "its own isolated sandbox, with a filesystem and a shell", and names the Sandbox Supervisor as the component that "runs inside each sandbox, speaking a vendor-neutral harness interface so the agent runtime is swappable". Neither sentence says what the isolation is made of. The runner's documentation does: the default backend is Docker (RUNNER_BACKEND=docker), and a sandbox is a Docker container with a memory cap, a CPU cap and a process cap, attached to the internal network. The code carries a seam for other backends. The current runner code also implements a Kubernetes backend, which the Helm chart uses for sandbox Jobs and persistent volumes. On the Compose installation in this guide, a sandbox is a Docker container.

The runner documentation now describes the Docker boundary: the agent runs as node, with no-new-privileges, all Linux capabilities dropped and Docker's default seccomp profile. The backend mounts only the agent's durable home into its sandbox. So take the narrow reading. The caps are resource caps. The internal network is a genuine egress control. The isolation between an agent and your host uses these container controls, and a container shares the host kernel.

There is a second fact to weigh. The runner service mounts /var/run/docker.sock, because that is how it creates sandboxes. Access to a rootful Docker daemon's socket is equivalent to root on the host, since whoever can call that API can start a container with the host filesystem mounted inside it. The shipped Docker-backed runner uses that socket. The consequence is that the runner process is as sensitive as the gateway. The SSH terminator mounts the same socket so it can exec into sandbox containers, and the compose file's own comments call that mount root-equivalent on the host, so keep port 10257 on loopback unless you have a reason to open it.

Treat the shared-kernel boundary conservatively. In practice that means three habits.

  1. Run OneCLI on a box that does nothing else. No unrelated production service, no shared database, no other team's data.
  2. Assume an agent that gets arbitrary code execution inside its sandbox could reach the host, and make that outcome survivable with backups kept off the box.
  3. Read apps/runner/src or ask upstream before you tell a colleague that the agent is contained.

For a picture of what a documented boundary reads like, and the questions worth asking upstream, compare this against what a real agent sandbox boundary looks like. The question is whether the documented mechanism covers the threats you need it to stop.

The licence split, and why to check before you build

OneCLI's core is Apache-2.0, and self-hosting it in production is allowed. Directories named ee/ fall under a separate OneCLI Enterprise License: free for development, testing and evaluation, with a subscription required for production use. The v2.0.1 release notes from 18 August 2026 mention restoring a GitHub-detectable Apache-2.0 licence file, so the badge on the repository page has moved recently. Check the tag you actually deploy rather than a summary written on some other date.

cd onecli && find . -type d -name ee -not -path '*/node_modules/*'

Anything under those paths is the commercial half. If a feature you plan to depend on lives there, price it before you build a process around it.

Upgrades, migrations, and the one file you cannot lose

Upgrades must refresh the service images and the separate agent image, then restart running sandboxes. A one-shot migrations service runs before the API on every up, and if a migration fails the stack refuses to start rather than serving against a half-migrated schema. That is the behaviour you want, because a failed upgrade then looks like an outage instead of like quiet corruption, and docker compose logs migrations says why.

One step is easy to miss. The self-hosting document warns against upgrading with a bare docker compose pull && docker compose up -d, because the agent sandbox image is not a Compose service. It is the RUNNER_AGENT_IMAGE value on the runner, so docker compose pull never sees it, and hosted agents can stay on an old sandbox image with no warning. Update the checkout, move the pin, and run the documented upgrade tool, which pulls the sandbox image and restarts running sandboxes.

cd onecli
git pull
sed -i 's/^ONECLI_VERSION=.*/ONECLI_VERSION=2.17.0/' docker/.env
pnpm install
pnpm run setup --upgrade
cd docker
docker compose logs migrations

Replace 2.17.0 with the release you are moving to. Sandbox restarts interrupt in-flight work; each agent's durable workspace survives.

If you installed with the install script instead, re-run that script rather than pulling by hand, so the compose file stays in step with the images it references. Export ONECLI_VERSION first if you want a specific release, since the script overrides a pin kept only in its .env file.

Back up the database, configuration and agent workspace volumes. PostgreSQL holds the agents, conversations, memory and the encrypted secrets. The docker/.env file holds SECRET_ENCRYPTION_KEY, and without that key the encrypted secrets are unreadable, even if the rest of the database is restored. Each agent's /workspace lives on a separate durable volume and needs its own backup.

cd onecli/docker
docker compose exec -T postgres pg_dump -U onecli onecli | gzip > ~/onecli-db.sql.gz
install -m 600 .env ~/onecli-env.backup

Keep those copies and the workspace backups off the box. The routine is the same one any stateful Compose stack needs, so if you already back up and upgrade a Docker Compose stack on a schedule, add the database, configuration and workspace volumes to it and stop thinking about it.

When it does not work

  • The stack never comes healthy and docker compose up -d --wait exits non-zero. Read docker compose logs migrations first, because the API deliberately waits on that service.
  • An agent sits idle and no sandbox appears. Check that COMPOSE_PROFILES=runner is in docker/.env and that docker compose ps lists a runner. Then check the agent has a granted model key, since sandboxes do not launch without one.
  • No slots left. RUNNER_MAX_SANDBOXES defaults to 4, and a sandbox with a background process running holds its slot until the held-awake ceiling evicts it. docker ps shows what is really alive.
  • The stack will not start and Docker reports a port already in use. With the runner profile on, the SSH front door wants 10257 as well as the other four ports.
  • Containers vanish, or the host crawls. Check for memory exhaustion with dmesg -T | grep -i oom; the default memory cap lets a single sandbox use up to 2048 MB.
  • An agent's HTTPS calls fail with certificate verification errors rather than authentication errors. Its HTTP client does not trust the gateway's certificate authority.
  • Old containers or volumes linger after you delete an agent. The runner reconciles every 60 seconds and destroys orphans older than RUNNER_ORPHAN_GRACE_SECONDS, which defaults to 3600, so wait an hour before you call it a leak.

Is this the right thing for you to run?

The fit test is short. OneCLI earns a box when several people each need an agent and you want the credentials in one place: one store to rotate, one audit log to read, one dashboard where revoking a person's access actually revokes it. That is a real operational problem, and copying an API key into six laptops is a worse answer to it.

For one person it is a lot of machinery for no gain. You would run PostgreSQL, a control plane, a gateway and a runner to give yourself a single agent, and the credential problem the gateway solves barely exists when the only holder of the key is you. Run a single harness on a smaller box instead: a single agent harness on a VPS does that job on a fraction of the memory. If you have not picked a direction at all yet, the survey in self-hosted AI agents compared is the cheaper first step. If the unfamiliar part is agents themselves rather than the servers they run on, work through a staged path for learning how agents actually work first, because knowing what a tool call and a memory store really do is what tells you which grants each person's agent should get.

FAQ

What are the minimum server requirements to self-host OneCLI?

Docker with the Compose plugin at 2.24.0 or newer, Node.js and pnpm for the setup wizard used here, and enough memory. PostgreSQL comes with the compose file, so you do not install it separately. Memory is what decides the plan: the runner caps each agent sandbox at 2048 MB by default, and its documentation asks for around 10 GiB free beyond the base stack to serve the default cap of four sandboxes. Under the chart's assumed 2 GB base-stack budget, a 4 GB box budgets for one sandbox at its full cap and a 16 GB box covers the default concurrency cap. These are planning figures, not measured minimum requirements or fixed memory allocations.

Does OneCLI need PostgreSQL, or can it use SQLite?

It needs PostgreSQL. DATABASE_URL is documented as a PostgreSQL connection string, the shipped compose file runs postgres:18-alpine with a pgdata volume, and a separate migrations service applies the schema before the API starts. No SQLite option is documented. For an external PostgreSQL server, configure both the API and migrations service to use it; the shipped compose file sets their connection strings to its bundled PostgreSQL service.

Is the OneCLI agent sandbox a real security boundary?

The documented Compose mechanism is a Docker container with memory, CPU and process caps, attached to a network marked internal: true so external traffic goes through the gateway. The egress control is real and you can verify it with docker network inspect. The agent runs as node, with no-new-privileges, all Linux capabilities dropped and Docker's default seccomp profile, while sharing the host kernel. The runner and the SSH terminator both mount /var/run/docker.sock, which is equivalent to root on a host using a rootful Docker daemon. Run OneCLI on a dedicated box, and keep backups off that box.

Do I need to open any inbound ports for OneCLI?

No. The runner is outbound-only and holds no ports the outside world can reach, so it works behind NAT with no tunnel. The compose file binds the dashboard, gateway, API, PostgreSQL and, under the runner profile, the SSH front door on 10257 to 127.0.0.1 by default. Reach the dashboard over an SSH tunnel, or use upstream's reverse proxy configuration with TLS and the required dashboard, API and gateway routes if several people need it, remembering that registration stays open to anyone who can reach it. The gateway on 10255 is for agents, and on a single box those agents reach it over the internal Docker network.

Is OneCLI free to use inside a company?

The core is Apache-2.0 and self-hosted production use is allowed with no commercial licence. Directories named ee/ are covered by the OneCLI Enterprise License, which is free for development, testing and evaluation but needs a subscription in production. The split moves between releases, and the v2.0.1 notes from 18 August 2026 mention restoring a GitHub-detectable Apache-2.0 licence file, so check LICENSE and the ee/ directories in the exact tag you deploy before you build a workflow on any single feature.

Was this article useful?