Debugging

After each run, VM0 outputs a Checkpoint ID that references a snapshot of the conversation and artifact at that moment.

Resume from Checkpoint

Use vm0 run resume to go back to a snapshot point:

vm0 run resume <checkpoint-id> "try a different approach"

Uses snapshotted conversation history
Uses snapshotted artifact version
Best for branching or trying alternatives

Multi-Step Debugging

For complex workflows, you can debug step by step using checkpoints.

Example: A 3-step workflow

Step 1 - Run the first step:

vm0 run my-agent "do step 1" --artifact-name my-project
# Outputs: checkpoint-id-1

Step 2 - Check the results, then resume:

# View logs from step 1
vm0 logs <run-id-1>

# Check artifact state
vm0 artifact pull

# Resume to step 2
vm0 run resume <checkpoint-id-1> "do step 2"
# Outputs: checkpoint-id-2

Step 3 - Repeat:

# View logs from step 2
vm0 logs <run-id-2>

# Resume to step 3
vm0 run resume <checkpoint-id-2> "do step 3"

This approach lets you:

Observe the agent's progress at each step
Inspect logs and artifact state between steps
Retry a step with different prompts if needed
Branch from any checkpoint to try alternative approaches

Viewing Logs

View logs from a completed run:

vm0 logs <run-id>

By default, this shows the last 5 agent event entries.

Log Types

The vm0 logs command supports four log types. These flags are mutually exclusive — you can only use one at a time:

Flag	Description
`-a`, `--agent`	Show agent events (default)
`-s`, `--system`	Show system log
`-m`, `--metrics`	Show metrics (CPU, memory, disk)
`-n`, `--network`	Show network logs (proxy traffic)

# View system log
vm0 logs <run-id> --system

# View metrics
vm0 logs <run-id> --metrics

# View network traffic
vm0 logs <run-id> --network

Pagination

Control how many entries are displayed with --tail, --head, or --all. These flags are mutually exclusive:

Flag	Description
`--tail <n>`	Show last N entries (default: 5)
`--head <n>`	Show first N entries
`--all`	Fetch all log entries

# Show last 100 entries
vm0 logs <run-id> --tail 100

# Show first 50 entries
vm0 logs <run-id> --head 50

# Show all entries
vm0 logs <run-id> --all

Filtering by Time

Use --since to filter logs by timestamp. Accepts relative durations, ISO 8601 timestamps, or Unix timestamps:

# Logs from the last 5 minutes
vm0 logs <run-id> --since 5m

# Logs from the last 2 hours
vm0 logs <run-id> --since 2h

# Logs since a specific time
vm0 logs <run-id> --since 2024-01-15T10:30:00Z

Searching Across Runs

Use vm0 logs search to find events across multiple runs without knowing specific run IDs. Results are grouped by run, with a header showing the run ID, agent name, and timestamp.

# Search for errors across all runs in the last 7 days (default)
vm0 logs search "error"

# Search with context lines before and after each match
vm0 logs search "OOM" -C 3

# Narrow results to a specific agent and time range
vm0 logs search "timeout" --agent my-agent --since 30d

# Search within a specific run
vm0 logs search "connection refused" --run 11007483-20b2-42b1-8f2a-b42a10186810

Search Options

Option	Description
`-A, --after-context <n>`	Show n events after each match (max 10)
`-B, --before-context <n>`	Show n events before each match (max 10)
`-C, --context <n>`	Show n events before and after each match (max 10)
`--agent <name>`	Filter by agent name
`--run <id>`	Filter by specific run ID
`--since <time>`	Search window (default: 7d)
`--limit <n>`	Maximum number of matches (default: 20, max 50)

When results are truncated, a hint is displayed. Use --limit to increase the number of matches returned.

On this page