vm0

• 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

```bash

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

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

> ```

List Your Agents

```bash

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:

```json

{

"agent": "my-agent",

"prompt": "Hello, please introduce yourself"

}

```

Then run:

```bash

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

```bash

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

```

Get Run Logs

```bash

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

```

Agents

List all agents:

```bash

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

```

Get agent details:

```bash

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

```

See [references/agents.md](references/agents.md) for version listing.

Runs

Create a run with variables:

```bash

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

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

```

See [references/runs.md](references/runs.md) for events streaming, logs filtering, and metrics.

Volumes (Input Storage)

List volumes:

```bash

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

```bash

curl -L -o volume.tar.gz "https://api.vm0.ai/v1/volumes//download" \

-H "Authorization: Bearer $VM0_TOKEN"

```

See [references/volumes.md](references/volumes.md) for version listing and download options.

Artifacts (Output Storage)

List artifacts:

```bash

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

```bash

curl -L -o artifact.tar.gz "https://api.vm0.ai/v1/artifacts//download" \

-H "Authorization: Bearer $VM0_TOKEN"

```

Extract downloaded archive:

```bash

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

```

See [references/artifacts.md](references/artifacts.md) for version listing and download options.

Pagination

List endpoints support cursor-based pagination:

```bash

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

```

Response includes:

```json

{

"pagination": {

"has_more": true,

"next_cursor": "abc123"

}

}

```

Fetch next page:

```bash

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:

```json

{

"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 |

• [Agents API](references/agents.md) - List agents and versions
• [Runs API](references/runs.md) - Execute agents, stream events, get logs and metrics
• [Artifacts API](references/artifacts.md) - List and download agent outputs
• [Volumes API](references/volumes.md) - List and download input files

• Documentation: https://docs.vm0.ai/docs/reference/api
• Base URL: https://api.vm0.ai/v1/