Environment Variables

Inject custom environment variables and access default metadata.

Configuration

Custom environment variables are configured during sandbox creation using the env parameter.

envdict[str, str]optional

Variables injected with their exact names (no CONCAVE_ prefix).

Environment variables are set at sandbox creation time and cannot be modified afterwards.

Limits

Limit	Value
Maximum keys	32
Key length	1-64 characters
Key format	Must start with letter or underscore, followed by alphanumeric or underscore
Value size	Up to 1024 bytes (UTF-8)
Total size	4096 bytes (sum of all keys and values)

Basic Usage

Pass a dictionary to the env parameter:

from concave import Sandbox

with Sandbox.create(env={"API_KEY": "secret123"}) as sbx:
    result = sbx.execute("echo API Key: $API_KEY")
    print(result.stdout)

Default Variables

All sandboxes have access to the following environment variables prefixed with CONCAVE_:

Variable	Description
`CONCAVE_SANDBOX`	Always `true` to indicate code is running in a Concave sandbox
`CONCAVE_SANDBOX_ID`	Unique identifier for this sandbox instance
`CONCAVE_VERSION`	Concave platform version (e.g., `1.0`)
`CONCAVE_NAME`	Platform name (`Concave Sandbox`)
`CONCAVE_DESCRIPTION`	Brief description of the sandbox environment
`CONCAVE_CREATED_AT`	ISO 8601 timestamp when the sandbox was created
`CONCAVE_EXPIRES_AT`	ISO 8601 timestamp when the sandbox will expire (24 hours from creation)
`CONCAVE_IP`	Internal IP address of the sandbox
`CONCAVE_GATEWAY_IP`	Gateway IP address for network routing
`CONCAVE_INTERNET_ACCESS`	`true` or `false` indicating internet connectivity
`CONCAVE_CPU_COUNT`	Number of virtual CPUs allocated to the sandbox
`CONCAVE_MEMORY_MIB`	Memory allocated in mebibytes (MiB)
`CONCAVE_DISK_GB`	Disk space allocated in gigabytes (GB)
`CONCAVE_KERNEL_VERSION`	Linux kernel version running in the sandbox

Examples

API Keys and Secrets

from concave import sandbox

# Inject API keys securely
with sandbox(env={"API_KEY": "sk_live_...", "API_URL": "https://api.example.com"}) as sbx:
    result = sbx.run("""
import os
import requests

# Access custom env vars
api_key = os.environ.get('API_KEY')
api_url = os.environ.get('API_URL')

# Make authenticated request
response = requests.get(f"{api_url}/data", headers={"Authorization": f"Bearer {api_key}"})
print(f"Status: {response.status_code}")
    """)
    print(result.stdout)

Network Detection

from concave import Sandbox

with Sandbox.create(internet_access=False) as sbx:
    result = sbx.run("""
import os

# Check internet access before making requests
has_internet = os.environ.get('CONCAVE_INTERNET_ACCESS') == 'true'

if has_internet:
    import requests
    response = requests.get('https://api.example.com')
else:
    print("No internet access - using cached data")
    """)
    print(result.stdout)

Combining Default and Custom Variables

from concave import Sandbox

with Sandbox.create(env={"APP_ENV": "production", "DEBUG": "false"}) as sbx:
    result = sbx.run("""
import os

# Access both default and custom variables
sandbox_id = os.environ.get('CONCAVE_SANDBOX_ID')
app_env = os.environ.get('APP_ENV')
debug = os.environ.get('DEBUG') == 'true'

print(f"Running in sandbox: {sandbox_id}")
print(f"Environment: {app_env}")
print(f"Debug mode: {debug}")
    """)
    print(result.stdout)

Errors

SandboxValidationErrorException

Raised when environment variables exceed limits (more than 32 keys, values over 1024 bytes, etc.).

SandboxNotFoundErrorException

Raised when the sandbox no longer exists.

If initialization fails, sandbox is still created with response "warning": "env init failed".