Quickstart

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):

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.

Add credentials via the dashboard

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

Connect your agent

Coding agents (Claude Code, Cursor, etc.)
Docker containers (NanoClaw, custom)
Manual proxy

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.

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.

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>.

OneCLI Docs How it works

Getting Started

CLI

External Vaults

Start with Docker

Or with Docker Compose

What happens next

Troubleshooting

Getting Started

CLI

External Vaults

​Start with Docker

​Or with Docker Compose

​What happens next

​Troubleshooting

Start with Docker

Or with Docker Compose

What happens next

Troubleshooting