StateSet API Docs

Use the Python SDK to create sandboxes, execute commands, and manage files.

Install

pip install stateset-sandbox

Initialize the Client

from stateset_sandbox import SandboxClient

client = SandboxClient(
    base_url="https://api.sandbox.stateset.app",
    api_key="sk-sandbox-YOUR_API_KEY",
    org_id="org_YOUR_ORG_ID",
)

Create and Execute

sandbox = client.create(timeout_seconds=300)
result = client.execute(
    sandbox_id=sandbox["sandbox_id"],
    command=["python3", "-c", "print('Hello from Stateset!')"],
)

File Operations

client.write_files(
    sandbox_id=sandbox["sandbox_id"],
    files=[{"path": "/workspace/hello.txt", "content": "SGVsbG8h", "encoding": "base64"}],
)

file = client.read_files(sandbox_id=sandbox["sandbox_id"], paths=["/workspace/hello.txt"])

File content crosses the wire as base64 in both directions — SGVsbG8h above is Hello!. Passing raw text writes the literal characters of your string rather than the bytes you meant.

Cleanup

client.stop(sandbox_id=sandbox["sandbox_id"])

A sandbox runs, and bills, until it is stopped or timeout_seconds expires. Stop it in a finally block so a raised exception does not leave one up:

sandbox = client.create(timeout_seconds=300)
try:
    result = client.execute(
        sandbox_id=sandbox["sandbox_id"],
        command=["python3", "-c", "print('hello')"],
    )
    print(result["stdout"])
finally:
    client.stop(sandbox_id=sandbox["sandbox_id"])

Handling failures

execute returns for a command that ran and failed — a non-zero exit is a result, not an exception. Check exit_code yourself; only transport and API errors raise.

result = client.execute(
    sandbox_id=sandbox["sandbox_id"],
    command=["npm", "run", "build"],
)

if result["exit_code"] != 0:
    raise RuntimeError(f"build failed ({result['exit_code']}): {result['stderr']}")

Next steps

Sandbox quickstart

The wider flow, including REPL sessions and checkpoints.

API reference

Every endpoint this SDK wraps.

Node SDK

The same surface for Node services.

Security guide

What a sandboxed process can and cannot reach.

Last modified on August 31, 2026

Get started

Platform

Using the APIs

StateSet Response

StateSet ResponseCX

Temporal Engine

StateSet iCommerce Engine

StateSet iCommerce EDI Engine

StateSet Mail

StateSet iCommerce Voice Engine

StateSet iCommerce NSR Engine

AI Agents

StateSet Agents

StateSet iCommerce Sandbox Engine

StateSet ACP

StateSet UCP

StateSet ICP

StateSet Sequencer

StateSet Set L2

StateSet Cloud

Apps & Consoles

Tools

Sandbox SDK (Python)

Install

Initialize the Client

Create and Execute

File Operations

Cleanup

Handling failures

Next steps

Sandbox quickstart

API reference

Node SDK

Security guide

​Install

​Initialize the Client

​Create and Execute

​File Operations

​Cleanup

​Handling failures

​Next steps

Sandbox quickstart

API reference

Node SDK

Security guide

Install

Initialize the Client

Create and Execute

File Operations

Cleanup

Handling failures

Next steps