The Containers API provides endpoints for listing, creating, retrieving, updating, authorizing, and deleting container resources across your projects. Use these endpoints to manage container lifecycle, fetch real-time runtime and resource statistics, and issue offline-verifiable authorization claims for container programs.
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.
Number of containers to return per page - maximum 100 items
sort_by
query
string
No
Field to sort containers by. Allowed values: id, name, status, created_at, updated_at
sort_order
query
string
No
Sort direction - ascending or descending. Allowed values: 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 values: true, false
include_prespawn
query
string
No
Include prespawn containers in the listing. By default, prespawn containers are excluded from results. Allowed values: 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 values: true, false
include_deleting
query
string
No
Include containers currently being deleted. By default, deleting containers are excluded from results. Allowed values: 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.
Field to sort containers by. Allowed values: id, name, status, created_at, updated_at
sort_order
query
string
No
Sort direction. Allowed values: 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 values: true, false
include_prespawn
query
string
No
Include prespawn containers in the listing. By default, prespawn containers are excluded. Allowed values: true, false
include_deleting
query
string
No
Include containers currently being deleted. By default, deleting containers are excluded from results. Allowed values: 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.
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 values: 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.
Get real-time resource usage statistics for a container including CPU, memory, disk, and network metrics. Useful for monitoring performance and troubleshooting resource issues.
Issues a signed, portable container authorization claim. The returned container_claim is an ED25519-signed credential that proves the user identity, the authorized container, and the issue time.
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 the configured expiry (default 1h); clients should re-call this endpoint to refresh before expiry.
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). If not provided, a random color will be generated. The # prefix will be added automatically if missing, and the color will be converted to uppercase.
container_image
string
No
Container image to use. If null or not provided, will use the default configured image.
ai
boolean
No
Whether AI features are enabled. Default: true
environment_vars
object
No
Environment variables to set in the container. Keys must match ^[a-zA-Z_][a-zA-Z0-9_]*$. Max 200 properties, each value ≤ 65536 chars.
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.
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. 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. Default: false
prespawn
boolean
No
Create container as prespawn cache. Prespawn containers are excluded from default listings and quota counts. 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",
"created_at": "2025-01-15T15:45:00.000Z",
"updated_at": "2025-01-15T15:45:00.000Z",
"realm_ids": []
}
}
{
"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.
{
"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
Human-readable name for the container - must be unique within the project. 1-100 characters.
color
string
No
HEX color for the container (e.g., #FF0000 or FF0000). The # prefix will be added automatically if missing, and the color will be 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
boolean
No
Whether to mount a ramdisk at /ramdisk in the container. If omitted, the current value is preserved.
environment_vars
object
No
Environment variables to set in the container as key-value pairs. Max 200 properties.
ssh_public_key
string | null
No
SSH public key for container access. SSH public keys must be unique per container. Re-sending the same key is a no-op. Set to null to clear or inherit from project defaults.
comment
string | null
No
Optional comment for the container (max 16000 characters). Set to null to clear existing comment.
realm_ids
array
No
Update realm membership. 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.
