Workspaces API

すべてのエンドポイントで Authorization: Bearer nt_… が必要で、共通エラー形式 を共有します。個別に記載のないステータス（401, 429, 500 等）も発生します。

ワークスペース作成

curl -X POST https://api.nanoterm.dev/api/workspaces \
  -H 'Authorization: Bearer nt_…' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "my-agent",
    "image": "ubuntu:22.04",
    "size": "small"
  }'

Body

Field	Type	必須	デフォルト	説明
name	string	no	自動生成	人間可読な名前
image	string	no	ubuntu:22.04	コンテナベースイメージ。GET /api/info で公開されている curated イメージ（またはサーバ側で設定された ALLOWED_IMAGE_PATTERNS のいずれか）に一致する必要があります。一致しない場合は 400 INVALID_IMAGE
size	enum	no	small	xs / small / medium / large
policyId	string	no	—	適用するポリシー ID
ports	{host?, container}[]	no	自動	ポートマッピング。host は省略可 — 省略すると container + 10000 帯から自動割当、指定すると固定。指定した host が既に使用中なら 409 PORT_IN_USE
repo.url	string	no	—	/workspace にクローンする Git リポジトリ。組織の GITHUB_TOKEN シークレットがあれば認証に利用
repo.branch	string	no	デフォルトブランチ	チェックアウトするブランチ

レスポンス

201 Created

{
  "id": "ws_a1b2c3d4",
  "name": "my-agent",
  "image": "ubuntu:22.04",
  "size": "small",
  "status": "running",
  "ports": [{ "host": 13000, "container": 3000 }],
  "createdAt": "2026-04-18T08:00:00.000Z"
}

400 VALIDATION_FAILED

{ "error": { "code": "VALIDATION_FAILED", "message": "size: invalid enum value" } }

400 INVALID_IMAGE

送信した image がサーバの allowlist に含まれていないとき返します。デフォルトの allowlist は GET /api/info の curated 一覧。サーバ運用者は ALLOWED_IMAGE_PATTERNS 環境変数（カンマ区切りの regex source）で拡張可能。このゲートが attacker.example/x:latest のような任意レジストリ pull を防ぎます — SSRF と supply-chain の両方の対策です。

{
  "error": {
    "code": "INVALID_IMAGE",
    "message": "Image 'attacker.example/x' is not allowed.",
    "action": "Use one of the curated images from GET /api/info...",
    "retryable": false
  }
}

409 PORT_IN_USE

明示的に指定した host ポートが他のアクティブなワークスペースで既に使用中のとき返します。別のポートにするか、host を省略してサーバに選ばせてください。

{ "error": { "code": "PORT_IN_USE", "message": "Host port 13000 is already in use by another workspace." } }

429 QUOTA_EXCEEDED

ワークスペース数上限（RPM の RATE_LIMITED とは別）。

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Workspace limit reached (10/10).",
    "action": "Terminate unused workspaces or upgrade your plan.",
    "retryable": false
  }
}

429 COMPUTE_QUOTA_EXCEEDED

プランの月間コンピュート時間を使い切ったとき。workspace.start / workspace.stop の監査ログから当月分を集計しています。

{
  "error": {
    "code": "COMPUTE_QUOTA_EXCEEDED",
    "message": "Monthly compute hours exhausted (50/50 h).",
    "action": "Wait for the cycle to reset on the 1st, or upgrade your plan.",
    "retryable": false
  }
}

503 RUNTIME_UNAVAILABLE

{
  "error": {
    "code": "RUNTIME_UNAVAILABLE",
    "message": "Container runtime not available.",
    "action": "Start Docker Desktop or `podman machine start`.",
    "retryable": true
  }
}

---

一覧

curl https://api.nanoterm.dev/api/workspaces \
  -H 'Authorization: Bearer nt_…'

200 OK

[
  {
    "id": "ws_a1b2c3d4",
    "name": "my-agent",
    "image": "ubuntu:22.04",
    "size": "small",
    "status": "running",
    "createdAt": "2026-04-18T08:00:00.000Z"
  }
]

---

取得

curl https://api.nanoterm.dev/api/workspaces/ws_a1b2c3d4 \
  -H 'Authorization: Bearer nt_…'

200 OK

単一の WorkspaceInfo（一覧と同形式）。

404 NOT_FOUND

存在しない場合 および 別組織所有の場合の両方で返します — テナント間で存在をリークしないためです。

{ "error": { "code": "NOT_FOUND", "message": "Workspace 'ws_a1b2c3d4' not found" } }

---

停止 / 再開

curl -X POST https://api.nanoterm.dev/api/workspaces/ws_a1b2c3d4/stop \
  -H 'Authorization: Bearer nt_…'

curl -X POST https://api.nanoterm.dev/api/workspaces/ws_a1b2c3d4/start \
  -H 'Authorization: Bearer nt_…'

停止はファイルシステムを保持し、再開はそこから復帰します。停止中は compute 課金が止まります。

200 OK

status が stopped / running に遷移した WorkspaceInfo を返します。

400 WORKSPACE_STOP_FAILED / WORKSPACE_START_FAILED

不正な状態遷移（例: running なワークスペースを start）。

---

終了

curl -X DELETE https://api.nanoterm.dev/api/workspaces/ws_a1b2c3d4 \
  -H 'Authorization: Bearer nt_…'

取り消し不可 — コンテナを削除し、行を removed にします。

200 OK

{ "ok": true }

---

スナップショット

実行中のコンテナをローカルイメージにコミットします。復元は 新しい ワークスペースをそのイメージから作成します（元は無傷）。Podman 限定 — Kubernetes ランタイムでは 501 NOT_SUPPORTED を返します。

スナップショット作成

curl -X POST https://api.nanoterm.dev/api/workspaces/ws_a1b2c3d4/snapshots \
  -H 'Authorization: Bearer nt_…' \
  -H 'Content-Type: application/json' \
  -d '{"name":"before-migration"}'

Body — name (string, optional)。省略時はタイムスタンプから自動生成。

201 Created

{
  "id": "sn_x1y2z3",
  "workspaceId": "ws_a1b2c3d4",
  "name": "before-migration",
  "imageRef": "nanoterm-snapshot:sn_x1y2z3",
  "sizeBytes": 44040192,
  "sourceImage": "ubuntu:22.04",
  "createdAt": "2026-04-18T08:01:23.000Z"
}

400 SNAPSHOT_CREATE_FAILED

ソースが running でない場合。

429 STORAGE_QUOTA_EXCEEDED

プランのスナップショット容量上限に達しています。見積は保守的にソースイメージサイズを使います。

{
  "error": {
    "code": "STORAGE_QUOTA_EXCEEDED",
    "message": "Storage quota exceeded (4.0 GB used + ~2.5 GB for this snapshot > 5 GB).",
    "action": "Delete old snapshots or upgrade your plan."
  }
}

501 NOT_SUPPORTED

Kubernetes ランタイム上で実行している場合。

一覧

curl https://api.nanoterm.dev/api/workspaces/ws_a1b2c3d4/snapshots \
  -H 'Authorization: Bearer nt_…'

200 OK

Snapshot の配列（新しい順）。

復元

curl -X POST https://api.nanoterm.dev/api/workspaces/ws_a1b2c3d4/snapshots/sn_x1y2z3/restore \
  -H 'Authorization: Bearer nt_…' \
  -H 'Content-Type: application/json' \
  -d '{"name":"restored-agent"}'

Body — name (string, optional)。省略時は <snapshotName>-restore。

201 Created

{ "workspaceId": "ws_newid01" }

429 QUOTA_EXCEEDED

復元はワークスペースのクォータを消費します。

削除

curl -X DELETE https://api.nanoterm.dev/api/workspaces/ws_a1b2c3d4/snapshots/sn_x1y2z3 \
  -H 'Authorization: Bearer nt_…'

行と、ローカルイメージの両方を削除します。

200 OK

{ "ok": true }