交互式实例
交互式实例是长驻的 GPU 容器，启动后可在浏览器直接打开 Jupyter、网页终端，或（有公网 IP 时）通过 SSH 连接。这是平台的核心能力。
创建实例
在算力市场选好机器后创建。POST /rentals 主要字段：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
node_id | uuid | ✓ | 目标节点 |
launch_mode | string | interactive（交互式）或 batch，默认 batch | |
app | string | 交互式应用：jupyter / terminal / custom | |
template_image | string | Docker 镜像 | |
template_entrypoint | string | 覆盖启动命令 | |
gpu_count | int | 租用 GPU 卡数 | |
disk_gb | int | 实例磁盘（GB），默认 10，按整盘计存储费 | |
ports | array | 暴露端口，每项 { port, label, open_button, proto } | |
env | array | 环境变量，每项 { key, value } | |
registry | object | 私有仓库凭证 { server, username, token } | |
runtime | string | docker（默认）或 vm（实验性） | |
interruptible | bool | 竞价实例，需配 bid_price | |
bid_price | float | 竞价（元/时），须高于节点 min_bid_price |
curl -X POST "$ARK_API/rentals" \
-H "Authorization: Bearer $ARK_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"node_id": "NODE_ID",
"launch_mode": "interactive",
"app": "jupyter",
"template_image": "pytorch/pytorch:2.3.0-cuda12.1-cudnn8-runtime",
"gpu_count": 1,
"disk_gb": 40,
"env": [{ "key": "HF_TOKEN", "value": "hf_xxx" }],
"ports": [{ "port": 8888, "label": "jupyter", "open_button": true, "proto": "tcp" }]
}'创建返回 status: inactive，再调用 start 才下发并开始计费（控制台「创建」按钮已合并这两步）：
curl -X POST "$ARK_API/rentals/$RENTAL_ID/start" -H "Authorization: Bearer $ARK_TOKEN"余额需覆盖至少 1 小时运行费率，否则
402 INSUFFICIENT_BALANCE。其他可能错误：409 NO_FREE_GPU（卡已占满）、409 NODE_NOT_AVAILABLE（节点离线/独占）、409 NODE_DISK_INSUFFICIENT（磁盘不足）。
打开 Jupyter / 终端 / SSH
实例 instance_status 变为 running 后，控制台按钮变绿。GET /rentals/:id/access 返回访问入口：
curl -s "$ARK_API/rentals/$RENTAL_ID/access" -H "Authorization: Bearer $ARK_TOKEN" | jq{
"instance_status": "running",
"tunnel_hostname": "i-ab12cd34.inst.arkcore.cloud",
"access": {
"jupyter_url": "https://i-ab12cd34.inst.arkcore.cloud/lab",
"terminal_url": "https://i-ab12cd34-term.inst.arkcore.cloud/",
"open_button": "jupyter_url",
"ssh_cmd": "ssh -p 22001 root@203.0.113.5",
"ssh_host": "203.0.113.5",
"ssh_port": 22001
}
}| 入口 | 地址 | 说明 |
|---|---|---|
| Jupyter | jupyter_url | 浏览器直接打开，零安装（app=jupyter 时） |
| 网页终端 | terminal_url | 基于 ttyd 的浏览器 shell |
| SSH | ssh_cmd | 仅当节点有公网 IP；端口由 Nomad 动态分配 |
地址形如 https://i-<实例ID前8位>.inst.<域名>，经 Cloudflare 隧道暴露——节点无需公网 IP、无需开放入站端口。
公网 IP vs NAT 节点：有公网 IP 的节点提供直连 SSH（
ssh_cmd）；NAT 节点只走隧道，提供 Jupyter / 网页终端。需要 SSH 时在市场筛选public_ip非空的节点。
自定义端口
通过 ports 暴露的端口（如推理服务的 8000）也会经隧道映射，open_button: true 的端口会在控制台显示"打开"按钮。
查看日志与监控
# 实时日志（含调度/拉取镜像事件）
curl -s "$ARK_API/rentals/$RENTAL_ID/logs?offset=0" -H "Authorization: Bearer $ARK_TOKEN"
# 资源监控（默认最近 60 分钟，1–1440）
curl -s "$ARK_API/rentals/$RENTAL_ID/metrics?minutes=60" -H "Authorization: Bearer $ARK_TOKEN" | jq监控返回 cpu_pct、mem_used_mb、gpu_util、gpu_mem_used_mb、gpu_mem_total_mb 等采样点。
VM 实例（实验性）
runtime: "vm" 在支持的节点上启动 KVM 虚拟机，访问信息含 ssh_user（默认 ubuntu）与随机 ssh_password，可走隧道或直连 SSH。VM 暂不支持 GPU 直通的全部场景，详见节点的 vm_capable / vm_gpu_capable 标志。