Installation

Requirements

SDK	Runtime requirement
Python	Python 3.10 or later
TypeScript	Node.js 18 or later
Go	Go 1.22 or later

You also need a Declaw API key. Sign up at declaw.ai to use Declaw Cloud, or see the Deployment overview for enterprise on-prem options.

Install

Python
TypeScript
Go

pip install declaw

This installs both the synchronous (Sandbox) and asynchronous (AsyncSandbox) clients, along with all security policy types and model classes.To install a specific version:

pip install "declaw==0.1.0"

To add it to a pyproject.toml project:

uv add declaw
# or
poetry add declaw

npm install @declaw/sdk

The package ships with full TypeScript types.With yarn or pnpm:

yarn add @declaw/sdk
pnpm add @declaw/sdk

The SDK is an ES module. Your tsconfig.json should include "moduleResolution": "node16" or "bundler".

Add it to your go.mod:

go get github.com/declaw-ai/declaw-go

All operations take a context.Context for cancellation and timeouts. Configuration is read from environment variables by default.

Configuration

The SDK connects to a Declaw API server. You configure the connection either through environment variables (recommended) or programmatically via ConnectionConfig.

Environment variables

export DECLAW_API_KEY="your-api-key"
export DECLAW_DOMAIN="your-declaw-instance.example.com:8080"

Variable	Description
`DECLAW_API_KEY`	API key sent as the `X-API-Key` header on every request. Get one from your dashboard at declaw.ai.
`DECLAW_DOMAIN`	Hostname of the Declaw API server. Defaults to `api.declaw.ai` for Declaw Cloud. Enterprise on-prem customers will receive their own domain. Do not include the `https://` scheme.

When these variables are set, you can call Sandbox.create() without any arguments:

Python
TypeScript
Go

from declaw import Sandbox

# Picks up DECLAW_API_KEY and DECLAW_DOMAIN from the environment
sbx = Sandbox.create(template="python", timeout=300)
sbx.kill()

import { Sandbox } from "@declaw/sdk";

// Picks up DECLAW_API_KEY and DECLAW_DOMAIN from the environment
const sbx = await Sandbox.create({ template: "python", timeout: 300 });
await sbx.kill();

import "github.com/declaw-ai/declaw-go"

// Picks up DECLAW_API_KEY and DECLAW_DOMAIN from the environment
sbx, err := declaw.Create(ctx,
    declaw.WithTemplate("python"),
    declaw.WithTimeout(300),
)
if err != nil {
    log.Fatal(err)
}
defer sbx.Kill(ctx)

Explicit ConnectionConfig

Pass a ConnectionConfig directly when you need multiple connections, non-standard ports, or explicit control over credentials:

Python
TypeScript
Go

from declaw import Sandbox, ConnectionConfig

config = ConnectionConfig(
    api_key="your-api-key",
    domain="my-vm.example.com:8080",
)

sbx = Sandbox.create(template="python", timeout=300, connection_config=config)
sbx.kill()

import { Sandbox, ConnectionConfig } from "@declaw/sdk";

const config = new ConnectionConfig({
  apiKey: "your-api-key",
  domain: "my-vm.example.com:8080",
});

const sbx = await Sandbox.create({
  template: "python",
  timeout: 300,
  connectionConfig: config,
});
await sbx.kill();

import "github.com/declaw-ai/declaw-go"

// Sandbox creation accepts SandboxOption functions directly
sbx, err := declaw.Create(ctx,
    declaw.WithTemplate("python"),
    declaw.WithTimeout(300),
)
if err != nil {
    log.Fatal(err)
}
defer sbx.Kill(ctx)

// Account-level operations use ConfigOption functions
account := declaw.NewAccountClient(
    declaw.WithAPIKey("your-api-key"),
    declaw.WithAPIURL("http://my-vm.example.com:8080"),
)
info, err := account.GetAccount(ctx)

Timeout

The timeout parameter on Sandbox.create() sets the maximum lifetime of the sandbox in seconds. If the sandbox is not killed before the timeout, the server destroys it automatically. The default is 300 seconds (5 minutes).

Always call sbx.kill() in a finally block. If your process crashes before calling kill(), the sandbox lives until its timeout expires and continues consuming server resources.

Verify your setup

After installing the SDK and setting your environment variables, run a quick smoke test:

Python
TypeScript
Go

from declaw import Sandbox

sbx = Sandbox.create(template="python", timeout=60)
try:
    result = sbx.commands.run("uname -a")
    print(result.stdout)
    assert result.exit_code == 0
    print("Declaw is working correctly.")
finally:
    sbx.kill()

import { Sandbox } from "@declaw/sdk";

const sbx = await Sandbox.create({ template: "python", timeout: 60 });
try {
  const result = await sbx.commands.run("uname -a");
  console.log(result.stdout);
  if (result.exitCode !== 0) throw new Error("Unexpected exit code");
  console.log("Declaw is working correctly.");
} finally {
  await sbx.kill();
}

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/declaw-ai/declaw-go"
)

func main() {
    ctx := context.Background()
    sbx, err := declaw.Create(ctx,
        declaw.WithTemplate("python"),
        declaw.WithTimeout(60),
    )
    if err != nil {
        log.Fatal(err)
    }
    defer sbx.Kill(ctx)

    result, err := sbx.Commands.Run(ctx, "uname -a")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(result.Stdout)
    fmt.Println("Declaw is working correctly.")
}

If you see a Linux kernel string in the output, your SDK is connected and sandboxes are booting correctly.

Common errors

Error (Python/TS → Go)	Cause	Fix
`AuthenticationException` / `*AuthenticationError`	`DECLAW_API_KEY` is missing or invalid	Set the correct key in your environment or config
`Connection refused`	`DECLAW_DOMAIN` points to an unreachable server	Verify the server is running and the domain/port are correct
`NotFoundException` / `*NotFoundError`	Sandbox ID does not exist (e.g., it already timed out)	Re-create the sandbox; check your timeout value
`TimeoutException` / `*TimeoutError`	A command exceeded its timeout	Increase `timeout` on the run call or break the work into smaller steps

Next steps

Quickstart — five-minute tutorial covering sandboxes, commands, filesystem, and security policies
Deployment overview — stand up a Declaw server on GCP, AWS, Docker, or bare metal
Python SDK reference — full API reference for the Python client
TypeScript SDK reference — full API reference for the TypeScript client
Go SDK reference — full API reference for the Go client

Getting Started

Core Features

CLI

Security

Platform

Deployment

Architecture

Requirements

Install

Configuration

Environment variables

Explicit ConnectionConfig

Timeout

Verify your setup

Common errors

Next steps

​Requirements

​Install

​Configuration

​Environment variables

​Explicit ConnectionConfig

​Timeout

​Verify your setup

​Common errors

​Next steps

Requirements

Install

Configuration

Environment variables

Explicit ConnectionConfig

Timeout

Verify your setup

Common errors

Next steps