快速开始

将下方命令中的 https://coderuntime.com 换成当前控制面 CONTROL_ORIGIN（受控环境示例： https://coderuntime.minr-c.com）。预览 URL 由响应中的 url / versionUrl 给出。

1. 准备静态站点目录

任意含 index.html 的目录即可。先打成 zip 供 curl 使用：

mkdir -p /tmp/cr-site && printf '%s\n' '<!doctype html><title>hi</title><h1>v1</h1>' > /tmp/cr-site/index.html
(cd /tmp/cr-site && zip -qr /tmp/site.zip .)

2. curl：首次匿名部署

curl --fail-with-body -sS -X POST "https://coderuntime.com/api/v1/deploy" \
  -H "Idempotency-Key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -F "archive=@/tmp/site.zip" \
  -F "intent=auto" \
  -o /tmp/deploy1.json
python3 -c 'import json; d=json.load(open("/tmp/deploy1.json")); print(d["url"]); print(d["projectId"]); print(d.get("guestToken","")[:16]+"...")'

首次成功会在 JSON 中返回一次 guestToken（以 cr_guest_ 开头）。请立即保存；响应里不会在 URL 或二维码中出现 Token。CLI 会自动写入本地配置，见下文。

# 保存 Guest Token（示例：写入仅本人可读的文件）
python3 -c 'import json; print(json.load(open("/tmp/deploy1.json"))["guestToken"])' > /tmp/guest.token
chmod 600 /tmp/guest.token
export GUEST_TOKEN="$(cat /tmp/guest.token)"
export PROJECT_ID="$(python3 -c 'import json; print(json.load(open("/tmp/deploy1.json"))["projectId"])')"

3. curl：同一项目再次部署

修改站点后重新打包，用同一 Guest Token 与 projectId 更新：

printf '%s\n' '<!doctype html><title>hi</title><h1>v2</h1>' > /tmp/cr-site/index.html
(cd /tmp/cr-site && zip -qr /tmp/site.zip .)
curl --fail-with-body -sS -X POST "https://coderuntime.com/api/v1/deploy" \
  -H "Authorization: Bearer $GUEST_TOKEN" \
  -H "Idempotency-Key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -F "archive=@/tmp/site.zip" \
  -F "intent=auto" \
  -F "projectId=$PROJECT_ID" \
  -o /tmp/deploy2.json
python3 -c 'import json; d=json.load(open("/tmp/deploy2.json")); print(d["url"], d["deployment"]["version"])'

稳定预览 URL（url）不变；版本号递增。失败部署不会把 current 挪到坏版本。

4. CLI：安装、首次与再次部署

# 当前阶段直接使用源码构建 CLI，不发布 npm 包
cd /path/to/codeRuntime
pnpm install --frozen-lockfile
pnpm --filter @coderuntime/cli --fail-if-no-match build
export XDG_CONFIG_HOME=/tmp/codert-ac39-config
rm -rf "$XDG_CONFIG_HOME"

# 首次部署
node apps/cli/dist/index.js deploy /tmp/cr-site --origin https://coderuntime.com

# 修改文件后再次执行；CLI 自动读取已保存的 Guest Token 与 projectId
node apps/cli/dist/index.js deploy /tmp/cr-site --origin https://coderuntime.com

Guest Token 写入 $XDG_CONFIG_HOME/codert/config.json（未设置该变量时使用 ~/.config/codert/config.json，权限 0600）。CLI 成功摘要从不打印 Token 明文。

5. 额度、错误与认领（必读）

额度：匿名 Guest 默认 1 个项目、24h 部署次数与版本保留有限；超限返回 429 与 problem+json，并提示认领。
错误：API 使用 application/problem+json 与稳定错误码（如 RATE_LIMITED、WORKSPACE_PROJECT_QUOTA_EXCEEDED、CONTENT_SUSPENDED）。不要依赖英文 message 做分支。
认领：在原设备保留 Guest 凭据，用 CLI claim 或官网流程绑定邮箱；Token 丢失不提供人工绕过。
安全：预览默认公开；上传的 HTML/JS 不可信；不要把 Guest Token 贴进聊天、截图或仓库；滥用可导致 403 CONTENT_SUSPENDED / 451 CONTENT_LEGALLY_UNAVAILABLE。

CLI 详解 · HTTP API · 服务条款 · 可接受使用