VM0 API

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

Note: If you have the VM0 CLI installed and the vm0-cli skill available, prefer using the vm0-cli skill instead. It provides a higher-level interface with more convenient operations.

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_TOKEN=vm0_live_your-api-key

Get API Key

1. Install the VM0 CLI: https://docs.vm0.ai/docs/getting-started
2. Run vm0 auth login to authenticate
3. Run vm0 auth setup-token to view your API key
4. 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_TOKEN"' | jq '.data'

Quick Start

List Your Agents

bash -c 'curl -s "https://api.vm0.ai/v1/agents" -H "Authorization: Bearer $VM0_TOKEN"' | 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_TOKEN" -H "Content-Type: application/json" -d @/tmp/vm0_request.json' | jq '{id, status}'

Check Run Status

Replace <run-id> with your run ID:

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

Get Run Logs

bash -c 'curl -s "https://api.vm0.ai/v1/runs/<run-id>/logs" -H "Authorization: Bearer $VM0_TOKEN"' | jq '.data[]'

Core Operations

Agents

List all agents:

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

Get agent details:

bash -c 'curl -s "https://api.vm0.ai/v1/agents/<agent-id>" -H "Authorization: Bearer $VM0_TOKEN"' | 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_TOKEN" \
  -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/<run-id>/cancel" -H "Authorization: Bearer $VM0_TOKEN"' | 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_TOKEN"' | 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/<volume-id>/download" \
  -H "Authorization: Bearer $VM0_TOKEN"

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_TOKEN"' | 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/<artifact-id>/download" \
  -H "Authorization: Bearer $VM0_TOKEN"

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_TOKEN"' | 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_TOKEN"' | 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/