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

# TypeScript SDK

> Install the Declaw TypeScript SDK, configure ConnectionConfig, and create your first sandbox with SandboxOpts.

The Declaw TypeScript SDK is available on [npm](https://www.npmjs.com/package/@declaw/sdk) and targets Node.js 18+ and modern browsers with native `fetch` support.

## Installation

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

## Environment variables

```bash theme={null}
export DECLAW_API_KEY="your-api-key"
export DECLAW_DOMAIN="api.declaw.ai"         # or your enterprise on-prem domain
```

## ConnectionConfig

`ConnectionConfig` holds the API key, domain, port, and base URL. It is constructed automatically when you pass `apiKey` and `domain` to `Sandbox.create()`. Instantiate it directly when you need to share connection settings.

```typescript theme={null}
import { ConnectionConfig } from '@declaw/sdk';

const config = new ConnectionConfig({
  apiKey: 'your-api-key',
  domain: '104.198.24.180:8080',
  requestTimeout: 30_000, // ms
});
```

### `ConnectionConfigOptions`

<ParamField body="apiKey" type="string">
  API key sent as `X-API-Key`. Defaults to `process.env.DECLAW_API_KEY`.
</ParamField>

<ParamField body="domain" type="string" default="process.env.DECLAW_DOMAIN or 'localhost'">
  Hostname of the Declaw API. Supports `host:port` format — the port is
  parsed from the string.
</ParamField>

<ParamField body="port" type="number" default="443">
  Explicit port override. Ignored when `domain` already contains a port.
</ParamField>

<ParamField body="apiUrl" type="string">
  Full URL override (e.g. `http://localhost:8080`). When set, `domain`,
  `port`, and scheme detection are bypassed.
</ParamField>

<ParamField body="requestTimeout" type="number">
  Default per-request HTTP timeout in milliseconds.
</ParamField>

### Properties

| Property                | Type                  | Description                       |
| ----------------------- | --------------------- | --------------------------------- |
| `config.apiKey`         | `string`              | Resolved API key.                 |
| `config.domain`         | `string`              | Resolved hostname (without port). |
| `config.port`           | `number`              | Resolved port.                    |
| `config.apiUrl`         | `string`              | Fully constructed base URL.       |
| `config.requestTimeout` | `number \| undefined` | Default timeout in ms.            |

***

## SandboxOpts

`SandboxOpts` is the options object passed to `Sandbox.create()`.

```typescript theme={null}
import { Sandbox } from '@declaw/sdk';

const sbx = await Sandbox.create({
  template: 'base',
  timeout: 300,
  envs: { MY_VAR: 'hello' },
  apiKey: 'your-api-key',
  domain: '104.198.24.180:8080',
});
```

<ParamField body="template" type="string" default="'base'">
  Template ID or alias to boot.
</ParamField>

<ParamField body="timeout" type="number" default="300">
  Sandbox lifetime in seconds.
</ParamField>

<ParamField body="metadata" type="Record<string, string>">
  Arbitrary key-value pairs attached to the sandbox.
</ParamField>

<ParamField body="envs" type="Record<string, string>">
  Environment variables injected at boot time.
</ParamField>

<ParamField body="secure" type="boolean" default="true">
  Whether to enable the edge proxy security proxy.
</ParamField>

<ParamField body="allowInternetAccess" type="boolean" default="true">
  When `false`, blocks all outbound traffic (`deny_out: ["0.0.0.0/0"]`).
</ParamField>

<ParamField body="network" type="SandboxNetworkOpts">
  Fine-grained network configuration. Overrides `allowInternetAccess`.
</ParamField>

<ParamField body="security" type="SecurityPolicy">
  Full security policy. See [Security Policy](/sdks/typescript/security-policy).
</ParamField>

<ParamField body="lifecycle" type="SandboxLifecycle">
  Sandbox lifecycle settings (`onTimeout`, `autoResume`).
</ParamField>

<ParamField body="apiKey" type="string">
  API key override for this call.
</ParamField>

<ParamField body="domain" type="string">
  Domain override for this call.
</ParamField>

<ParamField body="apiUrl" type="string">
  Full URL override for this call.
</ParamField>

<ParamField body="requestTimeout" type="number">
  Per-request HTTP timeout in milliseconds.
</ParamField>

***

## Quick example

```typescript theme={null}
import { Sandbox } from '@declaw/sdk';

const sbx = await Sandbox.create({
  apiKey: 'your-api-key',
  domain: '104.198.24.180:8080',
});

try {
  const result = await sbx.commands.run("echo 'hello from Declaw'");
  console.log(result.stdout);
} finally {
  await sbx.kill();
}
```

### Using `await using` (TypeScript 5.2+)

```typescript theme={null}
import { Sandbox } from '@declaw/sdk';

await using sbx = await Sandbox.create({
  apiKey: 'your-api-key',
  domain: '104.198.24.180:8080',
});

const result = await sbx.commands.run("node --version");
console.log(result.stdout);
// sbx.close() is called automatically at block exit
```

<Note>
  `await using` calls `sbx.close()` which releases the HTTP client but does
  **not** kill the sandbox. Call `await sbx.kill()` explicitly to destroy the
  sandbox.
</Note>

***

## What's exported

```typescript theme={null}
import {
  // Connection
  ConnectionConfig,
  // Sandbox
  Sandbox,
  // Templates
  Template,
  TemplateBase,
  // Security
  createSecurityPolicy,
  createPIIConfig,
  PIIType,
  RedactionAction,
  createInjectionDefenseConfig,
  InjectionSensitivity,
  InjectionAction,
  createNetworkPolicy,
  createTransformationRule,
  TransformDirection,
  createAuditConfig,
  createEnvSecurityConfig,
  ALL_TRAFFIC,
  // Errors
  SandboxError,
  TimeoutError,
  NotFoundError,
  AuthenticationError,
  CommandExitError,
} from '@declaw/sdk';
```