Skip to main content
The Sandbox API provides secure, isolated environments for executing shell commands. Each sandbox is a temporary container that runs independently, perfect for running untrusted code or testing scripts.

​
What you’ll build

In this quickstart, you’ll learn how to:
  • Create a sandbox environment
  • Execute shell commands
  • Capture output and exit codes
  • Transfer files between disk and sandbox
  • Clean up when finished

​
Prerequisites

Before you begin, ensure you have:

​
Initialize the client

First, create a client instance with your API key. 
import os
from acontext import AcontextClient

client = AcontextClient(
    api_key=os.getenv("ACONTEXT_API_KEY"),
)

# If you're using self-hosted Acontext:
# client = AcontextClient(
#     base_url="http://localhost:8029/api/v1",
#     api_key="sk-ac-your-root-api-bearer-token",
# )
Never hardcode API keys in production code. Use environment variables instead.

​
Step-by-step tutorial

1

Create a sandbox

Create a new isolated sandbox environment.
# Create a new sandbox
sandbox = client.sandboxes.create()

print(f"Sandbox ID: {sandbox.sandbox_id}")
print(f"Status: {sandbox.sandbox_status}")
print(f"Expires at: {sandbox.sandbox_expires_at}")
The sandbox object contains:
  • sandbox_id: Unique sandbox identifier
  • sandbox_status: Current status (running, killed, paused, error)
  • sandbox_created_at: ISO 8601 creation timestamp
  • sandbox_expires_at: ISO 8601 expiration timestamp
Save the sandbox ID - you’ll need it to execute commands.
2

Execute a command

Run a shell command inside the sandbox and capture the output.
# Execute a command
result = client.sandboxes.exec_command(
    sandbox_id=sandbox.sandbox_id,
    command="echo 'Hello from sandbox!' && pwd"
)

print(f"stdout: {result.stdout}")
print(f"stderr: {result.stderr}")
print(f"exit_code: {result.exit_code}")
The response includes:
  • stdout: Standard output from the command
  • stderr: Standard error from the command
  • exit_code: Exit code (0 for success)
Chain multiple commands with && or ; to run them sequentially in a single call.
3

Kill the sandbox

Terminate the sandbox when you’re done.
# Kill the sandbox
client.sandboxes.kill(sandbox.sandbox_id)
print("Sandbox terminated")
Sandboxes automatically expire after a timeout(default 30 minutes). Always kill sandboxes when finished to free up resources.

​
Complete example

Here’s a complete working example that demonstrates the full workflow: 
import os
from acontext import AcontextClient

def main():
    # Initialize client
    client = AcontextClient(
        api_key=os.getenv("ACONTEXT_API_KEY"),
    )
    
    try:
        # Create sandbox
        sandbox = client.sandboxes.create()
        print(f"✓ Created sandbox: {sandbox.sandbox_id}")
        
        # Execute commands
        result = client.sandboxes.exec_command(
            sandbox_id=sandbox.sandbox_id,
            command="python3 --version"
        )
        print(f"✓ Python version: {result.stdout.strip()}")
        
        # Run a Python script
        result = client.sandboxes.exec_command(
            sandbox_id=sandbox.sandbox_id,
            command="python3 -c 'print(sum(range(10)))'"
        )
        print(f"✓ Script output: {result.stdout.strip()}")
        
        # Clean up
        client.sandboxes.kill(sandbox.sandbox_id)
        print("✓ Sandbox terminated")
        
    except Exception as e:
        print(f"✗ Error: {e}")

if __name__ == "__main__":
    main()

​
Filesystem

Use the Disk API to persist files and transfer them to/from sandboxes. This enables workflows where you prepare files, process them in a sandbox, and save the results.
1

Create a disk and sandbox

Set up both a disk for persistent storage and a sandbox for execution.
# Create a disk for file storage
disk = client.disks.create()
print(f"Disk ID: {disk.id}")

# Create a sandbox for execution
sandbox = client.sandboxes.create()
print(f"Sandbox ID: {sandbox.sandbox_id}")
2

Upload a file to disk

Upload a file to your disk that you want to process in the sandbox.
from acontext import FileUpload

# Upload a script to the disk
artifact = client.disks.artifacts.upsert(
    disk.id,
    file=FileUpload(
        filename="data.txt",
        content=b"Hello from disk!\nProcess this in sandbox."
    ),
    file_path="/input/"
)
print(f"Uploaded: {artifact.path}{artifact.filename}")
3

Download file to sandbox

Transfer the file from disk to the sandbox filesystem.
# Download artifact to sandbox
success = client.disks.artifacts.download_to_sandbox(
    disk_id=disk.id,
    file_path="/input/",
    filename="data.txt",
    sandbox_id=sandbox.sandbox_id,
    sandbox_path="/workspace/"
)
print(f"Download success: {success}")

# Verify the file exists in sandbox
result = client.sandboxes.exec_command(
    sandbox_id=sandbox.sandbox_id,
    command="cat /workspace/data.txt"
)
print(f"File content: {result.stdout}")
The file is copied to the sandbox at the specified path. The original filename is preserved.
4

Process and create output

Run commands in the sandbox to process files and generate output.
# Process the file and create output
client.sandboxes.exec_command(
    sandbox_id=sandbox.sandbox_id,
    command="wc -l /workspace/data.txt > /workspace/result.txt"
)

# Verify the output
result = client.sandboxes.exec_command(
    sandbox_id=sandbox.sandbox_id,
    command="cat /workspace/result.txt"
)
print(f"Result: {result.stdout}")
5

Upload result to disk

Save the processed output from the sandbox back to persistent disk storage.
# Upload the result from sandbox to disk
uploaded = client.disks.artifacts.upload_from_sandbox(
    disk_id=disk.id,
    sandbox_id=sandbox.sandbox_id,
    sandbox_path="/workspace/",
    sandbox_filename="result.txt",
    file_path="/output/"
)
print(f"Saved: {uploaded.path}{uploaded.filename}")

# Verify by reading from disk
artifact_info = client.disks.artifacts.get(
    disk.id,
    file_path="/output/",
    filename="result.txt",
    with_content=True
)
print(f"Persisted content: {artifact_info.content.raw}")
Your processed file is now safely stored on the disk and will persist after the sandbox is terminated.
6

Clean up

Terminate the sandbox when processing is complete.
# Kill the sandbox (disk persists)
client.sandboxes.kill(sandbox.sandbox_id)
print("Sandbox terminated, files preserved on disk")
The disk and its files remain available after the sandbox is killed. You can download them later or transfer to a new sandbox.

​
Complete example

Here’s a complete working example that demonstrates the full disk-sandbox file transfer workflow: 
import os
from acontext import AcontextClient, FileUpload

def main():
    client = AcontextClient(
        api_key=os.getenv("ACONTEXT_API_KEY"),
    )
    
    try:
        # Create disk and sandbox
        disk = client.disks.create()
        sandbox = client.sandboxes.create()
        print(f"✓ Created disk: {disk.id}")
        print(f"✓ Created sandbox: {sandbox.sandbox_id}")
        
        # Upload input file to disk
        client.disks.artifacts.upsert(
            disk.id,
            file=FileUpload(filename="input.txt", content=b"Line 1\nLine 2\nLine 3"),
            file_path="/input/"
        )
        print("✓ Uploaded input file to disk")
        
        # Download to sandbox
        client.disks.artifacts.download_to_sandbox(
            disk_id=disk.id,
            file_path="/input/",
            filename="input.txt",
            sandbox_id=sandbox.sandbox_id,
            sandbox_path="/workspace/"
        )
        print("✓ Downloaded file to sandbox")
        
        # Process in sandbox
        client.sandboxes.exec_command(
            sandbox_id=sandbox.sandbox_id,
            command="wc -l /workspace/input.txt > /workspace/output.txt"
        )
        print("✓ Processed file in sandbox")
        
        # Upload result back to disk
        client.disks.artifacts.upload_from_sandbox(
            disk_id=disk.id,
            sandbox_id=sandbox.sandbox_id,
            sandbox_path="/workspace/",
            sandbox_filename="output.txt",
            file_path="/output/"
        )
        print("✓ Uploaded result to disk")
        
        # Verify result
        result = client.disks.artifacts.get(
            disk.id,
            file_path="/output/",
            filename="output.txt",
            with_content=True
        )
        print(f"✓ Result: {result.content.raw.strip()}")
        
        # Cleanup
        client.sandboxes.kill(sandbox.sandbox_id)
        client.disks.delete(disk.id)
        print("✓ Cleaned up resources")
        
    except Exception as e:
        print(f"✗ Error: {e}")

if __name__ == "__main__":
    main()

​
Common use cases

Code execution

Run user-submitted code safely in an isolated environment without risking your host system.

Script testing

Test shell scripts, installation procedures, or build processes in a clean environment.

Agent tools

Give AI agents the ability to execute commands and interact with a file system safely.

Data processing

Run data transformation scripts or command-line tools on files without affecting your main system.

​
Troubleshooting

Problem: Command takes too long and times out.Solution:
  • Break long-running commands into smaller steps
  • Check if the command is waiting for input (use non-interactive flags)
  • Consider running background processes if needed
Problem: Getting a 404 error when executing commands.Solution:
  • Verify the sandbox ID is correct
  • Check if the sandbox has expired or been killed
  • Create a new sandbox if the previous one is no longer available
Problem: Command returns a non-zero exit code.Solution:
  • Check stderr for error messages
  • Verify the command syntax is correct
  • Ensure required tools are available in the sandbox environment