Patterns¶

Common workflows and mistakes to avoid.

Run Python Script with Local Files¶

// 1. Check for image
{"tool": "list_images", "args": {"tag_prefix": "python"}}

// 2. Import if needed
{"tool": "import_image", "args": {"registry_url": "docker://python:3.11-slim"}}

// 3. Sync files
{"tool": "rsync", "args": {
  "source": "/project", "destination": "/app",
  "exclude": ["__pycache__", ".git", ".venv"]
}}

// 4. Run
{"tool": "run", "args": {
  "command": "python /app/main.py",
  "image": "img-uuid",
  "directory_state_id": "ds-xxx"
}}

Install Dependencies and Save¶

// Save changes with disposable=false
{"tool": "run", "args": {
  "command": "pip install numpy pandas",
  "image": "tag:python:3.11",
  "disposable": false
}}
// Returns: {"result_image": "img-with-deps"}

// Use new image for subsequent runs
{"tool": "run", "args": {
  "command": "python /app/train.py",
  "image": "img-with-deps",
  "directory_state_id": "ds-xxx"
}}

Mistake: Forgetting disposable=false means changes are discarded.

Parallel Execution¶

// Launch async
{"tool": "run", "args": {"command": "python exp_a.py", "image": "img", "wait": false}}
{"tool": "run", "args": {"command": "python exp_b.py", "image": "img", "wait": false}}

// Wait for all
{"tool": "wait_operations", "args": {"operation_ids": ["op-1", "op-2"]}}

Mistake: Using wait=false for single operations adds unnecessary complexity.

Build and Extract Artifact¶

// Build with disposable=false
{"tool": "run", "args": {
  "command": "cargo build --release",
  "image": "tag:rust:1.75",
  "directory_state_id": "ds-project",
  "disposable": false,
  "timeout": 300
}}

// Download result
{"tool": "download", "args": {
  "image": "img-built",
  "path": "/app/target/release/myapp",
  "destination": "./myapp",
  "executable": true
}}

Rollback After Failure¶

// View lineage
contree://image/broken-uuid/lineage
// Returns: {"parent": {"image": "working-parent-uuid"}}

// Continue from working state
{"tool": "run", "args": {
  "command": "python fixed.py",
  "image": "working-parent-uuid"
}}

Common Mistakes¶

Re-syncing unchanged files¶

Wrong: Calling rsync before every run

Right: Sync once, reuse directory_state_id for all runs. Re-sync only when files change.

Importing without checking¶

Wrong: import_image immediately

Right: list_images first to check if image exists

Chaining commands in one string¶

Wrong:

{"command": "apt update && apt install python && pip install numpy && python train.py"}

Right: Run each step separately with disposable=false. Enables rollback if later steps fail.

Using tags for one-off images¶

Wrong: Creating tags for temporary experiments

Right: Use UUIDs directly. Tags are for frequently-reused images.

Not excluding build artifacts¶

Wrong: rsync without exclusions

Right: Always exclude __pycache__, .git, .venv, node_modules, target, dist

Ignoring filesystem_changed¶

When filesystem_changed: false, result_image equals input image - no new snapshot was created.