Commands

Commands are asynchronous shell jobs dispatched to a container. Submit a command, receive a job ID, then poll or stream the result.

---

POST /api/v1/containers/{container_id}/commands

Enqueue a new shell command on a running container.

Header	Value	Required
Authorization	Bearer <token>	Yes
Content-Type	application/json	Yes
x-csrf-token	<csrf_token>	Yes, for session auth only

Request Body

Field	Type	Required	Description
command	string	Yes	Shell command to execute

Success 200

{
  "data": {
    "id": "01942cf7-…",
    "container_id": "01942cf6-…",
    "command": "echo hello",
    "status": "queued",
    "exit_code": null,
    "created_at": "2026-03-28T00:00:00Z"
  }
}

Errors

Status	error.code	Reason
400	BAD_REQUEST	Missing command field
401	UNAUTHORIZED	Missing or invalid auth
403	CSRF_REJECTED	Session auth missing x-csrf-token
404	NOT_FOUND	Container not found

---

GET /api/v1/commands/{job_id}

Fetch the current state and result of a command job.

Header	Value	Required
Authorization	Bearer <token>	Yes

Success 200

{
  "data": {
    "id": "01942cf7-…",
    "container_id": "01942cf6-…",
    "command": "echo hello",
    "status": "completed",
    "exit_code": 0,
    "created_at": "2026-03-28T00:00:00Z"
  }
}

status values: "queued" | "running" | "completed" | "failed"

Errors

Status	error.code	Reason
401	UNAUTHORIZED	Missing or invalid auth
404	NOT_FOUND	Job ID not found

---

Real-time streaming

Connect over WebSocket to stream stdout/stderr as the command runs:

wss://api.hzel.org/ws/jobs/{job_id}?token=<bearer_token>

The token is passed as a query parameter because browsers cannot set Authorization headers on WebSocket connections.