REST API reference for sandbox.do - A secure, isolated execution environment for running code with full VM capabilities, git integration, and agent-optimized APIs.

Sandbox API

A secure, isolated execution environment for running code with full VM capabilities, git integration, and agent-optimized APIs.

Endpoint

POST https://api.do/sandbox

Authentication

All API requests require authentication:

curl https://api.do/sandbox \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Request

Headers

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
X-Request-ID: unique-request-id (optional)

Request Body

{
  "operation": "sandbox",
  "parameters": {
    // Operation-specific parameters
  },
  "options": {
    "timeout": 30000,
    "retries": 3
  }
}

Response

Success Response

{
  "success": true,
  "data": {
    // Response data
  },
  "meta": {
    "requestId": "req_123",
    "timestamp": "2025-01-01T12:00:00Z",
    "duration": 145
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid parameters",
    "details": {
      // Error details
    }
  },
  "meta": {
    "requestId": "req_123",
    "timestamp": "2025-01-01T12:00:00Z"
  }
}

Operations

create

Create a new sandbox environment.

curl -X POST https://api.do/sandbox \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "create",
    "parameters": {}
  }'

delete

Permanently remove the sandbox.

curl -X POST https://api.do/sandbox \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "delete",
    "parameters": {}
  }'

execute

Run code within the sandbox.

curl -X POST https://api.do/sandbox \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "execute",
    "parameters": {}
  }'

terminate

Force stop any running sandbox execution.

curl -X POST https://api.do/sandbox \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "terminate",
    "parameters": {}
  }'

clone

Clone a git repository into the sandbox.

curl -X POST https://api.do/sandbox \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "clone",
    "parameters": {}
  }'

checkout

Switch to different branch or commit.

curl -X POST https://api.do/sandbox \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "checkout",
    "parameters": {}
  }'

pull

Pull latest changes from remote repository.

curl -X POST https://api.do/sandbox \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "pull",
    "parameters": {}
  }'

commit

Commit changes in sandbox to git.

curl -X POST https://api.do/sandbox \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "commit",
    "parameters": {}
  }'

push

Push committed changes to remote repository.

curl -X POST https://api.do/sandbox \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "push",
    "parameters": {}
  }'

install

Install dependencies (npm, pip, cargo, etc.).

curl -X POST https://api.do/sandbox \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "install",
    "parameters": {}
  }'

run

Execute shell command in sandbox.

curl -X POST https://api.do/sandbox \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "run",
    "parameters": {}
  }'

read

Read file contents from sandbox filesystem.

curl -X POST https://api.do/sandbox \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "read",
    "parameters": {}
  }'

write

Write content to file in sandbox.

curl -X POST https://api.do/sandbox \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "write",
    "parameters": {}
  }'

logs

Retrieve execution logs from sandbox.

curl -X POST https://api.do/sandbox \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "logs",
    "parameters": {}
  }'

reset

Clear sandbox state and return to initial configuration.

curl -X POST https://api.do/sandbox \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "reset",
    "parameters": {}
  }'

Examples

cURL

curl -X POST https://api.do/sandbox \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "sandbox",
    "parameters": {}
  }'

JavaScript/TypeScript

const response = await fetch('https://api.do/sandbox', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    operation: 'sandbox',
    parameters: {},
  }),
})

const data = await response.json()

Python

import requests

response = requests.post(
    'https://api.do/sandbox',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'operation': 'sandbox',
        'parameters': {}
    }
)

data = response.json()

Rate Limiting

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1609459200

Status Codes

200 OK - Success
400 Bad Request - Invalid request
401 Unauthorized - Missing/invalid API key
403 Forbidden - Insufficient permissions
404 Not Found - Resource not found
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Server error
503 Service Unavailable - Service temporarily unavailable

Error Codes

VALIDATION_ERROR - Invalid parameters
AUTHENTICATION_ERROR - Invalid API key
AUTHORIZATION_ERROR - Insufficient permissions
NOT_FOUND - Resource not found
RATE_LIMIT_EXCEEDED - Too many requests
TIMEOUT - Operation timeout
INTERNAL_ERROR - Server error

Webhooks

Subscribe to events:

curl -X POST https://api.do/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhook",
    "events": ["sandbox.created", "sandbox.deleted", "sandbox.executed", "sandbox.terminated", "sandbox.Repository.cloned", "sandbox.Branch.checkedOut", "sandbox.Changes.pulled", "sandbox.Changes.committed", "sandbox.Commits.pushed", "sandbox.Packages.installed", "sandbox.Command.executed", "sandbox.File.read", "sandbox.File.written", "sandbox.reset", "sandbox.Permission.violated", "sandbox.Limit.exceeded"]
  }'

Best Practices

API Keys - Store securely, never commit to git
Error Handling - Handle all error codes gracefully
Retries - Implement exponential backoff
Rate Limiting - Respect rate limits
Idempotency - Use X-Idempotency-Key header
Logging - Log requests for debugging

Sandbox API

On this page