Connect the CLI and agents

Point agents at your self-hosted OneCLI instance, with headless provisioning, org-wide app connections, and rules via the organization API key.

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_[e-mail]:10255",
    "HTTP_PROXY": "http://x:aoc_[e-mail]: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"

Organization-level connections and rules

Organization-level resources take no X-Project-Id at all: the organization comes from the key itself, and anything you create applies to every project and agent on the instance. Connect an API-key app organization-wide:

curl -X POST http://localhost:10254/v1/org/apps/fireflies/connect \
  -H "Authorization: Bearer $ONECLI_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fields": {"apiKey": "your-fireflies-api-key"}}'

{ "success": true }

For OAuth apps, configure the app’s OAuth client first (see App credentials), then request the authorize URL and open it in a browser to finish the flow:

curl -si http://localhost:10254/v1/org/apps/google-drive/authorize \
  -H "Authorization: Bearer $ONECLI_ORG_API_KEY" | grep -i '^location:'

Organization policy rules work the same way and apply to every agent (see Policy rules for the draft → publish model):

curl -X POST http://localhost:10254/v1/org/policy/rules \
  -H "Authorization: Bearer $ONECLI_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Block Gmail sends", "action": "block", "targets": [{"kind":"app","provider":"gmail","tools":["send_email"]}]}'

Then enforce the draft with POST /v1/org/policy/publish. Inspect what exists with GET /v1/org/connections and GET /v1/org/policy/rules, or use the CLI: the onecli org apps connect, onecli org apps authorize, and onecli org policy commands wrap the same endpoints. Agents pick up new organization connections and published rules on their next request.

The /v1/org/policy surface is available on Enterprise releases running the policy engine. Self-hosted releases that predate it use the older /v1/org/rules API instead (onecli org rules --help).

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

• Add rules to control what each agent can do
• Connect apps and external vaults
• Explore the full API reference