Python SDK

The Declaw Python SDK is available on PyPI and supports Python 3.10+.

Installation

pip install declaw

Environment variables

The SDK reads connection settings from environment variables by default.

export DECLAW_API_KEY="your-api-key"
export DECLAW_DOMAIN="api.declaw.ai"      # or your enterprise on-prem domain

ConnectionConfig

ConnectionConfig holds the credentials and endpoint used by every API call. You rarely need to instantiate it directly — Sandbox.create() accepts api_key and domain parameters that build it for you. Use it directly when you need to share connection settings across multiple calls or customise the request timeout.

from declaw import ConnectionConfig

config = ConnectionConfig(
    api_key="your-api-key",
    domain="api.declaw.ai",
    request_timeout=30.0,
)

str

default:"$DECLAW_API_KEY"

API key sent as the X-API-Key header on every request. Defaults to the DECLAW_API_KEY environment variable.

str

default:"$DECLAW_DOMAIN or api.declaw.ai"

Hostname of the Declaw API server. Supports host:port format. Port is parsed from the string and defaults to 443.

int

default:"443"

Explicit port override. Ignored when domain already contains a port.

str | None

default:"None"

Full URL override (e.g. http://localhost:8080). When set, domain and port are not used to construct the URL.

float | None

default:"None"

Default per-request timeout in seconds applied to all HTTP calls made with this config. Individual methods accept a request_timeout parameter that overrides this value.

Sync vs async

The SDK ships two sandbox classes. AsyncSandbox exposes commands and files as awaitable methods on the sandbox (run_command, read_file, write_file, …) rather than the commands and files namespaces; see AsyncSandbox for the full list. Directory watching (files.watch_dir()) and commands.run_stream() are sync-only. To stream a command’s output from async code, use stdio: proc = await sbx.stdio.start(cmd), then await proc.close_stdin() so a command that reads stdin gets end-of-input instead of waiting for it, then async for stream_type, data in proc.

	`Sandbox`	`AsyncSandbox`
Import	`from declaw import Sandbox`	`from declaw import AsyncSandbox`
Create	`Sandbox.create(...)`	`await AsyncSandbox.create(...)`
Context manager	`with Sandbox.create(...) as sbx:`	`async with await AsyncSandbox.create(...) as sbx:`
Run a command	`sbx.commands.run("ls")`	`await sbx.run_command("ls")`
Best for	Scripts, CLI tools, simple agents	Concurrent workloads, multiple sandboxes, FastAPI/async frameworks

Use AsyncSandbox whenever you need to manage multiple sandboxes in parallel or you are running inside an async framework such as FastAPI, LangGraph, or asyncio event loops.

Quick example

Synchronous
Async

from declaw import Sandbox

sbx = Sandbox.create(
    api_key="your-api-key",
    domain="api.declaw.ai",
)
try:
    result = sbx.commands.run("echo 'hello from Declaw'")
    print(result.stdout)
finally:
    sbx.kill()

import asyncio
from declaw import AsyncSandbox

async def main():
    sbx = await AsyncSandbox.create(
        api_key="your-api-key",
        domain="api.declaw.ai",
    )
    async with sbx:
        result = await sbx.run_command("echo 'hello from Declaw'")
        print(result.stdout)
    await sbx.kill()

asyncio.run(main())

What’s exported

The top-level declaw package re-exports every public class, exception, model, and enum:

from declaw import (
    # Connection
    ConnectionConfig,
    # Sandbox
    Sandbox,
    AsyncSandbox,
    # Templates
    Template,
    AsyncTemplate,
    TemplateBase,
    # Security
    SecurityPolicy,
    PIIConfig,
    PIIType,
    RedactionAction,
    InjectionDefenseConfig,
    InjectionAction,
    NetworkPolicy,
    TransformationRule,
    TransformDirection,
    AuditConfig,
    EnvSecurityConfig,
    SecureEnvVar,
    # Models
    SandboxInfo,
    SandboxState,
    SandboxMetrics,
    SandboxQuery,
    SandboxLifecycle,
    SnapshotInfo,
    CommandResult,
    ProcessInfo,
    EntryInfo,
    FileType,
    WriteEntry,
    WriteInfo,
    FilesystemEvent,
    FilesystemEventType,
    # Exceptions
    SandboxException,
    TimeoutException,
    NotFoundException,
    AuthenticationException,
    CommandExitException,
)

TypeScript SDK

Go SDK

Python SDK

Installation

Environment variables

ConnectionConfig

Sync vs async

Quick example

What’s exported

​Installation

​Environment variables

​ConnectionConfig

​Sync vs async

​Quick example

​What’s exported

Installation

Environment variables

ConnectionConfig

Sync vs async

Quick example

What’s exported