The Containers API provides endpoints to list, create, retrieve, update, and delete containers. It also exposes container resource statistics and signed authorization claims for offline verification by container programs. Use these endpoints to manage container lifecycles across projects, monitor performance, and issue portable credentials.
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. Allowed: id, name, status, created_at, updated_at. Default: "created_at"
sort_order
query
string
No
Sort direction - ascending or descending. Allowed: asc, desc. Default: "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 - maximum 100 items. 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
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 6h). Clients should re-call this endpoint to refresh before expiry.
The successful response also includes an X-Hoody-Signature header containing an ED25519 signature of the response body. Format: t=<unix_ts>,kid=<keyId>,path=<urlPath>,sig=<128-hex>.
{
"statusCode": 400,
"error": "Bad Request",
"message": "Invalid ID format"
}
Error Code
Title
Description
Resolution
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)
{
"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>“
{
"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
{
"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.
{
"statusCode": 503,
"error": "SIGNING_NOT_CONFIGURED",
"message": "Response signing is not configured on this API instance"
Identifier of the server that will host the container.
name
string
No
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.
ai
boolean
No
Whether AI features are enabled. Default: true
environment_vars
object
No
Environment variables to set in the container as key-value string pairs. Up to 200 properties, each value up to 65536 characters. Property names must 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, the key is inherited from project defaults.
comment
string
No
Optional comment for the container (max 16000 characters).
hoody_kit
boolean
No
Enable all Hoody Kit features. Default: true
dev_kit
boolean
No
Enable dev_kit development tools in the container. Defaults to true when hoody_kit is true, false otherwise (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 creation of a new cached image from the container image. Only available to admins or the owner of the 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. If creating from a realm subdomain, the subdomain realm is automatically included and merged with any explicitly provided realm_ids.
"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": "Invalid container name"
}
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 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
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 string pairs. Up to 200 properties, each value up to 65536 characters. Property names must 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). Re-sending the same key for the same container is treated as 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; realm-restricted tokens cannot change realm membership for security.
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.
