> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Node.js SDK: Container Config and Provisioning

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

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

> [card] [@trybuckle/sdk](https://www.npmjs.com/package/@trybuckle/sdk)
>
> View on npm

## Requirements

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

## Installation

```bash npm theme={null}
npm install @trybuckle/sdk
```

```bash pnpm theme={null}
pnpm add @trybuckle/sdk
```

```bash yarn theme={null}
yarn add @trybuckle/sdk
```

## Quick start

> [tab] Cloud
>
> ```typescript theme={null}
> import { Buckle } from "@trybuckle/sdk";
>
> // No url needed — defaults to https://api.buckle.dev
> const buckle = new Buckle({
>   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 buckle.applyContainerConfig(args);
>
> // args now contains HTTPS_PROXY, CA certs, and volume mounts
> console.log(active); // true if Buckle was reachable
> ```

> [tab] Self-hosted
>
> ```typescript theme={null}
> import { Buckle } from "@trybuckle/sdk";
>
> const buckle = new Buckle({
>   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 buckle.applyContainerConfig(args);
>
> // args now contains HTTPS_PROXY, CA certs, and volume mounts
> console.log(active); // true if Buckle was reachable
> ```

### Environment variables

Instead of passing options explicitly, set environment variables:

> [tab] Cloud
>
> ```bash theme={null}
> export BUCKLE_API_KEY=oc_your_api_key
> # BUCKLE_URL defaults to https://api.buckle.dev
> ```

> [tab] Self-hosted
>
> ```bash theme={null}
> export BUCKLE_URL=http://localhost:10254
> export BUCKLE_API_KEY=oc_your_api_key
> ```

```typescript theme={null}
import { Buckle } from "@trybuckle/sdk";

// Automatically reads from BUCKLE_API_KEY (and BUCKLE_URL if set)
const buckle = new Buckle();
const active = await buckle.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 { Buckle } from "@trybuckle/sdk";

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

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

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

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

***

## API reference

### `Buckle`

Main SDK client.

```typescript theme={null}
new Buckle(options?: BuckleOptions)
```

#### Parameters

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

***

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

Fetch the raw container configuration from Buckle.

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

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

// With org-level API key, specify the target project
const config = await buckle.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** `BuckleRequestError` if Buckle returns a non-200 response.

***

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

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

```typescript theme={null}
const args = ["run", "-i", "--rm", "my-image"];
const active = await buckle.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 Buckle 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 + Buckle CA) so all tools trust Buckle
5. Adds `--add-host host.docker.internal:host-gateway` on Linux

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

***

### Agents & grants

Create agents and grant each one the credentials it may use (see [Agent access](/docs/guides/agent-access.md)). An agent starts with **no grants** — the gateway injects nothing for it until a connection or secret is attached. Writes take effect immediately.

```typescript theme={null}
const agent = await buckle.createAgent({ name: "Support bot", identifier: "support-bot" });

// Full access to a connection
await buckle.setConnectionGrant(agent.id, "conn_9f2c1b", { access: "full" });

// Or per-tool: `allow` runs freely, `ask` pauses for human approval,
// everything unnamed is blocked
await buckle.setConnectionGrant(agent.id, "conn_9f2c1b", {
  access: "custom",
  allow: ["search_messages", "get_message"],
  ask: ["send_email"],
});

// Secrets are all-or-nothing
await buckle.attachSecret(agent.id, "sec_5e8c02");

// Read intent, or the whole project at a glance
const grants = await buckle.getAgentGrants(agent.id);
const agents = await buckle.listAgentsWithGrants();
```

| Method | Description |
| - | - |
| `createAgent(input, opts?)` / `ensureAgent(input, opts?)` | Create an agent (idempotent with `ensureAgent`) |
| `listAgents(opts?)` / `listAgentsWithGrants(opts?)` | List agents, optionally with per-agent grant summaries |
| `getAgentGrants(agentId, opts?)` | Everything granted to one agent |
| `setConnectionGrant(agentId, connectionId, input, opts?)` | Attach or rewrite a connection grant |
| `removeConnectionGrant(agentId, connectionId, opts?)` | Detach a connection (`204` → resolves `void`) |
| `attachSecret(agentId, secretId, opts?)` / `detachSecret(...)` | Attach / detach a secret |
| `getConnectionGrants(connectionId, opts?)` | The reverse view: which agents hold a grant |
| `getEffectiveCredentials(agentId, opts?)` | Read-only **effective** view once org rules apply |
| `getEffectiveAppPermissions({ provider, agentId? }, opts?)` | Per-tool verdicts for an app |
| `getConnectionAgentAccess(connectionId, opts?)` | Effective per-agent access to a connection |

Two validation laws on custom grants (both `422`): the lists together must name at least one tool (all-blocked = detach instead), and a tool can't be in both. A non-empty `ask` requires a plan with manual approvals (`403`).

***

### Project provisioning

> [!NOTE]
>
> Project provisioning is a **cloud-only** feature. Calling `provisionProject()` against an OSS instance throws `BuckleError`.

#### `buckle.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 buckle.provisionProject({
  role: "member",
  skipOnboarding: true,
});

console.log(result.apiKey);   // oc_... (usable immediately)
console.log(result.claimUrl); // https://app.buckle.dev/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** `BuckleError` if called against an OSS instance. **Throws** `BuckleRequestError` with status 403 if the API key doesn't belong to an admin/owner.

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

***

### Manual approval

#### `buckle.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 = buckle.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` | Human-readable, length-bounded rendering of the request body (safe to display; never raw binary), or `null` |
| `summary` | `object \| null` | Structured form of `bodyPreview` (an `action` label plus key/value `details`), or `null` |
| `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 an allow [policy rule](/docs/guides/rules.md#manual-approval) with **Require approval** set. Without a matching rule, no requests are held for approval.

#### Org policy rules

Author and publish organization policy rules (the staged draft → publish model; see the [Policy rules guide](/docs/guides/rules.md)). Writes publish automatically; pass `{ skipPublish: true }` to stage and review first, since a publish snapshots the **whole** org draft, including changes staged by other users.

```typescript theme={null}
// Create + publish an org-wide block
const { result, generation } = await buckle.org.createPolicyRule({
  name: "Never delete repos",
  action: "block",
  targets: [
    {
      kind: "network",
      hostPattern: "api.github.com",
      pathPattern: "/repos/*",
      method: "DELETE",
    },
  ],
});

// Stage several changes, then publish once
await buckle.org.createPolicyRule(ruleA, { skipPublish: true });
await buckle.org.createPolicyRule(ruleB, { skipPublish: true });
await buckle.org.publishPolicy();

// Read the ENFORCED set (drafts are the default)
const enforced = await buckle.org.listPolicyRules("published");
```

| Method | Description |
| - | - |
| `listPolicyRules(status?)` | List rules: `"draft"` (default) or `"published"` (enforced) |
| `getPolicyRule(id)` | Get one DRAFT rule (published ids regenerate every publish; match by `logicalId`) |
| `createPolicyRule(input, opts?)` | Create (+ publish unless `skipPublish`) |
| `updatePolicyRule(id, input, opts?)` | Update a DRAFT rule (+ publish) |
| `deletePolicyRule(id, opts?)` | Delete a DRAFT rule (+ publish) |
| `reorderPolicyRules(ids, opts?)` | Full-permutation reorder (+ publish) |
| `getPolicyDefault(status?)` / `setPolicyDefault(action, opts?)` | The org's terminal Default Rule |
| `publishPolicy()` | Publish the whole staged draft |
| `getPolicyLastPublish()` | The most recent publish, or `null` |

SDK 3.0.0 removed the legacy `createRule`/`updateRule`/`deleteRule` methods — the `/v1/org/rules` API they called answers `410 Gone` on current servers.

#### `buckle.org.configureManualApproval(callback, options?)`

> [!NOTE]
>
> Organization-scoped approvals require an **organization API key** (`oc_org_...`) and Buckle Cloud or a self-hosted Enterprise instance.

Watch manual-approval requests across **every project** in the organization from a single handler. Identical to `buckle.configureManualApproval`, with two differences: the poll carries no `X-Project-Id` (the organization is derived from the key), and each request includes its own `projectId`, which the SDK uses to route the decision back to the right project.

```typescript theme={null}
const buckle = new Buckle({ apiKey: "oc_org_your_org_key" });

const handle = buckle.org.configureManualApproval(
  async (request) => {
    console.log(`[${request.projectId}] ${request.method} ${request.url}`);
    // Return 'approve' to forward the request, 'deny' to block it
    return "approve";
  },
  {
    onError: (error) => console.error("approval poll failed", error),
  },
);

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

**Callback parameter: `OrgApprovalRequest`**

Every field of `ApprovalRequest` (above), plus:

| Field | Type | Description |
| - | - | - |
| `projectId` | `string` | The project this request belongs to. The decision is routed back to it. |

**Options**

| Field | Type | Description |
| - | - | - |
| `onError` | `(error: unknown) => void` | Called when a poll cycle fails (auth, network, gateway resolution). The loop backs off and retries either way; without a handler these errors are swallowed silently. |

**Return value:** `ManualApprovalHandle` (the same `stop()` handle as the project handler).

***

### Error classes

#### `BuckleError`

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

```typescript theme={null}
import { BuckleError } from "@trybuckle/sdk";

try {
  const buckle = new Buckle(); // no apiKey set
  await buckle.getContainerConfig();
} catch (error) {
  if (error instanceof BuckleError) {
    console.error(error.message);
  }
}
```

#### `BuckleRequestError`

HTTP request error with additional context.

```typescript theme={null}
import { BuckleRequestError } from "@trybuckle/sdk";

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

#### Gateway errors on proxied traffic

Errors the gateway returns on an agent's **proxied** requests (the `409` multiple-accounts protocol, `access_restricted`, `blocked_by_policy`, …) don't throw SDK errors — they arrive on the agent's own HTTP calls. The SDK exports typed bodies and a `parseGatewayError` narrowing helper plus the `CONNECTION_ID_HEADER` / `CONNECTIONS_HEADER` constants for handling them; see [Gateway errors](/docs/api-reference/gateway-errors.md) and [Multiple accounts](/docs/api-reference/multi-account.md).

***

### Types

All types are exported for use in your own code:

```typescript theme={null}
import type {
  BuckleOptions,
  RequestOptions,
  ContainerConfig,
  GetContainerConfigOptions,
  ApplyContainerConfigOptions,
  Agent,
  AgentGrants,
  ConnectionGrantInput,
  ConnectionGrants,
  AgentWithGrantsSummary,
  EffectiveCredentials,
  GatewayError,
  GatewayConnectionChoice,
  ApprovalRequest,
  ManualApprovalCallback,
  ManualApprovalHandle,
  OrgApprovalRequest,
  OrgManualApprovalCallback,
  OrgManualApprovalOptions,
  ProvisionProjectInput,
  ProvisionProjectResponse,
} from "@trybuckle/sdk";
```

***

## How it works

Buckle 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`), Buckle:

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 Buckle swaps out transparently.

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.