Skip to content
Hoody Documentation
Hoody.com
Download Page (.md)

Overview

Section titled “Overview”

The Containers API lets you enumerate, inspect, create, modify, and delete your containers. You can also fetch live resource statistics and issue a signed, portable container authorization claim for offline verification by container programs.

Use these endpoints when you need to:

  • Discover containers across all projects or within a single project.
  • Read a container’s configuration, runtime state, and proxy permissions.
  • Provision a new container on a chosen server inside a project.
  • Update mutable container fields such as name, color, autostart, ramdisk settings, environment variables, SSH key, comment, and realm membership.
  • Tear down a container when it is no longer needed.
  • Mint a short-lived signed claim (container_claim) that proves authorization for a specific container without an extra API round-trip.

List and Inspect Containers

Section titled “List and Inspect Containers”

GET /api/v1/containers/

Section titled “GET /api/v1/containers/”

Returns every container accessible to the current user across all projects, with pagination, filtering, sorting, and opt-in live runtime information.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
pagequerynumberNoPage number for pagination — starts from 1. Default: 1
limitquerynumberNoNumber of containers per page — maximum 100. Default: 50
sort_byquerystringNoField to sort by. Allowed values: id, name, status, created_at, updated_at. Default: "created_at"
sort_orderquerystringNoSort direction. Allowed values: asc, desc. Default: "desc"
realm_idquerystringNoFilter by realm ID. Only returns containers that belong to this realm. Alternative to using a realm subdomain in the URL.
runtimequerystringNoInclude live runtime information. Accepts true, false, or a URL-encoded JSON string like {"displays":true}. An empty JSON object {} fetches all info. Results are cached for 2 seconds to prevent abuse.
include_proxy_domainsquerystringNoInclude proxy domains (aliases) for each container. Allowed values: true, false.
include_proxy_permissionsquerystringNoInclude the full proxy-permissions documents for each container. Allowed values: true, false. Returns authentication group configuration including credentials — request only when explicitly needed. Auth tokens additionally require the resources.proxy_aliases permission.
include_prespawnquerystringNoInclude prespawn containers in the listing. By default, prespawn containers are excluded. Allowed values: true, false.
include_expiredquerystringNoInclude containers that have expired due to server termination. By default, expired containers are excluded. Allowed values: true, false.
include_deletingquerystringNoInclude containers currently being deleted. By default, deleting containers are excluded. Allowed values: true, false.
Terminal window
curl -X GET "https://api.hoody.icu/api/v1/containers/?page=1&limit=20&sort_by=created_at&sort_order=desc" \
  -H "Authorization: Bearer <token>"

GET /api/v1/containers/{id}

Section titled “GET /api/v1/containers/{id}”

Returns a single container by ID, including warnings (such as expiration notices), optional runtime information, and optional proxy documents.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesUnique identifier of the container to retrieve
runtimequerystringNoInclude live runtime information. Accepts true, false, or a URL-encoded JSON string like {"displays":true}. An empty JSON object {} fetches all info. Results are cached for 2 seconds to prevent abuse.
include_proxy_domainsquerystringNoInclude proxy domains (aliases) for this container. Allowed values: true, false.
include_proxy_permissionsquerystringNoInclude the full proxy-permissions documents for this container. Allowed values: true, false. Auth tokens additionally require the resources.proxy_aliases permission.
Terminal window
curl -X GET "https://api.hoody.icu/api/v1/containers/507f1f77bcf86cd799439011?runtime=true" \
  -H "Authorization: Bearer <token>"

GET /api/v1/projects/{id}/containers

Section titled “GET /api/v1/projects/{id}/containers”

Returns all containers belonging to a single project, with the same pagination, filtering, and opt-in runtime controls as the global listing.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesProject ID (24-char hex)
pagequerynumberNoPage number for pagination — starts from 1
limitquerynumberNoNumber of containers per page. Default: 50
sort_byquerystringNoField to sort by. Allowed values: id, name, status, created_at, updated_at
sort_orderquerystringNoSort direction. Allowed values: asc, desc
runtimequerystringNoInclude live runtime information. Accepts true, false, or a URL-encoded JSON string like {"displays":true}. An empty JSON object {} fetches all info. Results are cached for 2 seconds.
include_proxy_domainsquerystringNoInclude proxy domains (aliases) for each container. Allowed values: true, false.
include_proxy_permissionsquerystringNoInclude the full proxy-permissions documents for each container. Allowed values: true, false. Auth tokens additionally require the resources.proxy_aliases permission.
include_prespawnquerystringNoInclude prespawn containers in the listing. By default, prespawn containers are excluded. Allowed values: true, false.
include_deletingquerystringNoInclude containers currently being deleted. By default, deleting containers are excluded. Allowed values: true, false.
Terminal window
curl -X GET "https://api.hoody.icu/api/v1/projects/507f1f77bcf86cd799439011/containers?page=1&limit=20" \
  -H "Authorization: Bearer <token>"

GET /api/v1/containers/{id}/stats

Section titled “GET /api/v1/containers/{id}/stats”

Returns real-time resource usage statistics for a container — CPU, memory, ramdisk, disk, and network interface counters. Useful for monitoring and troubleshooting.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesUnique identifier of the container
Terminal window
curl -X GET "https://api.hoody.icu/api/v1/containers/507f1f77bcf86cd799439011/stats" \
  -H "Authorization: Bearer <token>"

Authorize

Section titled “Authorize”

POST /api/v1/containers/{id}/authorize

Section titled “POST /api/v1/containers/{id}/authorize”

Issues a signed, portable container authorization claim. The returned container_claim is an ED25519-signed credential that proves:

  • Who the user is (sub, type)
  • Which container they are authorized for (containerId, projectId)
  • When Hoody issued the authorization (iat, exp)

Container programs can verify this claim offline using Hoody’s public key at GET /api/v1/meta/public-key — no API round-trip needed during verification.

Claims expire after HOODY_CONTAINER_CLAIM_EXPIRES_IN (default 6 hours). Clients should re-call this endpoint to refresh before expiry.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesContainer ID (24-char hex)
Terminal window
curl -X POST "https://api.hoody.icu/api/v1/containers/abc123def456abc123def456/authorize" \
  -H "Authorization: Bearer <token>"

Create, Update, and Delete

Section titled “Create, Update, and Delete”

POST /api/v1/projects/{id}/containers

Section titled “POST /api/v1/projects/{id}/containers”

Provisions a new container inside a project on a chosen server.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesProject ID (24-char hex)

Request Body

Section titled “Request Body”
FieldTypeRequiredDefaultDescription
server_idstringYes—Target server ID (24-char hex)
namestringNo—Container name — 3-100 characters, alphanumeric with hyphens and underscores. Omit or pass "rand" to generate a random name.
colorstringNo—HEX color for the container (e.g. #FF0000 or FF0000). The # prefix is added if missing; the value is converted to uppercase.
container_imagestringNo—Container image to use. If null or omitted, the default configured image is used.
aibooleanNotrueWhether AI features are enabled.
environment_varsobjectNo—Environment variables as key-value pairs (max 200 keys, each value ≤ 65536 chars; keys must match ^[a-zA-Z_][a-zA-Z0-9_]*$).
ssh_public_keystringNo—SSH public key for container access. SSH public keys must be unique per container. If omitted, the container inherits from the project’s defaults.
commentstringNo—Optional comment (max 16000 characters).
hoody_kitbooleanNotrueEnable all Hoody Kit features (extra apt sources, base packages, hoody-daemon, sudo env, remove snapd, webview, user, hoody-ai, ttyd).
dev_kitbooleanNo—Enable dev_kit development tools. Defaults to true when hoody_kit is true, otherwise false. Cannot be updated after creation.
autostartbooleanNotrueWhether the container should start automatically on host boot.
ramdiskbooleanNotrueWhether to mount a ramdisk at /ramdisk. Data persists across container restarts but is lost on a host reboot.
cachebooleanNotrueEnable use of cached images during creation. When false, no cache options are added.
cache_imagebooleanNofalseForce the creation of a new cached image from the container image. Admins and the image owner only.
prespawnbooleanNofalseInternal — not user-settable. Passing true is rejected (403); an explicit false is accepted.
bypass_prespawnbooleanNofalseBypass prespawn container claiming and create a fresh container directly.
realm_idsarrayNo—Realm IDs to assign this container to. If creating from a realm subdomain, the subdomain realm is automatically merged with any explicit values. Containers may have different realm membership than their parent project.
Terminal window
curl -X POST "https://api.hoody.icu/api/v1/projects/507f1f77bcf86cd799439011/containers" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "507f1f77bcf86cd799439014",
    "name": "backend-api",
    "color": "#10B981",
    "container_image": "ubuntu/22.04",
    "ai": true,
    "environment_vars": {
      "DATABASE_URL": "postgresql://user:pass@db:5432/app",
      "REDIS_URL": "redis://cache:6379"
    },
    "ssh_public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl user@host",
    "comment": "Backend API server with PostgreSQL connection",
    "autostart": true,
    "ramdisk": true
  }'

PUT /api/v1/containers/{id}

Section titled “PUT /api/v1/containers/{id}”

Updates mutable fields on an existing container. Omitted fields are preserved. Use null for ssh_public_key or comment to clear the value or fall back to project defaults.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesUnique identifier of the container to update

Request Body

Section titled “Request Body”
FieldTypeRequiredDescription
namestringNoHuman-readable name — must be unique within the project.
colorstringNoHEX color (e.g. #FF0000 or FF0000). The # prefix is added if missing; the value is converted to uppercase.
aibooleanNoWhether AI features are enabled. Preserved if omitted.
autostartbooleanNoWhether the container starts automatically on host boot. Preserved if omitted.
ramdisk_scopestringNoSharing scope for /ramdisk. Allowed values: container, project. project is refused when the project has other members.
ramdiskbooleanNoWhether to mount a ramdisk at /ramdisk. Preserved if omitted.
environment_varsobjectNoEnvironment variables as key-value pairs (max 200 keys, each value ≤ 65536 chars).
ssh_public_keystring or nullNoSSH public key for container access. Re-sending the same key for the same container is a no-op. Set to null to clear or inherit from project defaults.
commentstring or nullNoOptional comment (max 16000 characters). Set to null to clear.
realm_idsarrayNoUpdate realm membership. Only unrestricted tokens and admin users can modify realm_ids.
Terminal window
curl -X PUT "https://api.hoody.icu/api/v1/containers/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-app-1-renamed",
    "color": "#FF8800",
    "autostart": true,
    "ramdisk_scope": "container",
    "comment": "Renamed after launch"
  }'

DELETE /api/v1/containers/{id}

Section titled “DELETE /api/v1/containers/{id}”

Deletes a container. The container must be in a state that permits deletion.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesUnique identifier of the container to delete
Terminal window
curl -X DELETE "https://api.hoody.icu/api/v1/containers/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer <token>"