Container Lifecycle

Creating a container

When you call POST /api/v1/containers, hzel provisions an isolated container and automatically starts it. The state field progresses from "provisioning" → "running" as the container boots; if the transition can't be confirmed within the polling window, it is set to "failed". See ContainerRecord for the full field reference.

POSThttps://api.hzel.org/api/v1/containers

Header	Required	Description
`Authorization`	Required	`Bearer <token>`. Accepted auth methods: PAT, OAuth app token, JWT.
`Content-Type`	Required	Must be `application/json`.
`x-csrf-token`	Session auth only	Session-bound CSRF token. Required only when authenticating via session cookie. Automatically skipped for `Authorization: Bearer` requests.

Container states

State	Meaning
`provisioning`	Container is being created
`running`	Container is live
`stopped`	Container has been stopped
`failed`	A lifecycle action could not be confirmed

Runtime actions

Each lifecycle action returns the updated ContainerRecord. If the requested state transition cannot be confirmed within the timeout, state is set to "failed". Attempting an action on a container you don't own returns 403 Forbidden.

Start a container

POSThttps://api.hzel.org/api/v1/containers/{id}/start

Header	Required	Description
`Authorization`	Required	`Bearer <token>`. Accepted auth methods: PAT, OAuth app token, JWT.
`x-csrf-token`	Session auth only	Session-bound CSRF token. Required only when authenticating via session cookie.

Stop a container

POSThttps://api.hzel.org/api/v1/containers/{id}/stop

Header	Required	Description
`Authorization`	Required	`Bearer <token>`. Accepted auth methods: PAT, OAuth app token, JWT.
`x-csrf-token`	Session auth only	Session-bound CSRF token. Required only when authenticating via session cookie.

Restart a container

POSThttps://api.hzel.org/api/v1/containers/{id}/restart

Header	Required	Description
`Authorization`	Required	`Bearer <token>`. Accepted auth methods: PAT, OAuth app token, JWT.
`x-csrf-token`	Session auth only	Session-bound CSRF token. Required only when authenticating via session cookie.

Get container metrics

Returns a point-in-time snapshot of resource usage. See ContainerMetrics for the full field reference.

GEThttps://api.hzel.org/api/v1/containers/{id}/metrics

Header	Required	Description
`Authorization`	Required	`Bearer <token>`. Accepted auth methods: PAT, OAuth app token, JWT.

Running commands

The initial response has status: "queued". Poll GET /api/v1/commands/{id} to check progress, or connect to the job WebSocket endpoint to stream output in real time. See CommandExecutionRecord for the full field reference.

Submit a command

POSThttps://api.hzel.org/api/v1/containers/{id}/commands

Header	Required	Description
`Authorization`	Required	`Bearer <token>`. Accepted auth methods: PAT, OAuth app token, JWT.
`Content-Type`	Required	Must be `application/json`.
`x-csrf-token`	Session auth only	Session-bound CSRF token. Required only when authenticating via session cookie.

Poll command status

GEThttps://api.hzel.org/api/v1/commands/{id}

Header	Required	Description
`Authorization`	Required	`Bearer <token>`. Accepted auth methods: PAT, OAuth app token, JWT.

Terminal sessions

The dashboard provides a browser-based terminal connected to your container. You can also connect directly via the terminal WebSocket endpoint to build your own integrations. Each session is independent, and closing the connection ends the session cleanly.