vm0

VM0 API

Execute AI agents in secure sandboxed environments and manage their inputs/outputs.

When to Use Execute AI agents in isolated sandbox environments Monitor and manage agent runs (status, logs, metrics) List and download input files (volumes) provided to agents List and download output files (artifacts) created by agents Prerequisites export VM0_API_KEY=vm0_live_your-api-key

Get API Key Install the VM0 CLI: https://docs.vm0.ai/docs/getting-started Run vm0 auth login to authenticate Run vm0 auth setup-token to view your API key Copy the token starting with vm0_live_

Important: When using $VAR in a command that pipes to another command, wrap only the curl command in bash -c '...', then pipe to jq outside. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.

bash -c 'curl -s "https://api.vm0.ai/v1/agents" -H "Authorization: Bearer $VM0_API_KEY"' | jq '.data'

Quick Start List Your Agents bash -c 'curl -s "https://api.vm0.ai/v1/agents" -H "Authorization: Bearer $VM0_API_KEY"' | jq '.data[] | {id, name}'

Run an Agent

Write to /tmp/vm0_request.json:

{ "agent": "my-agent", "prompt": "Hello, please introduce yourself" }

Then run:

bash -c 'curl -s -X POST "https://api.vm0.ai/v1/runs" -H "Authorization: Bearer $VM0_API_KEY" -H "Content-Type: application/json" -d @/tmp/vm0_request.json' | jq '{id, status}'

Check Run Status

Replace with your run ID:

bash -c 'curl -s "https://api.vm0.ai/v1/runs/" -H "Authorization: Bearer $VM0_API_KEY"' | jq '{id, status, error, execution_time_ms}'

Get Run Logs bash -c 'curl -s "https://api.vm0.ai/v1/runs//logs" -H "Authorization: Bearer $VM0_API_KEY"' | jq '.data[]'

Core Operations Agents

List all agents:

bash -c 'curl -s "https://api.vm0.ai/v1/agents" -H "Authorization: Bearer $VM0_API_KEY"' | jq '.data'

Get agent details:

bash -c 'curl -s "https://api.vm0.ai/v1/agents/" -H "Authorization: Bearer $VM0_API_KEY"' | jq '{id, name, description}'

See references/agents.md for version listing.

Runs

Create a run with variables:

curl -s -X POST "https://api.vm0.ai/v1/runs" \ -H "Authorization: Bearer $VM0_API_KEY" \ -H "Content-Type: application/json" \ -d @- << 'EOF' { "agent": "my-agent", "prompt": "Process the data file", "variables": { "DEBUG": "true" }, "volumes": { "input-data": "latest" } } EOF

Cancel a running execution:

bash -c 'curl -s -X POST "https://api.vm0.ai/v1/runs//cancel" -H "Authorization: Bearer $VM0_API_KEY"' | jq '{id, status}'

See references/runs.md for events streaming, logs filtering, and metrics.

Volumes (Input Storage)

List volumes:

bash -c 'curl -s "https://api.vm0.ai/v1/volumes" -H "Authorization: Bearer $VM0_API_KEY"' | jq '.data[] | {id, name}'

Download volume as tar.gz archive (follows 302 redirect):

curl -L -o volume.tar.gz "https://api.vm0.ai/v1/volumes//download" \ -H "Authorization: Bearer $VM0_API_KEY"

See references/volumes.md for version listing and download options.

Artifacts (Output Storage)

List artifacts:

bash -c 'curl -s "https://api.vm0.ai/v1/artifacts" -H "Authorization: Bearer $VM0_API_KEY"' | jq '.data[] | {id, name}'

Download artifact as tar.gz archive (follows 302 redirect):

curl -L -o artifact.tar.gz "https://api.vm0.ai/v1/artifacts//download" \ -H "Authorization: Bearer $VM0_API_KEY"

Extract downloaded archive:

tar -xzf artifact.tar.gz -C ./output/

See references/artifacts.md for version listing and download options.

Common Patterns Pagination

List endpoints support cursor-based pagination:

bash -c 'curl -s "https://api.vm0.ai/v1/runs?limit=10" -H "Authorization: Bearer $VM0_API_KEY"' | jq '{data, pagination}'

Response includes:

{ "pagination": { "has_more": true, "next_cursor": "abc123" } }

Fetch next page:

bash -c 'curl -s "https://api.vm0.ai/v1/runs?limit=10&cursor=abc123" -H "Authorization: Bearer $VM0_API_KEY"' | jq '{data, pagination}'

Error Handling

All errors return a consistent format:

{ "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "No such agent: 'my-agent'", "param": "agent" } }

Error Type Status Description authentication_error 401 Invalid or missing API key invalid_request_error 400 Invalid parameters not_found_error 404 Resource doesn't exist api_error 500 Internal server error Detailed References Agents API - List agents and versions Runs API - Execute agents, stream events, get logs and metrics Artifacts API - List and download agent outputs Volumes API - List and download input files API Reference Documentation: https://docs.vm0.ai/docs/reference/api Base URL: https://api.vm0.ai/v1/