---

name: vm0 description: VM0 API for running AI agents in secure sandboxes. Use this skill to execute agents, manage runs, and download outputs (artifacts) and inputs (volumes) via the VM0 platform API. vm0_secrets:

• VM0_API_KEY

---

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

Copyexport VM0_API_KEY=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.

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

Quick Start

List Your Agents

Copybash -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:

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

Then run:

Copybash -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 <run-id> with your run ID:

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

Get Run Logs

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

Core Operations

Agents

List all agents:

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

Get agent details:

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

See references/agents.md for version listing.

Runs

Create a run with variables:

Copycurl -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:

Copybash -c 'curl -s -X POST "https://api.vm0.ai/v1/runs/<run-id>/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:

Copybash -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):

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

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

Artifacts (Output Storage)

List artifacts:

Copybash -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):

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

Extract downloaded archive:

Copytar -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:

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

Response includes:

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

Fetch next page:

Copybash -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:

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

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/