Skip to main content
Your self-hosted instance serves the same REST API as OneCLI Cloud, so the CLI, SDKs, and agents work the same way. You just point them at your instance instead of api.onecli.sh. There are two ways to get an agent running: through the dashboard, or headless over the API. On the Enterprise image, the organization API key makes this fully headless from first boot; on Community, create a project API key in the dashboard first and use it the same way.

​
Headless: provision straight from the API

On the Enterprise image, the organization and its API key are created at container startup, so the API works before you ever open the dashboard. One call provisions everything an agent needs: 
curl http://localhost:10254/v1/container-config \
  -H "Authorization: Bearer $ONECLI_ORG_API_KEY"

{
  "env": {
    "HTTPS_PROXY": "http://x:aoc_da603e520d5f142d0646e08f41c8ad08a1f48ec40953120540511ef9e2aa0334@host.docker.internal:10255",
    "HTTP_PROXY": "http://x:aoc_da603e520d5f142d0646e08f41c8ad08a1f48ec40953120540511ef9e2aa0334@host.docker.internal:10255",
    "NODE_EXTRA_CA_CERTS": "/tmp/onecli-gateway-ca.pem",
    "NODE_USE_ENV_PROXY": "1",
    "GIT_TERMINAL_PROMPT": "0",
    "GIT_HTTP_PROXY_AUTHMETHOD": "basic"
  },
  "caCertificate": "-----BEGIN CERTIFICATE-----\nMIIBqzCC...\n-----END CERTIFICATE-----",
  "caCertificateContainerPath": "/tmp/onecli-gateway-ca.pem",
  "warnings": [
    "No Anthropic credentials configured — the agent will use its own API key if available. Add one at /secrets"
  ]
}
On the first call, the instance provisions a default project and a default agent, then returns the agent’s proxy configuration: proxy URLs carrying the agent’s access token, and the gateway’s CA certificate. Apply the env values and write caCertificate to the NODE_EXTRA_CA_CERTS path, and the agent’s HTTP traffic routes through your gateway.
The proxy URL’s host comes from GATEWAY_BASE_URL (default host.docker.internal:10255), which is right for agent containers on the same Docker host. If agents run elsewhere, set GATEWAY_BASE_URL to an address they can reach. See Configuration.

​
With the SDK

The Node SDK wraps the same endpoint. Point it at your instance and let it configure agent containers: 
import { OneCLI } from "@onecli-sh/sdk";

const onecli = new OneCLI({
  url: "https://onecli.internal.example.com",
  apiKey: "oc_org_your_org_api_key",
});

const args = ["run", "--rm", "my-agent-image"];
const active = await onecli.applyContainerConfig(args);

​
Managing the instance over the API

The organization API key works across the REST API. Project-scoped endpoints take an X-Project-Id header: 
curl http://localhost:10254/v1/agents \
  -H "Authorization: Bearer $ONECLI_ORG_API_KEY" \
  -H "X-Project-Id: smkufuswcpmbkqya"

​
Through the dashboard

Open your instance’s dashboard, connect the apps your agents need (see app integrations), and add LLM keys under Secrets. Agents provisioned through container-config pick up new connections and secrets on their next request; no restart needed.

​
Next steps