Requirements
| SDK | Runtime requirement |
|---|
| Python | Python 3.10 or later |
| TypeScript | Node.js 18 or later |
Install
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"
pyproject.toml project:uv add declaw
# or
poetry add declaw
The package ships with full TypeScript types.With yarn or pnpm:yarn add @declaw/sdk
pnpm add @declaw/sdk
tsconfig.json should include "moduleResolution": "node16" or "bundler".
Configuration
The SDK connects to a Declaw API server. You configure the connection either through environment variables (recommended) or programmatically via ConnectionConfig.
Environment variables
| 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. |
Sandbox.create() without any arguments:
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();
Explicit ConnectionConfig
Pass a ConnectionConfig directly when you need multiple connections, non-standard ports, or explicit control over credentials:
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();
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:
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();
}
Common errors
| Error | Cause | Fix |
|---|
AuthenticationException | DECLAW_API_KEY is missing or invalid | Set the correct key in your environment or ConnectionConfig |
Connection refused | DECLAW_DOMAIN points to an unreachable server | Verify the server is running and the domain/port are correct |
NotFoundException | Sandbox ID does not exist (e.g., it already timed out) | Re-create the sandbox; check your timeout value |
TimeoutException | A command exceeded its timeout | Increase timeout on commands.run() or break the work into smaller steps |
Next steps
