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

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

​
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,
} 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.