Skip to main content
Follow this guide to set up OneCLI and give your agent secure access to external services.

​
For coding agents

For developers using Claude Code, Cursor, Codex, or other coding agents. No SDK or Docker needed.
1

Sign up and get your API key

Go to app.onecli.sh and create an account. A project and API key are generated automatically.
2

Connect services

From the dashboard, connect the services your agent needs (Google, GitHub, Slack, AWS, etc.). Most services connect with OAuth in one click.Connect a service in the OneCLI dashboard
3

Install the CLI and run your agent

curl -fsSL onecli.sh/cli/install | sh
onecli auth login --api-key oc_your_api_key
onecli run -- claude
This wraps your agent with proxy settings, CA certificates, and agent skills automatically.
That’s it. Your agent’s HTTP calls now route through OneCLI, which injects credentials and enforces your rules. Your agent never sees the raw keys. Replace claude with your agent of choice: 
onecli run -- cursor
onecli run -- codex
onecli run -- your-custom-agent
See the Coding Agents guide for advanced configuration.

​
For SDK and Docker agents

For agents running in Docker containers or programmatic setups. Use the SDK to configure containers automatically.
1

Get your API key

Sign up at app.onecli.sh if you haven’t already. Your API key is available in the dashboard.You can also create agents programmatically via the API:
curl -X POST https://api.onecli.sh/agents \
  -H "Authorization: Bearer $ONECLI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "my-agent", "identifier": "my-agent" }'
2

Install the SDK

npm install @onecli-sh/sdk
3

Configure your container

import { OneCLI } from "@onecli-sh/sdk";

const onecli = new OneCLI({
  apiKey: "oc_your_api_key",
});

const args = ["run", "-i", "--rm", "--name", "my-agent"];
await onecli.applyContainerConfig(args);
// args now has HTTPS_PROXY, CA certs, and volume mounts

console.log("Container configured for OneCLI");
No url parameter needed — the SDK defaults to the managed service at api.onecli.sh.
See the Node.js SDK docs for the full API reference including manual approval, project provisioning, and org-level keys.

​
Self-hosting

OneCLI is also available as an open-source project you can run on your own infrastructure. 
docker run --pull always -p 10254:10254 -p 10255:10255 -v onecli-data:/app/data ghcr.io/onecli/onecli
This starts both the web dashboard (port 10254) and the gateway (port 10255) in a single container with embedded storage. Open localhost:10254 to manage agents, secrets, and rules.Or with Docker Compose:
git clone https://github.com/onecli/onecli.git
cd onecli/docker
docker compose up
When using the SDK with a self-hosted instance, pass the url parameter:
const onecli = new OneCLI({
  url: "http://localhost:10254",
  apiKey: "oc_your_api_key",
});
See How it works for the full architecture and configuration options.

​
Next steps

You’ve connected your first agent. Now explore what else OneCLI can do:

Rules

Block operations, rate-limit actions, and require manual approval per agent.

Integrations

Browse 30+ supported services and connect them from the dashboard.

How it works

Architecture: gateway, vault, rules, and how the pieces fit together.

API Reference

Manage agents, secrets, rules, and connections programmatically.

​
Troubleshooting

If you’re accessing a self-hosted OneCLI through an SSH tunnel, reverse proxy, or on a remote server, OAuth callbacks may redirect to an unreachable address.Set NEXT_PUBLIC_APP_URL to the URL you actually use in your browser:
NEXT_PUBLIC_APP_URL=http://localhost:8080
For SSH tunnel setups, forwarding to the same local port avoids this entirely:
ssh -L 10254:127.0.0.1:10254 user@host
Make sure Docker is running and ports 10254/10255 are available. Check logs with docker logs <container-id>.