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
) -> Sandbox

Parameters

internet_accessbooleanoptional

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

metadatadict[str, str]optional

Immutable key-value metadata to attach to the sandbox. Useful for tagging, filtering, and tracking sandboxes.

envdict[str, str]optional

Custom environment variables to inject into the sandbox. Available in all code executions via os.environ.

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

Use context managers for short-lived operations, quick tests, or when you want automatic cleanup. Perfect 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()

Use manual lifecycle management for persistent sandboxes, long-running operations, or when you need to pass sandbox 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}")