Core Concepts

​

Execution Model

1. Spins up an isolated microVM (~2-5 seconds)
2. Mounts the specified image as the filesystem
3. Injects any files from directory_state_id or files
4. Executes your command as root
5. Captures stdout, stderr, exit code
6. Optionally saves the resulting filesystem as a new image

​

The disposable Flag

• When true, result_image is a new UUID (changes were saved)
• When false, result_image equals input image (no snapshot created)

​

Images

• Immutable: Once created, it never changes
• Identified by UUID: abc123-def456-789012
• Optionally tagged: Human-readable names like python:3.11

​

Lineage

docker://alpine:latest (img-root)
    └── apk add python3 (img-with-python)
        ├── pip install numpy (img-with-numpy)
        └── pip install pandas (img-with-pandas)

contree://image/{uuid}/lineage

​

Timeouts and Output

• Default timeout: 30 seconds (use timeout parameter for longer)
• Default output limit: 8000 bytes (~2000 tokens)
• Adjust with: truncate_output_at parameter