Quickstart

Sign up for OneCLI and connect your first agent to external services in under five minutes. No code changes needed.

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.

   
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

   npm install @onecli-sh/sdk
   

   pnpm add @onecli-sh/sdk
   

   pip install onecli
   
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.

Self-hosted setup with Docker

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

OAuth redirect goes to the wrong URL (self-hosted / remote setups)

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

Docker container won't start (self-hosted)

Make sure Docker is running and ports 10254/10255 are available. Check logs with docker logs <container-id>.