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

# Node.js SDK: Container Config, Provisioning & Approval

> Configure Docker containers to route through the OneCLI gateway from Node.js. Handles proxy setup, CA certs, and approval.

The OneCLI Node.js SDK provides a programmatic interface for configuring Docker containers to route through the OneCLI gateway, so containerized agents can access external APIs without exposing credentials.

<Card title="@onecli-sh/sdk" icon="npm" href="https://www.npmjs.com/package/@onecli-sh/sdk">
  View on npm
</Card>

## Requirements

| SDK version | Node.js version |
| ----------- | --------------- |
| >= 0.1.0    | >= 20           |

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @onecli-sh/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @onecli-sh/sdk
  ```

  ```bash yarn theme={null}
  yarn add @onecli-sh/sdk
  ```
</CodeGroup>

## Quick start

<Tabs>
  <Tab title="Cloud">
    ```typescript theme={null}
    import { OneCLI } from "@onecli-sh/sdk";

    // No url needed — defaults to https://api.onecli.sh
    const onecli = new OneCLI({
      apiKey: "oc_your_api_key",
    });

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

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

    // args now contains HTTPS_PROXY, CA certs, and volume mounts
    console.log(active); // true if OneCLI was reachable
    ```
  </Tab>

  <Tab title="Self-hosted">
    ```typescript theme={null}
    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"];

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

    // args now contains HTTPS_PROXY, CA certs, and volume mounts
    console.log(active); // true if OneCLI was reachable
    ```
  </Tab>
</Tabs>

### Environment variables

Instead of passing options explicitly, set environment variables:

<Tabs>
  <Tab title="Cloud">
    ```bash theme={null}
    export ONECLI_API_KEY=oc_your_api_key
    # ONECLI_URL defaults to https://api.onecli.sh
    ```
  </Tab>

  <Tab title="Self-hosted">
    ```bash theme={null}
    export ONECLI_URL=http://localhost:10254
    export ONECLI_API_KEY=oc_your_api_key
    ```
  </Tab>
</Tabs>

```typescript theme={null}
import { OneCLI } from "@onecli-sh/sdk";

// Automatically reads from ONECLI_API_KEY (and ONECLI_URL if set)
const onecli = new OneCLI();
const active = await onecli.applyContainerConfig(args);
```

### Organization API keys

Organization-level API keys (`oc_org_...`) grant access across all projects in an org. Pass a `projectId` to specify which project to target.

```typescript theme={null}
import { OneCLI } from "@onecli-sh/sdk";

// Set a default project for all operations
const onecli = new OneCLI({
  apiKey: "oc_org_your_org_key",
  projectId: "proj-123",
});

await onecli.createAgent({ name: "Bot", identifier: "bot" });

// Override the project for a specific operation
await onecli.createAgent(
  { name: "Bot", identifier: "bot" },
  { projectId: "proj-456" },
);
```

The `projectId` can also be set via the `ONECLI_PROJECT_ID` environment variable. Per-operation overrides always take precedence over the constructor default.

***

## API reference

### `OneCLI`

Main SDK client.

```typescript theme={null}
new OneCLI(options?: OneCLIOptions)
```

#### Parameters

| Parameter    | Type     | Default                          | Description                                                                 |
| ------------ | -------- | -------------------------------- | --------------------------------------------------------------------------- |
| `apiKey`     | `string` | `process.env.ONECLI_API_KEY`     | API key (`oc_...` for project keys, `oc_org_...` for org keys)              |
| `url`        | `string` | `process.env.ONECLI_URL`         | Base URL of the OneCLI instance                                             |
| `timeout`    | `number` | `5000`                           | Request timeout in milliseconds                                             |
| `gatewayUrl` | `string` | `process.env.ONECLI_GATEWAY_URL` | Gateway URL for manual approval polling (auto-resolved if not set)          |
| `projectId`  | `string` | `process.env.ONECLI_PROJECT_ID`  | Default project ID for org-level API keys (can be overridden per-operation) |

***

#### `onecli.getContainerConfig(options?)`

Fetch the raw container configuration from OneCLI.

```typescript theme={null}
const config = await onecli.getContainerConfig();
console.log(config.env);                    // { HTTPS_PROXY: "...", HTTP_PROXY: "...", ... }
console.log(config.caCertificate);          // PEM-formatted CA certificate
console.log(config.caCertificateContainerPath); // /tmp/onecli-proxy-ca.pem

// Fetch config for a specific agent
const agentConfig = await onecli.getContainerConfig({ agent: "my-agent" });

// With org-level API key, specify the target project
const config = await onecli.getContainerConfig({ projectId: "proj-123" });
```

**Parameters**

| Parameter   | Type     | Description                                                          |
| ----------- | -------- | -------------------------------------------------------------------- |
| `agent`     | `string` | Agent identifier to fetch config for (uses default agent if omitted) |
| `projectId` | `string` | Project ID override for org-level API keys                           |

**Returns**

```typescript theme={null}
{
  env: Record<string, string>;
  caCertificate: string;
  caCertificateContainerPath: string;
}
```

**Throws** `OneCLIRequestError` if OneCLI returns a non-200 response.

***

#### `onecli.applyContainerConfig(args, options?)`

Fetch the container config and push Docker flags onto the `args` array. Returns `true` if config was applied, `false` if OneCLI was unreachable.

```typescript theme={null}
const args = ["run", "-i", "--rm", "my-image"];
const active = await onecli.applyContainerConfig(args, {
  combineCaBundle: true,
  addHostMapping: true,
});
```

**Parameters**

| Parameter         | Type      | Default | Description                                    |
| ----------------- | --------- | ------- | ---------------------------------------------- |
| `combineCaBundle` | `boolean` | `true`  | Build combined CA bundle for system-wide trust |
| `addHostMapping`  | `boolean` | `true`  | Add `host.docker.internal` mapping on Linux    |
| `agent`           | `string`  |         | Agent identifier to fetch config for           |
| `projectId`       | `string`  |         | Project ID override for org-level API keys     |

This method:

1. Fetches `/api/container-config` from OneCLI with Bearer auth
2. Pushes `-e KEY=VALUE` for each environment variable
3. Writes the CA certificate to a temp file and mounts it with `-v`
4. Builds a combined CA bundle (system CAs + OneCLI CA) so all tools trust OneCLI
5. Adds `--add-host host.docker.internal:host-gateway` on Linux

If OneCLI is unreachable, returns `false` without mutating the args array.

***

### Project provisioning

<Info>
  Project provisioning is a **cloud-only** feature. Calling `provisionProject()` against an OSS instance throws `OneCLIError`.
</Info>

#### `onecli.provisionProject(input?, options?)`

Pre-create a user account with a project and API key. The API key works immediately. Requires admin or owner role.

```typescript theme={null}
const result = await onecli.provisionProject({
  role: "member",
  skipOnboarding: true,
});

console.log(result.apiKey);   // oc_... (usable immediately)
console.log(result.claimUrl); // https://app.onecli.sh/claim?token=...
console.log(result.projectId);
```

**Parameters**

| Parameter        | Type                  | Default    | Description                                    |
| ---------------- | --------------------- | ---------- | ---------------------------------------------- |
| `role`           | `"admin" \| "member"` | `"member"` | Role the provisioned user will have in the org |
| `skipOnboarding` | `boolean`             | `true`     | Whether the user skips the onboarding wizard   |

**Options**

| Parameter   | Type     | Description                                |
| ----------- | -------- | ------------------------------------------ |
| `projectId` | `string` | Project ID override for org-level API keys |

**Returns: `ProvisionProjectResponse`**

| Field       | Type     | Description                                              |
| ----------- | -------- | -------------------------------------------------------- |
| `id`        | `string` | Provision record ID                                      |
| `userId`    | `string` | Placeholder user ID (becomes the real user after claim)  |
| `projectId` | `string` | Pre-created project ID                                   |
| `apiKey`    | `string` | API key for the provisioned project (usable immediately) |
| `claimUrl`  | `string` | URL the user visits to claim the account                 |
| `expiresAt` | `string` | Expiration timestamp (ISO 8601)                          |

**Throws** `OneCLIError` if called against an OSS instance. **Throws** `OneCLIRequestError` with status 403 if the API key doesn't belong to an admin/owner.

See the [User Provisioning guide](/guides/user-provisioning) for the full workflow.

***

### Manual approval

#### `onecli.configureManualApproval(callback, options?)`

Register a callback that's invoked whenever an agent request needs human approval. Starts background long-polling to the gateway. Returns a handle to stop polling.

```typescript theme={null}
const handle = onecli.configureManualApproval(async (request) => {
  console.log(`${request.method} ${request.url}`);
  console.log(`Agent: ${request.agent.name}`);

  if (request.bodyPreview) {
    console.log(`Body: ${request.bodyPreview}`);
  }

  // Return 'approve' to forward the request, 'deny' to block it
  return "approve";
});

// Stop polling on shutdown
process.on("SIGTERM", () => handle.stop());
```

The callback is called once per pending approval. Multiple approvals are handled concurrently, and each callback runs independently without blocking the others.

If the callback throws or the decision fails to submit, the same request is retried on the next poll cycle.

**Callback parameter: `ApprovalRequest`**

| Field            | Type                                                       | Description                                         |
| ---------------- | ---------------------------------------------------------- | --------------------------------------------------- |
| `id`             | `string`                                                   | Unique approval ID                                  |
| `method`         | `string`                                                   | HTTP method (`GET`, `POST`, `DELETE`, etc.)         |
| `url`            | `string`                                                   | Full request URL                                    |
| `host`           | `string`                                                   | Hostname                                            |
| `path`           | `string`                                                   | Request path                                        |
| `headers`        | `Record<string, string>`                                   | Sanitized request headers (no credentials)          |
| `bodyPreview`    | `string \| null`                                           | First 4KB of the request body, or `null` if no body |
| `agent`          | `{ id: string; name: string; externalId: string \| null }` | The agent that made the request                     |
| `createdAt`      | `string`                                                   | When the request arrived (ISO 8601)                 |
| `expiresAt`      | `string`                                                   | When the approval expires (ISO 8601)                |
| `timeoutSeconds` | `number`                                                   | Seconds until auto-deny (300)                       |

**Return value:** `ManualApprovalHandle`

| Method   | Description                 |
| -------- | --------------------------- |
| `stop()` | Stop polling and disconnect |

<Note>
  Manual approval requires a [policy rule](/guides/rules#manual-approval) with the **Manual Approval** action configured in the dashboard. Without a matching rule, no requests are held for approval.
</Note>

***

### Error classes

#### `OneCLIError`

General SDK error (e.g., missing API key).

```typescript theme={null}
import { OneCLIError } from "@onecli-sh/sdk";

try {
  const onecli = new OneCLI(); // no apiKey set
  await onecli.getContainerConfig();
} catch (error) {
  if (error instanceof OneCLIError) {
    console.error(error.message);
  }
}
```

#### `OneCLIRequestError`

HTTP request error with additional context.

```typescript theme={null}
import { OneCLIRequestError } from "@onecli-sh/sdk";

try {
  await onecli.getContainerConfig();
} catch (error) {
  if (error instanceof OneCLIRequestError) {
    console.error(error.url);        // Request URL
    console.error(error.statusCode); // HTTP status code
    console.error(error.message);    // [URL=...] [StatusCode=...] ...
  }
}
```

***

### Types

All types are exported for use in your own code:

```typescript theme={null}
import type {
  OneCLIOptions,
  RequestOptions,
  ContainerConfig,
  GetContainerConfigOptions,
  ApplyContainerConfigOptions,
  ApprovalRequest,
  ManualApprovalCallback,
  ManualApprovalHandle,
  ProvisionProjectInput,
  ProvisionProjectResponse,
} from "@onecli-sh/sdk";
```

***

## How it works

OneCLI runs on the host machine and acts as a gateway for containerized agents. When a container makes HTTPS requests to intercepted domains (e.g. `api.anthropic.com`), OneCLI:

1. Terminates TLS using a local CA certificate
2. Inspects the request and injects real credentials (replacing placeholder tokens)
3. Forwards the request to the upstream service
4. Returns the response to the container

**Containers never see real API keys.** They only have placeholder tokens that OneCLI swaps out transparently.

The SDK configures containers with the right environment variables (`HTTPS_PROXY`, `HTTP_PROXY`) and CA certificate mounts so this works automatically.