> ## Documentation Index
> Fetch the complete documentation index at: https://onecli.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect the CLI and agents

> Point agents at your self-hosted OneCLI instance, including fully headless provisioning with the organization API key.

Your self-hosted instance serves the same [REST API](/api-reference) 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](/self-hosting/enterprise/all-in-one) 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:

```bash theme={null}
curl http://localhost:10254/v1/container-config \
  -H "Authorization: Bearer $ONECLI_ORG_API_KEY"
```

```json theme={null}
{
  "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.

<Note>
  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](/self-hosting/configuration#networking).
</Note>

### With the SDK

The [Node SDK](/sdks/node) wraps the same endpoint. Point it at your instance and let it configure agent containers:

```typescript theme={null}
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](/api-reference). Project-scoped endpoints take an `X-Project-Id` header:

```bash theme={null}
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](/self-hosting/configuration#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](/guides/rules) to control what each agent can do
* Connect [apps](/integrations/app-connections) and [external vaults](/vaults/overview)
* Explore the full [API reference](/api-reference)