Quickstart - Declaw

Prerequisites

A Declaw Cloud account — sign up at declaw.ai to get an API key
DECLAW_API_KEY and DECLAW_DOMAIN environment variables set (see Deployment)

Enterprise on-prem customers receive their own DECLAW_DOMAIN from the Declaw team during provisioning. Everything else in this guide is identical.

Install the SDK

Python
TypeScript
Go

pip install declaw

Requires Python 3.10 or later. The package includes both synchronous (Sandbox) and asynchronous (AsyncSandbox) clients.

npm install @declaw/sdk

Requires Node.js 18 or later. All SDK methods return Promises.

Requires Go 1.22 or later. All operations take a context.Context for cancellation and timeouts.

Set environment variables

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

DECLAW_DOMAIN is the hostname of the Declaw API server (api.declaw.ai for Declaw Cloud). DECLAW_API_KEY authenticates your requests. Both are picked up automatically by the SDK — you do not need to pass them explicitly to Sandbox.create().

Get your API key from your dashboard at declaw.ai. Enterprise on-prem customers will receive their own domain and key.

Create a sandbox and run a command

Python
TypeScript
Go

from declaw import Sandbox

sbx = Sandbox.create(template="python", timeout=300)
try:
    result = sbx.commands.run('echo "Hello from Declaw!"')
    print(result.stdout)   # Hello from Declaw!
    print(result.exit_code)  # 0
finally:
    sbx.kill()

Sandbox.create() boots a sandbox and returns once the VM is ready. commands.run() executes the command inside the VM and blocks until it completes. sbx.kill() destroys the VM and releases all resources.

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

const sbx = await Sandbox.create({ template: "python", timeout: 300 });
try {
  const result = await sbx.commands.run('echo "Hello from Declaw!"');
  console.log(result.stdout);    // Hello from Declaw!
  console.log(result.exitCode);  // 0
} finally {
  await sbx.kill();
}

Every Sandbox method is async. Always call sbx.kill() in a finally block to ensure cleanup even if an error occurs.

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(300),
    )
    if err != nil {
        log.Fatal(err)
    }
    defer sbx.Kill(ctx)

    result, err := sbx.Commands.Run(ctx, `echo "Hello from Declaw!"`)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(result.Stdout)   // Hello from Declaw!
    fmt.Println(result.ExitCode) // 0
}

All operations take a context.Context. Always defer sbx.Kill(ctx) to ensure cleanup.

Write a file and run a script

Python
TypeScript
Go

from declaw import Sandbox

sbx = Sandbox.create(template="python", timeout=300)
try:
    # Write a Python script into the sandbox filesystem
    sbx.files.write("/tmp/hello.py", "print('Hello from inside the VM!')\n")

    # Execute it
    result = sbx.commands.run("python3 /tmp/hello.py")
    print(result.stdout)  # Hello from inside the VM!
finally:
    sbx.kill()

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

const sbx = await Sandbox.create({ template: "python", timeout: 300 });
try {
  // Write a script into the sandbox filesystem
  await sbx.files.write("/tmp/hello.py", "print('Hello from inside the VM!')\n");

  // Execute it
  const result = await sbx.commands.run("python3 /tmp/hello.py");
  console.log(result.stdout);  // Hello from inside the VM!
} finally {
  await sbx.kill();
}

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

// Write a Python script into the sandbox filesystem
_, err = sbx.Files.Write(ctx, "/tmp/hello.py", "print('Hello from inside the VM!')\n")
if err != nil {
    log.Fatal(err)
}

// Execute it
result, err := sbx.Commands.Run(ctx, "python3 /tmp/hello.py")
if err != nil {
    log.Fatal(err)
}
fmt.Println(result.Stdout) // Hello from inside the VM!

Add a security policy

Attach a SecurityPolicy at creation time to enable PII redaction, prompt injection defense, network restrictions, and audit logging.

Python
TypeScript
Go

from declaw import Sandbox, SecurityPolicy, PIIConfig, ALL_TRAFFIC

policy = SecurityPolicy(
    pii=PIIConfig(
        enabled=True,
        types=["ssn", "credit_card", "email", "phone"],
        action="redact",
    ),
    injection_defense=True,
    network={"allow_out": ["api.openai.com", "pypi.org"], "deny_out": [ALL_TRAFFIC]},
    audit=True,
)

sbx = Sandbox.create(template="python", timeout=300, security=policy)
try:
    result = sbx.commands.run("python3 -c 'print(2 + 2)'")
    print(result.stdout)  # 4
finally:
    sbx.kill()

With this policy:

Any HTTP request leaving the sandbox that contains a credit card number, SSN, email address, or phone number will have those values replaced with [REDACTED_*] tokens before reaching the external server.
The injection defense model scores every outbound LLM API call and blocks requests above the detection threshold.
Only api.openai.com and pypi.org can be reached. All other outbound connections are dropped.
Every security event is written to the audit log.

import { Sandbox, createSecurityPolicy, createPIIConfig, PIIType, RedactionAction, ALL_TRAFFIC } from "@declaw/sdk";

const policy = createSecurityPolicy({
  pii: createPIIConfig({
    enabled: true,
    types: [PIIType.SSN, PIIType.CreditCard, PIIType.Email, PIIType.Phone],
    action: RedactionAction.Redact,
  }),
  injectionDefense: { enabled: true, action: "block" },
  network: {
    allowOut: ["api.openai.com", "pypi.org"],
    denyOut: [ALL_TRAFFIC],
  },
  audit: { enabled: true },
});

const sbx = await Sandbox.create({
  template: "python",
  timeout: 300,
  security: policy,
});
try {
  const result = await sbx.commands.run("python3 -c 'print(2 + 2)'");
  console.log(result.stdout);  // 4
} finally {
  await sbx.kill();
}

policy := declaw.SecurityPolicy{
    PII: &declaw.PIIConfig{
        Enabled: true,
        Types:   []declaw.PIIType{declaw.PIISSN, declaw.PIICreditCard, declaw.PIIEmail, declaw.PIIPhone},
        Action:  declaw.RedactionActionRedact,
    },
    InjectionDefense: &declaw.InjectionDefenseConfig{
        Enabled: true,
        Action:  declaw.InjectionActionBlock,
    },
    Network: &declaw.NetworkPolicy{
        AllowOut: []string{"api.openai.com", "pypi.org"},
        DenyOut:  []string{"0.0.0.0/0"},
    },
    Audit: &declaw.AuditConfig{Enabled: true},
}

sbx, err := declaw.Create(ctx,
    declaw.WithTemplate("python"),
    declaw.WithTimeout(300),
    declaw.WithSecurity(policy),
)
if err != nil {
    log.Fatal(err)
}
defer sbx.Kill(ctx)

result, err := sbx.Commands.Run(ctx, "python3 -c 'print(2 + 2)'")
if err != nil {
    log.Fatal(err)
}
fmt.Println(result.Stdout) // 4

Next steps

You have created a sandbox, run commands and filesystem operations, and applied a security policy. Where to go next:

Concepts — understand the architecture: sandbox VMs, envd, the security proxy, and how they fit together.
Installation — detailed SDK setup, ConnectionConfig, and all configuration options.
Security overview — the full SecurityPolicy object and all available security controls.
Cookbook — 49 working examples covering LLM integrations, framework adapters, PII rehydration, agent-in-sandbox patterns, and security demos.

​Prerequisites

Prerequisites