Metadata

Attach immutable key-value metadata to sandboxes for tagging, filtering, and tracking.

Configuration

Metadata is configured during sandbox creation using the metadata parameter.

metadatadict[str, str]optional

Immutable key-value metadata to attach to the sandbox. Useful for tagging, filtering, and tracking sandboxes. Stored in-memory only (not persisted across scheduler restarts).

Metadata is set at sandbox creation time and cannot be modified afterwards.

Limits

Limit	Value
Maximum keys	32
Key length	1-64 characters
Key format	Alphanumeric and `_ . -` only
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 metadata parameter:

from concave import Sandbox

# Create with metadata
sbx = Sandbox.create(
    metadata={
        "environment": "production",
        "user_id": "user_12345",
        "region": "us-east"
    }
)

print(f"Sandbox ID: {sbx.id}")
sbx.delete()

Examples

Environment Tagging

from concave import sandbox

with sandbox(metadata={"env": "staging", "app": "api"}) as sbx:
    result = sbx.run("python app.py")
    print(result.stdout)

User Tracking

from concave import Sandbox

def run_user_code(user_id: str, code: str):
    sbx = Sandbox.create(
        metadata={
            "user_id": user_id,
            "request_id": generate_request_id(),
            "timestamp": str(datetime.now())
        }
    )
    
    try:
        result = sbx.run(code)
        return result
    finally:
        sbx.delete()

Multi-tenant Isolation

from concave import Sandbox

# Create isolated sandboxes per tenant
tenant_sbx = Sandbox.create(
    metadata={
        "tenant_id": "acme-corp",
        "org": "engineering",
        "cost_center": "CC-1234"
    }
)

# Use for tenant-specific operations
result = tenant_sbx.execute("./run_tenant_job.sh")
tenant_sbx.delete()

Version Control

from concave import sandbox

with sandbox(
    metadata={
        "version": "v2.1.0",
        "build_id": "build_456",
        "commit_sha": "abc123def"
    }
) as sbx:
    result = sbx.run("pytest tests/")
    print(f"Tests passed: {result.returncode == 0}")