Skip to main content
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

Point your agent at the gateway

If your agent runs directly on the host, set the proxy env vars:
export HTTP_PROXY=http://localhost:10255
export HTTPS_PROXY=http://localhost:10255
If your agent runs in a Docker container, use the Node.js SDK to configure it automatically:
npm install @onecli-sh/sdk

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

const onecli = new OneCLI({
  url: "http://localhost:10254",
  apiKey: "oc_your_api_key", // from the dashboard
});

const args = ["run", "-i", "--rm", "--name", "my-agent"];

// Fetches gateway config and pushes -e / -v flags onto args
const active = await onecli.applyContainerConfig(args);

// args now contains HTTPS_PROXY, CA certs, and volume mounts
The SDK handles environment variables (HTTPS_PROXY, HTTP_PROXY), CA certificate mounts, and host mappings on Linux. See the full SDK docs for all options.
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
  • Explore the SDKs for programmatic integration

​
Troubleshooting

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