Skip to main content
The Declaw Python SDK is available on PyPI and supports Python 3.9+.

​
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="104.198.24.180:8080",
    request_timeout=30.0,
)
​
api_key
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.
​
domain
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.
​
port
int
default:"443"
Explicit port override. Ignored when domain already contains a port.
​
api_url
str | None
default:"None"
Full URL override (e.g. http://localhost:8080). When set, domain and port are not used to construct the URL.
​
request_timeout
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 with identical surface areas:
SandboxAsyncSandbox
Importfrom declaw import Sandboxfrom declaw import AsyncSandbox
CreateSandbox.create(...)await AsyncSandbox.create(...)
Context managerwith Sandbox.create(...) as sbx:async with await AsyncSandbox.create(...) as sbx:
Best forScripts, CLI tools, simple agentsConcurrent 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

from declaw import Sandbox

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

​
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,
)