vm0

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

在安全的沙箱环境中执行AI Agent，并管理其输入/输出。

注意： 如果你已安装VM0 CLI且拥有vm0-cli技能，建议优先使用vm0-cli技能。它提供了更高级的接口和更便捷的操作。

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

在隔离的沙箱环境中执行AI Agent
监控和管理Agent运行任务（状态、日志、指标）
列出并下载提供给Agent的输入文件（volumes）
列出并下载Agent生成的输出文件（artifacts）

Prerequisites

前置条件

bash

export VM0_TOKEN=vm0_live_your-api-key

bash

export VM0_TOKEN=vm0_live_your-api-key

Get API Key

获取API密钥

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

安装VM0 CLI：https://docs.vm0.ai/docs/getting-started
运行
```
vm0 auth login
```
进行身份验证
运行
```
vm0 auth setup-token
```
查看你的API密钥
复制以
```
vm0_live_
```
开头的令牌

重要提示： 在使用包含
$VAR
的命令并通过管道符连接到其他命令时，请仅将curl命令包裹在
bash -c '...'
中，然后在外部通过管道符连接到jq。由于Claude Code的bug，直接使用管道符时环境变量会被静默清除。
bash
bash -c 'curl -s "https://api.vm0.ai/v1/agents" -H "Authorization: Bearer $VM0_TOKEN"' | jq '.data'

Quick Start

快速开始

List Your Agents

列出你的Agent

bash

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

bash

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

Run an Agent

运行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}'

写入文件

/tmp/vm0_request.json

：

json

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

然后运行：

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

<run-id>

with your run ID:

bash

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

将

<run-id>

替换为你的运行任务ID：

bash

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

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

bash

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

Core Operations

核心操作

Agents

Agent管理

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/<agent-id>" -H "Authorization: Bearer $VM0_TOKEN"' | jq '{id, name, description}'

See references/agents.md for version listing.

列出所有Agent：

bash

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

获取Agent详情：

bash

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

查看版本列表请参考references/agents.md。

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/<run-id>/cancel" -H "Authorization: Bearer $VM0_TOKEN"' | jq '{id, status}'

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

创建包含变量的运行任务：

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

取消正在运行的任务：

bash

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

事件流、日志过滤和指标相关内容请参考references/runs.md。

Volumes (Input Storage)

Volumes（输入存储）

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

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

列出Volumes：

bash

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

将Volume下载为tar.gz压缩包（遵循302重定向）：

bash

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

版本列表和下载选项请参考references/volumes.md。

Artifacts (Output Storage)

Artifacts（输出存储）

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

Extract downloaded archive:

bash

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

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

列出Artifacts：

bash

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

将Artifact下载为tar.gz压缩包（遵循302重定向）：

bash

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

解压下载的压缩包：

bash

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

版本列表和下载选项请参考references/artifacts.md。

Common Patterns

常见模式

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}'

列表接口支持基于游标（cursor）的分页：

bash

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

响应包含：

json

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

获取下一页：

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

所有错误返回统一格式：

json

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

错误类型	状态码	描述
`authentication_error`	401	API密钥无效或缺失
`invalid_request_error`	400	参数无效
`not_found_error`	404	资源不存在
`api_error`	500	服务器内部错误

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

Agents API - 列出Agent及版本
Runs API - 执行Agent、事件流、获取日志和指标
Artifacts API - 列出并下载Agent输出
Volumes API - 列出并下载输入文件

API Reference

API参考

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

文档：https://docs.vm0.ai/docs/reference/api
基础URL：
```
https://api.vm0.ai/v1/
```