Create Sandbox

Create a new isolated sandbox environment for running code securely.

Sandbox.create(
    internet_access: bool = True,
    metadata: Optional[dict[str, str]] = None,
    env: Optional[dict[str, str]] = None,
    lifetime: Optional[str] = None
) -> Sandbox

Disk size is ~200MB for temporary files and package installations.

Parameters

internet_accessbooleanoptional

Enable or disable internet access for the sandbox. Default value is True.

metadatadict[str, str]optional

Key-value pairs for tagging and tracking sandboxes.

envdict[str, str]optional

Custom environment variables to set in the sandbox for all code executions.

lifetimestroptional

How long the sandbox remains active (e.g., "1h"). Min: 1m, Max: 48h, Default: 24h.

Returns

Returns a Sandbox instance that can be used to interact with the created sandbox.

Context ManagerRecommended

The simplest way to use sandboxes is with a context manager. The sandbox is automatically created when entering the with block and deleted when exiting.

from concave import sandbox

with sandbox() as sbx:
    result = sbx.run("print('Hello World')")
    print(result.stdout)
# Sandbox is automatically deleted here

Best for short-lived operations and automatic cleanup. Recommended for most use cases.

Manual Lifecycle Management

For long-running operations or when you need more control, you can manually manage the sandbox lifecycle.

from concave import Sandbox

# Create a sandbox
sbx = Sandbox.create()

# Use it for multiple operations
result1 = sbx.execute("ls -la")
result2 = sbx.run("import sys; print(sys.version)")

# Delete when done
sbx.delete()

Best for persistent sandboxes, long-running operations, and passing instances between functions.

Examples

Basic Create

from concave import Sandbox

# Create a sandbox with default settings
sbx = Sandbox.create()

# Use the sandbox
result = sbx.run("print('Hello from Concave!')")
print(result.stdout)

# Clean up
sbx.delete()

Create with Configuration

from concave import Sandbox

# Create with internet access and metadata
sbx = Sandbox.create(
    internet_access=True,
    metadata={
        "environment": "production",
        "user_id": "user_12345"
    }
)

# Use the sandbox
result = sbx.run("print('Hello from Concave!')")
print(result.stdout)

# Clean up
sbx.delete()

Exceptions

SandboxCreationErrorException

Raised when sandbox creation fails due to service errors.

SandboxAuthenticationErrorException

Raised when API key is invalid or missing.

SandboxTimeoutErrorException

Raised when sandbox creation times out (exceeds 30 seconds).

ValueErrorException

Raised when api_key is not provided and CONCAVE_SANDBOX_API_KEY environment variable is not set.

Error Handling

from concave import (
    Sandbox,
    SandboxCreationError,
    SandboxAuthenticationError
)

try:
    sbx = Sandbox.create()
    print(f"Sandbox created: {sbx.id}")
except SandboxAuthenticationError as e:
    print(f"Authentication failed: {e}")
except SandboxCreationError as e:
    print(f"Creation failed: {e}")
except ValueError as e:
    print(f"Invalid parameters: {e}")