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.

@onecli-sh/sdk

View on npm

Requirements

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

Installation

npm

npm install @onecli-sh/sdk

Quick start

Cloud

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

Self-hosted

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

Environment variables

Instead of passing options explicitly, set environment variables:

Cloud

export ONECLI_API_KEY=oc_your_api_key
# ONECLI_URL defaults to https://api.onecli.sh

Self-hosted

export ONECLI_URL=http://localhost:10254
export ONECLI_API_KEY=oc_your_api_key

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.

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.

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.

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

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

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

Project provisioning is a cloud-only feature. Calling provisionProject() against an OSS instance throws OneCLIError.

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.

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

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

Manual approval requires a policy rule with the Manual Approval action configured in the dashboard. Without a matching rule, no requests are held for approval.

---

Error classes

OneCLIError

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

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.

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:

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.