Quickstart: Connect Your First Service in Minutes

Install OneCLI and connect your first service in under five minutes. Works with Docker or as a standalone binary. No code changes needed.

Get onecli running and connect your agent to external services.

Start with Docker

The fastest way to run OneCLI locally (no external database or config needed):

1. Start onecli

   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.

2. Add credentials via the dashboard

   Open localhost:10254, create an agent, and add credentials for the services your agent uses (Google, GitHub, Slack, etc.).

3. Connect your agent

   Coding agents (Claude Code, Cursor, etc.)

   Install the OneCLI CLI and launch your agent through it:

   curl -fsSL onecli.sh/cli/install | sh
   onecli auth login --api-key oc_your_api_key
   onecli run -- claude
   

   This configures proxy settings, CA certificates, and agent skills automatically. See the Coding Agents guide for details.

   Docker containers (NanoClaw, custom)

   Use the Node.js SDK to configure agent containers:

   npm install @onecli-sh/sdk
   

   import { OneCLI } from "@onecli-sh/sdk";
   
   const onecli = new OneCLI({
     url: "http://localhost:10254",
     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
   

   See the NanoClaw guide or SDK docs for the full setup.

   Manual proxy

   Set proxy environment variables directly:

   export HTTPS_PROXY=http://localhost:10255
   export HTTP_PROXY=http://localhost:10255
   

   You’ll also need to trust the gateway CA certificate. Download it from the dashboard at localhost:10254.

That’s it. Your agent’s HTTP calls now have credentials injected automatically.

Or with Docker Compose

git clone https://github.com/onecli/onecli.git
cd onecli/docker
docker compose up

What happens next

You now have OneCLI set up. From here:

• Read How it works to understand the full architecture
• Set up Coding Agents (Claude Code, Cursor, Codex)
• Explore the SDKs for Docker-based agent integration

Troubleshooting

Docker container won't start

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

OAuth redirect goes to the wrong URL (remote/VPS/tunnel setups)

If you’re accessing OneCLI through an SSH tunnel, reverse proxy, or on a remote server, OAuth callbacks may redirect to an unreachable address (e.g. http://127.0.0.1:10254).

Set NEXT_PUBLIC_APP_URL to the URL you actually use in your browser:

# In your .env file or docker-compose.yml
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