The Containers API lets you list, inspect, create, update, authorize, and delete container resources owned by the authenticated user. Use these endpoints when you need a global view of all containers across every project, a scoped view of one project’s containers, or to manage a specific container’s configuration, lifecycle, or signed authorization claims.
Container records expose configuration (image, AI/Kit flags, ramdisk scope, autostart, SSH key, environment variables, comment, realm membership), current runtime state (status, lifecycle, optionally live runtime information), and proxy metadata (custom domain aliases and per-scope proxy-permissions documents).
Get all containers across all projects for the current user with pagination, filtering, and sorting. This endpoint provides a global view of all containers without being scoped to a specific project.
Page number for pagination - starts from 1. Default: 1
limit
query
number
No
Number of containers to return per page - maximum 100 items. Default: 50
sort_by
query
string
No
Field to sort containers by. Default: "created_at". Allowed: id, name, status, created_at, updated_at
sort_order
query
string
No
Sort direction - ascending or descending. Default: "desc". Allowed: asc, desc
realm_id
query
string
No
Filter by realm ID. Only returns containers that belong to this realm. Alternative to using realm subdomain in URL.
runtime
query
string
No
Include 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_domains
query
string
No
Include proxy domains (aliases) for each container. When true, adds a proxy_domains array to each container object. Allowed: true, false
include_proxy_permissions
query
string
No
Include the full proxy-permissions documents (container-level proxy_permissions and parent-project-level project_proxy_permissions) for each container. Returns proxy authentication group configuration including credentials — request only when explicitly needed. Auth tokens additionally require the resources.proxy_aliases permission. Allowed: true, false
include_prespawn
query
string
No
Include prespawn containers in the listing. By default, prespawn containers are excluded from results. Allowed: true, false
include_expired
query
string
No
Include containers that have expired due to server termination. By default, expired containers are excluded from results. Allowed: true, false
include_deleting
query
string
No
Include containers currently being deleted. By default, deleting containers are excluded from results. Allowed: true, false
Include 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_domains
query
string
No
Include proxy domains (aliases) for this container. When true, adds a proxy_domains array to the container object. Allowed: true, false
include_proxy_permissions
query
string
No
Include the full proxy-permissions documents (container-level proxy_permissions and parent-project-level project_proxy_permissions) for each container. Returns proxy authentication group configuration including credentials — request only when explicitly needed. Auth tokens additionally require the resources.proxy_aliases permission. Allowed: true, false
Get real-time resource usage statistics for a container including CPU, memory, disk, and network metrics. Useful for monitoring performance and troubleshooting resource issues.
Number of containers to return per page. Default: 50
sort_by
query
string
No
Field to sort containers by. Allowed: id, name, status, created_at, updated_at
sort_order
query
string
No
Sort direction - ascending or descending. Allowed: asc, desc
runtime
query
string
No
Include 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_domains
query
string
No
Include proxy domains (aliases) for each container. When true, adds a proxy_domains array to each container object. Allowed: true, false
include_proxy_permissions
query
string
No
Include the full proxy-permissions documents (container-level proxy_permissions and parent-project-level project_proxy_permissions) for each container. Returns proxy authentication group configuration including credentials — request only when explicitly needed. Auth tokens additionally require the resources.proxy_aliases permission. Allowed: true, false
include_prespawn
query
string
No
Include prespawn containers in the listing. By default, prespawn containers are excluded. Allowed: true, false
include_deleting
query
string
No
Include containers currently being deleted. By default, deleting containers are excluded from results. Allowed: true, false
Create a new container for a project. The server_id field is required. Container creation is asynchronous; the returned status typically reads creating (or claiming when the system first tries to claim a prespawn cache). Image shorthand is auto-resolved: a bare distribution name or hyphenated version (such as debian or debian-13) becomes the canonical debian/13 form, as do the debian:13 and debian 13 forms.
Name for the container. Must be 3-100 characters, alphanumeric with hyphens and underscores. Omit or use "rand" to generate a random name.
color
string
No
HEX color for the container (e.g., FF0000 or #FF0000). The # prefix is added automatically if missing and the color is converted to uppercase.
container_image
string
No
Container image to use. If null or not provided, the default configured image is used. Shorthand is resolved automatically: a bare distribution name or hyphenated version (debian, debian-13) becomes the canonical base image (debian/13), as do the debian:13 and debian 13 forms.
ai
boolean
No
Whether AI features are enabled. Default: true
environment_vars
object
No
Environment variables to set in the container as key-value pairs (string values, max 65536 chars each, max 200 properties, names match ^[a-zA-Z_][a-zA-Z0-9_]*$).
ssh_public_key
string
No
SSH public key for container access. SSH public keys must be unique per container (one container per key). If not provided, will inherit from project defaults.
comment
string
No
Optional comment for the container (max 16000 characters).
hoody_kit
boolean
No
Enable all Hoody Kit features (extra-apt-sources, basic-packages, hoody-daemon, sudo-env, remove-snapd, webview, user, hoody-ai, ttyd). Default: true
dev_kit
boolean
No
Enable dev_kit development tools in the container. Defaults to true when hoody_kit is true, false when hoody_kit is false (unless explicitly set). Cannot be updated after creation.
kvm
boolean
No
Enable /dev/kvm passthrough (run full VMs inside the container) at creation. Available on rented / dedicated (bare-metal) servers ONLY — never free tier — and rejected (403) on a free server. Defaults to false.
dev_kvm
boolean
No
Accepted alias of kvm on input (kvm wins if both are sent and they must agree).
autostart
boolean
No
Whether the container should start automatically on host boot. Default: true
ramdisk
boolean
No
Whether to mount a ramdisk at /ramdisk in the container. The ramdisk KEEPS data when you stop/start/reboot the container, but LOSES data if the physical host server reboots. Default: true
cache
boolean
No
Enable use of cached images during container creation. Default: true
cache_image
boolean
No
Force the creation of a new cached image from the container image. This option is only available to admins or the owner of the image. Default: false
prespawn
boolean
No
INTERNAL — not user-settable. Prespawn cache containers are provisioned only by the system pool producer. Passing true is rejected (403); an explicit false is accepted. Default: false
bypass_prespawn
boolean
No
Bypass prespawn container claiming and create a fresh container directly. Default: false
realm_ids
array
No
Realm IDs to assign this container to. Containers can have different realm membership than their parent project.
"comment":"Backend API server with PostgreSQL connection",
"realm_ids":[],
"created_at":"2025-01-15T15:45:00.000Z",
"updated_at":"2025-01-15T15:45:00.000Z"
}
}
{
"statusCode":400,
"error":"Bad Request",
"message":"Validation failed"
}
Error Code
Title
Description
Resolution
VALIDATION_ERROR
Invalid input parameters
One or more request parameters failed validation
Check the error message for specific field requirements and correct your input
INVALID_ID_FORMAT
Invalid ID format
The provided ID must be a 24-character hexadecimal string
Ensure the ID is exactly 24 characters long and contains only hexadecimal characters (0-9, a-f)
INVALID_CONTAINER_NAME
Invalid container name
Container name must be 3-100 characters, alphanumeric with hyphens and underscores.
Use a valid name between 3 and 100 characters containing only a-z, A-Z, 0-9, -, and _.
SERVER_CONTAINER_LIMIT
Server container limit reached
The target server is at its maximum number of live containers (explicit max_containers, or the free-tier default).
Delete an existing container on this server, or create the container on a different server.
PROJECT_CONTAINER_LIMIT
Project container limit reached
The target project is at its owner-configured container quota (projects.max_containers). Prespawn containers are excluded from this quota.
Delete an existing container in this project, raise the project quota, or use a different project.
{
"statusCode":401,
"error":"Unauthorized",
"message":"Authentication token required"
}
Error Code
Title
Description
Resolution
MISSING_TOKEN
Authentication token missing
No authentication token was provided in the request
Include a valid JWT token in the Authorization header as “Bearer <token>“
INVALID_TOKEN
Invalid authentication token
The provided authentication token is malformed or invalid
Obtain a new token by logging in again or using a valid auth token
TOKEN_EXPIRED
Authentication token expired
The provided authentication token has expired
Obtain a new token by logging in again or refreshing your session
{
"statusCode":403,
"error":"Forbidden",
"message":"Insufficient permissions"
}
Error Code
Title
Description
Resolution
INSUFFICIENT_PERMISSIONS
Insufficient permissions
You do not have the required permissions to perform this action
Contact the resource owner or administrator to request access
ACCOUNT_BANNED
Account banned
Your account has been banned and cannot access this resource
Contact support for information about your account status
{
"statusCode":404,
"error":"Not Found",
"message":"Resource not found"
}
Error Code
Title
Description
Resolution
RESOURCE_NOT_FOUND
Resource not found
The requested resource does not exist or has been deleted
Verify the resource ID and ensure it exists
{
"statusCode":409,
"error":"Conflict",
"message":"Container name already in use within the project"
}
Error Code
Title
Description
Resolution
CONTAINER_NAME_IN_USE
Container name already in use
A container with this name already exists in the project.
Choose a different name for your container.
SSH_PUBLIC_KEY_IN_USE
SSH public key already in use
SSH public keys must be unique per container. A single public key cannot be assigned to multiple containers because it is used for routing SSH connections.
Generate a new SSH key pair for this container, or remove the key from the other container before reusing it.
{
"statusCode":422,
"error":"Unprocessable Entity",
"message":"Quota exceeded"
}
Error Code
Title
Description
Resolution
QUOTA_EXCEEDED
Quota exceeded
You have exceeded your quota for this resource type
Delete unused resources or upgrade your plan for higher limits
Update a container. Fields omitted from the body are preserved. Set comment or ssh_public_key to null to clear them and inherit from project defaults. Modifying realm_ids requires an unrestricted token or admin user; realm-restricted tokens cannot change realm membership.
Human-readable name for the container - must be unique within the project
color
string
No
HEX color for the container (e.g., FF0000 or #FF0000). The # prefix is added automatically if missing and the color is converted to uppercase.
ai
boolean
No
Whether AI features are enabled. If omitted, the current value is preserved.
autostart
boolean
No
Whether the container starts automatically on host boot. If omitted, the current value is preserved.
ramdisk_scope
string
No
Sharing scope for /ramdisk. container (default) mounts only private storage. project additionally mounts /ramdisk/project, shared with your other containers in this project ON THE SAME SERVER (a RAM disk cannot span servers). Refused when the project has other members. Allowed: container, project
ramdisk
boolean
No
Whether to mount a ramdisk at /ramdisk. If omitted, the current value is preserved. Backed by a shared per-server memory pool (512 MiB by default, never more than 50% of the server memory). Data survives container restarts but is LOST on a host reboot.
environment_vars
object
No
Environment variables to set in the container as key-value pairs (string values, max 65536 chars each, max 200 properties, names match ^[a-zA-Z_][a-zA-Z0-9_]*$).
ssh_public_key
string
No
SSH public key for container access. SSH public keys must be unique per container. Re-sending the same key for the same container is a no-op. Set to null to clear or inherit from project defaults.
comment
string
No
Optional comment for the container (max 16000 characters). Set to null to clear existing comment.
realm_ids
array
No
Update realm membership for this container. Only unrestricted tokens and admin users can modify realm_ids.
Check the error message for specific field requirements and correct your input
INVALID_ID_FORMAT
Invalid ID format
The provided ID must be a 24-character hexadecimal string
Ensure the ID is exactly 24 characters long and contains only hexadecimal characters (0-9, a-f)
INVALID_CONTAINER_NAME
Invalid container name
Container name must be 3-100 characters, alphanumeric with hyphens and underscores.
Use a valid name between 3 and 100 characters containing only a-z, A-Z, 0-9, -, and _.
{
"statusCode":401,
"error":"Unauthorized",
"message":"Authentication token required"
}
Error Code
Title
Description
Resolution
MISSING_TOKEN
Authentication token missing
No authentication token was provided in the request
Include a valid JWT token in the Authorization header as “Bearer <token>“
INVALID_TOKEN
Invalid authentication token
The provided authentication token is malformed or invalid
Obtain a new token by logging in again or using a valid auth token
TOKEN_EXPIRED
Authentication token expired
The provided authentication token has expired
Obtain a new token by logging in again or refreshing your session
{
"statusCode":403,
"error":"Forbidden",
"message":"Insufficient permissions"
}
Error Code
Title
Description
Resolution
INSUFFICIENT_PERMISSIONS
Insufficient permissions
You do not have the required permissions to perform this action
Contact the resource owner or administrator to request access
ACCOUNT_BANNED
Account banned
Your account has been banned and cannot access this resource
Contact support for information about your account status
OPERATION_NOT_PERMITTED_ON_EXPIRED
Operation Not Permitted on Expired Container
This operation cannot be performed because the container has expired due to server termination.
The container is in a read-only state. No further operations are allowed. Please create a new container.
{
"statusCode":404,
"error":"Not Found",
"message":"Container not found"
}
Error Code
Title
Description
Resolution
CONTAINER_NOT_FOUND
Container not found
The requested container does not exist or you do not have permission to access it.
Verify the container ID is correct and that you have access to the project it belongs to.
RESOURCE_NOT_FOUND
Resource not found
The requested resource does not exist or has been deleted
Verify the resource ID and ensure it exists
{
"statusCode":409,
"error":"Conflict",
"message":"Container name already in use within the project"
}
Error Code
Title
Description
Resolution
CONTAINER_NAME_IN_USE
Container name already in use
A container with this name already exists in the project.
Choose a different name for your container.
SSH_PUBLIC_KEY_IN_USE
SSH public key already in use
SSH public keys must be unique per container. A single public key cannot be assigned to multiple containers because it is used for routing SSH connections.
Generate a new SSH key pair for this container, or remove the key from the other container before reusing it.
Enable or disable hardware virtualization passthrough (/dev/kvm) so the container can run full virtual machines. Available on rented/dedicated (bare-metal) servers only — never on free-tier servers. The container must be STOPPED. Send kvm: true to enable or kvm: false to disable; dev_kvm is accepted as an alias of kvm.
Issue a signed, portable container authorization claim.
The returned container_claim is an ED25519-signed credential that proves:
Who the user is (sub, claim_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 is needed during verification.
Claims expire after HOODY_CONTAINER_CLAIM_EXPIRES_IN (default 6h). Clients should re-call this endpoint to refresh before expiry.
Container claims share their wire format, signing key, and verification procedure with the identity claims issued at login (identity claims) — the differences are claim_type: "container" (verifiers must check this to prevent cross-claim confusion), the container/project fields, and the shorter lifetime.
