Skip to content

Latest commit

 

History

History
195 lines (142 loc) · 5.97 KB

README.md

File metadata and controls

195 lines (142 loc) · 5.97 KB

@onecli-sh/sdk

Official Node.js SDK for OneCLI. Route AI agent traffic through the OneCLI proxy — agents never see real credentials.

Documentation  |  Website  |  GitHub

npm version MIT License Node.js version

Installation

pnpm add @onecli-sh/sdk

Requirements

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

Quick Start

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

// Reads ONECLI_API_KEY and ONECLI_URL from environment
const onecli = new OneCLI();

const args = ["run", "-i", "--rm", "--name", "my-agent"];
const active = await onecli.applyContainerConfig(args);
// args now contains proxy env vars and CA certificate mounts
console.log(active); // true if OneCLI was reachable

Explicit configuration

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

const onecli = new OneCLI({
  apiKey: "oc_...",                    // optional: falls back to ONECLI_API_KEY env var
  url: "http://localhost:3000",        // optional: falls back to ONECLI_URL env var, then https://app.onecli.sh
});

// Get raw container configuration
const config = await onecli.getContainerConfig();
console.log(config.env);              // { HTTPS_PROXY: "...", HTTP_PROXY: "...", ... }
console.log(config.caCertificate);    // PEM content

// Or apply directly to Docker run args
const args = ["run", "-i", "--rm", "my-image"];
const active = await onecli.applyContainerConfig(args);

Environment variables

Variable Description
ONECLI_API_KEY User API key (oc_...). Used when apiKey is not passed to constructor.
ONECLI_URL Base URL of OneCLI instance. Defaults to https://app.onecli.sh.

API Reference

OneCLI

Main SDK client.

new OneCLI(options?: OneCLIOptions)
Option Type Required Default Description
apiKey string No ONECLI_API_KEY env var User API key (oc_...)
url string No ONECLI_URL or https://app.onecli.sh Base URL of the OneCLI instance
timeout number No 5000 Request timeout in milliseconds

onecli.getContainerConfig()

Fetch the raw container configuration from OneCLI.

const config = await onecli.getContainerConfig();
// Returns: { env, caCertificate, caCertificateContainerPath }

Throws OneCLIRequestError on non-200 response.

onecli.applyContainerConfig(args, options?)

Fetch config and push Docker flags onto the args array. Returns true on success, false on failure (graceful degradation).

const active = await onecli.applyContainerConfig(args, {
  combineCaBundle: true,  // Merge system + OneCLI CAs (default: true)
  addHostMapping: true,   // Add --add-host on Linux (default: true)
});
Option Type Default Description
combineCaBundle boolean true Build combined CA bundle for system-wide trust
addHostMapping boolean true Add host.docker.internal mapping on Linux

What it does:

  1. Fetches /api/container-config with Authorization: Bearer {apiKey}
  2. Pushes -e KEY=VALUE for each server-controlled environment variable
  3. Writes CA certificate to a temp file and mounts it into the container
  4. Builds a combined CA bundle (system CAs + OneCLI CA) so curl, Python, Go, etc. also trust OneCLI
  5. Adds --add-host host.docker.internal:host-gateway on Linux

Error Classes

OneCLIError

General SDK error (e.g. missing apiKey).

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

OneCLIRequestError

HTTP request error with url and statusCode properties.

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

Types

import type {
  OneCLIOptions,
  ContainerConfig,
  ApplyContainerConfigOptions,
} from "@onecli-sh/sdk";

How It Works

OneCLI acts as a MITM proxy 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
  3. Forwards the request to the upstream service

Containers never see real API keys. The SDK configures containers with the right environment variables (HTTPS_PROXY, HTTP_PROXY, NODE_EXTRA_CA_CERTS) and CA certificate mounts so this works automatically.

Development

pnpm install       # Install dependencies
pnpm run build     # Build CJS + ESM
pnpm run typecheck # Type-check without emitting
pnpm run test      # Run tests
pnpm run dev       # Watch mode

License

MIT