# OneCLI: a self-hosted agent harness that gives every employee a sandboxed agent

> OneCLI v2 turns a credential vault for AI agents into a team platform: one sandboxed agent per person, one gateway that injects secrets the agent never sees, and a runner that only makes outbound connections. Here is how the pieces fit and where it stops being the right tool.

**onecli/onecli** — Open-source sandboxed agent harness for teams. Giving every employee a secured personal agent.

- Repository: https://github.com/onecli/onecli
- Website: https://onecli.sh
- Stars: 3,535 · Forks: 246
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/onecli-onecli

## The problem OneCLI solves: agents built for one person, deployed for a company

The README is unusually candid about the origin story. OneCLI started as a credential vault for AI agents, written in Rust, and the demand came mostly from individuals and teams running autonomous agents such as Hermes, OpenClaw and NanoClaw. Those agents work well for one person. The README states the gap directly: "Every autonomous agent out there is built for one person. And for one person, they're great." Replicating that across a team means provisioning each agent, deciding what each one may touch, hosting them, and tracking ownership.

So the target user is not a solo developer with a script. It is a company that wants a personal agent per employee and refuses to distribute raw credentials to each one. The two missing pieces the README names are secret and permission management, and multiplayer management for teams. Everything in the product follows from those two.

## How the gateway injects credentials the agent never holds

The mechanism is a man-in-the-middle proxy. The Rust Gateway in apps/gateway intercepts outbound requests, HTTPS included, and injects credentials into them. Agents authenticate to the gateway with access tokens sent via Proxy-Authorization headers. The secret store keeps values encrypted with AES-256-GCM at rest, decrypts them only at request time, matches them by host and path pattern, and injects them as headers or query parameters.

The practical consequence: an agent's sandbox has a filesystem and a shell, and the README says the only way out is the gateway. The agent can reach what you granted and nothing else. There is also an on-demand path. Connecting Bitwarden or 1Password, documented in docs/vault-integration.md, means nothing is stored on the server at all.

The rest of the architecture is split into small services. apps/web is a Next.js dashboard for creating agents, chatting, editing memory and skills, and managing connections, secrets and grants. apps/api-server is the control plane that owns the database, the conversation plane and the work queue the runner polls. apps/runner starts, parks and reaps sandboxes, is outbound-only and never touches the database. apps/sandbox-supervisor runs inside each sandbox behind a vendor-neutral harness interface, which is what makes the agent runtime swappable. apps/ssh-terminator terminates ssh connections with short-lived certificates. apps/channel-adapter is the Slack daemon, one app per agent.

## Installing OneCLI and creating your first agent

There are two paths. The cloud-hosted option is onecli.sh. For self-hosting, the README gives a three-command quick start:

```bash
git clone https://github.com/onecli/onecli.git && cd onecli
pnpm install
pnpm run setup
```

The README says to open http://localhost:10254 afterwards. For local development the repository uses a different sequence, with mise managing tool versions:

```bash
mise install
pnpm install
pnpm dev
```

The package.json scripts show what pnpm dev actually does: it runs node scripts/dev.mjs. According to .env.example, that script generates every required secret on first run (BETTER_AUTH_SECRET, SECRET_ENCRYPTION_KEY, GATEWAY_INTERNAL_SECRET, RUNNER_TOKEN, CHANNEL_ADAPTER_TOKEN), writes the dev DATABASE_URL, and never overwrites a value you set. The README describes the same run as generating .env, starting PostgreSQL, applying migrations and launching the full stack. A self-host install gets the same treatment from pnpm run setup into docker/.env, or from the install script into ~/.onecli/.env.

The important detail for anyone who has been burned by .env.example files: you do not copy it. The file states that plainly. Every line in it is an optional override. If you want a different database, uncomment the dev default:

```bash
DATABASE_URL=postgresql://onecli:onecli@localhost:5432/onecli
```

Google sign-in is optional too. Email and password always works; setting GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET adds a "Continue with Google" button, with the redirect URI at <API_URL>/auth/callback/google. Once the stack is up, the dashboard at port 10254 is where you create an agent, grant it connections, and talk to it.

## ONE var decides how OneCLI is addressed

The .env.example contains a decision worth reading before you deploy, because it is the kind of thing people discover after a broken redirect. One variable answers "where do people open OneCLI": ONECLI_EXTERNAL_URL. It is deliberately not derived from the address the server binds to, and the file says why: those are different things, and only you know the first one.

Every other address derives from it by one rule. An http scheme means PORTS mode, where the API and gateway live on the same host on their own ports, 10256 and 10255 by default. An https scheme means PROXY mode, where one origin serves everything and your reverse proxy terminates TLS and routes /v1 and /auth. That is a clean split, and it means a self-hosted deployment behind a reverse proxy does not need to reason about internal port mappings at all. The trade-off is that getting the scheme wrong changes the deployment shape rather than just a URL.

## What an agent actually is, and why that matters for approvals

The README defines an agent as durable rather than a single prompt. It has a computer (an isolated sandbox with a filesystem and a shell), a conversation (its own dashboard page or Slack, with images and files, where a message sent while the agent is working redirects it immediately instead of queueing), memory kept by the platform and editable at any time, skills written once and always available, and a schedule so the platform wakes it for planned work.

Two of those deserve scrutiny. The redirect-while-working behaviour is a real design choice: most chat interfaces queue, and queueing is what makes an agent feel unresponsive when you spot a mistake mid-task. Redirecting is better for correction and worse for anything where you wanted the original instruction to complete.

The second is human-in-the-loop approvals. The README calls them deterministic and places them in the chat itself, for actions you need full control over, naming sending an email, deleting a Linear ticket and emptying an S3 bucket. Deterministic is the operative word. The approval is enforced by the platform rather than requested in a prompt, which is the difference between a guardrail and a suggestion.

## Where OneCLI is the wrong tool

The clearest boundary is headcount. If you are one person running one agent, the team features are overhead: provisioning from an identity provider, per-agent Slack apps, workspace policy and grants all exist to solve coordination that does not exist yet. The README's own framing says the original vault was built for individuals and that the team layer is what v2 adds.

The second boundary is operational. Self-hosting means running PostgreSQL, the API server, the web app, the gateway, the runner and the sandbox supervisor, plus Docker for the agent image if you use the agent:build script. The README's comfort argument is that agents run on your own infrastructure and the runner is outbound-only with no inbound ports, so a laptop, a homelab or a VPC behind NAT works with no ingress and no tunnel. That removes one class of networking work and leaves the rest.

The third is the MITM gateway itself. Intercepting HTTPS to inject credentials is the feature, and it is also the thing that will make a security reviewer ask questions. If your policy forbids TLS interception on the path, this design is not for you, and the Bitwarden or 1Password on-demand path from docs/vault-integration.md is the alternative to examine first. Finally, the README's own description of the licence points at ee/ directories holding enterprise features under a separate licence, so anyone evaluating feature parity needs to read LICENSE-ENTERPRISE rather than assuming Apache-2.0 covers everything.

## OneCLI compared with running a personal agent harness directly

The obvious alternative is what OneCLI's users were already doing: run Hermes, OpenClaw or NanoClaw per person and manage the credentials yourself. The difference in approach is where the secret lives. A personal harness typically gets a token in its environment or config, and the agent process can read it. OneCLI moves the secret out of the sandbox entirely and into a gateway that matches by host and path and injects at request time, so compromising the agent does not hand over the key.

The second difference is ownership. Per-person harnesses have no shared notion of who owns which agent, what it may reach, or what happens when someone leaves. OneCLI puts that in the API server's database and the dashboard, with provisioning tied to the company identity provider and shared connections granted per agent without ever being handed to one.

What you give up is simplicity. A single harness is one process. OneCLI is a control plane, a gateway, a runner, a supervisor and a database, and you are the operator. For a two-person team, that is the wrong trade. For twenty people who each need an agent with scoped access to internal systems, the arithmetic changes.

## Maintenance, releases and licence cost

The repository is not archived and the last push was on 2026-09-10, with releases v2.4.0 on 2026-09-01, v2.5.0 on 2026-09-03 and v2.6.0 on 2026-09-08. That is a fast cadence, and it means upgrade work is a recurring cost rather than a one-off. The database is the part to watch: package.json exposes db:migrate, db:push and db:generate, and the README says pnpm dev applies migrations automatically. A self-hosted deployment should be running the migration script deliberately rather than relying on a dev command.

Licensing is Apache-2.0 with one stated exception: the ee/ directories hold enterprise features under a separate licence, and LICENSE-ENTERPRISE is in the repository root alongside LICENSE. Contributions are accepted under a Contributor License Agreement. That structure is common and not alarming, but it means "open source" here does not automatically mean every feature in the tree is Apache-2.0. Check which directory a capability lives in before you plan around it. This is a description of the repository layout, not legal advice; read the licence files yourself.

## Conclusion

Adopt OneCLI if you are running autonomous agents for more than a couple of people and you cannot hand out long-lived API keys. Skip it if you want one personal agent for yourself, or if you cannot run PostgreSQL and a container host. Before rolling it out, verify three things in your own environment: that the outbound-only runner can reach your API server from wherever the sandboxes will live, that your identity provider is one the provisioning path actually supports, and that the ee/ directories in LICENSE-ENTERPRISE do not cover a feature you assumed was Apache-2.0.

## FAQ

### What is OneCLI?

OneCLI is an open-source platform for running AI agents as a team, licensed Apache-2.0 with enterprise features in ee/ directories. You create one sandboxed agent per person, and it reaches the outside world only through a gateway that injects credentials and enforces your policy.

### How to install OneCLI?

The README's self-hosted quick start is to clone the repository, run pnpm install, then pnpm run setup, and open http://localhost:10254. For local development the sequence uses mise install, pnpm install and pnpm dev, which generates .env, starts PostgreSQL, applies migrations and runs the full stack.

### How to use OneCLI?

After the stack is running, you open the dashboard on port 10254 to create an agent, grant it connections, and chat with it from the dashboard or Slack. Each agent gets its own sandbox, memory, skills and schedule, and the gateway enforces what it may reach on every request.

## Sources

- [License: Apache-2.0](https://github.com/onecli/onecli/blob/main/LICENSE)
- [onecli/onecli on GitHub](https://github.com/onecli/onecli)
- [Project website](https://onecli.sh)
- [README](https://github.com/onecli/onecli/blob/main/README.md)
- [Releases](https://github.com/onecli/onecli/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/onecli-onecli