Skip to main content
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 versionNode.js version
>= 0.1.0>= 20

​
Installation

npm install @onecli-sh/sdk

​
Quick start

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: 
export ONECLI_URL=http://localhost:10254
export ONECLI_API_KEY=oc_your_api_key

import { OneCLI } from "@onecli-sh/sdk";

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

​
API reference

​
OneCLI

Main SDK client. 
new OneCLI(options?: OneCLIOptions)

​
Parameters

ParameterTypeDefaultDescription
apiKeystringprocess.env.ONECLI_API_KEYAPI key (must start with oc_)
urlstringprocess.env.ONECLI_URLBase URL of the OneCLI instance
timeoutnumber5000Request timeout in milliseconds
gatewayUrlstringprocess.env.ONECLI_GATEWAY_URLGateway URL for manual approval polling (auto-resolved if not set)

​
onecli.getContainerConfig()

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
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
ParameterTypeDefaultDescription
combineCaBundlebooleantrueBuild combined CA bundle for system-wide trust
addHostMappingbooleantrueAdd host.docker.internal mapping on Linux
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.

​
Manual Approval

​
onecli.configureManualApproval(callback)

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
FieldTypeDescription
idstringUnique approval ID
methodstringHTTP method (GET, POST, DELETE, etc.)
urlstringFull request URL
hoststringHostname
pathstringRequest path
headersRecord<string, string>Sanitized request headers (no credentials)
bodyPreviewstring | nullFirst 4KB of the request body, or null if no body
agent{ id: string; name: string; externalId: string | null }The agent that made the request
createdAtstringWhen the request arrived (ISO 8601)
expiresAtstringWhen the approval expires (ISO 8601)
timeoutSecondsnumberSeconds until auto-deny (300)
Return value: ManualApprovalHandle
MethodDescription
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,
  ContainerConfig,
  ApplyContainerConfigOptions,
  ApprovalRequest,
  ManualApprovalCallback,
  ManualApprovalHandle,
} 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.