Container environment variables

The Container Environment Variables API manages process environment variables on a running container. Use it to list every variable on a container, merge in new variables or update existing ones (in bulk or one at a time), and delete individual variables.

Variables you write through these endpoints are persisted to /etc/environment inside the container, where they are picked up by PAM/SSH on the next login, and they are also applied to the container runtime environment, where they appear in any new exec or console session. Processes that are already running do not pick up the change until they re-exec.

Note

Keys starting with HOODY_ are reserved for system use and are rejected by the set and delete operations. A valid key matches the pattern ^[a-zA-Z_][a-zA-Z0-9_]*$ and is at most 128 characters long. Each value is a string between 1 and 4,096 characters (1,024 Unicode code points being roughly typical for ASCII).

Value redaction for Auth Tokens

Every response on this page returns the container’s whole map in environment_vars, along with a values_redacted flag that says whether the values were shown to you.

Caller	environment_vars	values_redacted
Logged-in session (JWT)	Every key with its value	false
Auth Token with containers.features.env_values	Every key with its value	false
Auth Token without containers.features.env_values	Every key, each with the value null	true

A redacted response is still a 200, and the set and delete operations still apply the change; only the returned map hides the values. The permission decides what comes back, not what a token may do: listing needs containers.read and changing a variable needs containers.update, with or without it. A container with no variables returns {}.

The full_access and dev_team templates grant containers.features.env_values; read_only, external_customer and finance_team do not. A token built from an explicit permission tree has it only when the tree sets it to true. Tokens that existed before this permission was introduced were granted it wherever they held containers.read or containers.update, so they still see values. The tokens the Hoody Agent creates for itself also hold it, so the agent reads values in your containers.

A redacted list response looks like this:

{
  "statusCode": 200,
  "message": "Environment variables retrieved",
  "data": {
    "environment_vars": {
      "DATABASE_URL": null,
      "LOG_LEVEL": null
    },
    "values_redacted": true,
    "env_sync": {
      "pending": false,
      "revision": 42,
      "applied_revision": 42,
      "verified_at": "2026-02-15T10:42:13.000Z",
      "attempted_at": "2026-02-15T10:42:13.000Z",
      "last_error": null,
      "exhausted": false
    }
  }
}

Caution

containers.features.env_values is not a secrets boundary. Anyone who can run commands in the container or read its files can read the same variables from /etc/environment or a process environment. A token that can set variables can also confirm a guess: setting a key to the value it already holds reports that nothing changed. Keep secrets a token must never see out of containers that token can reach.

List container environment variables

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

Return every environment variable on the container together with the host-side reconciliation state. The env_sync block reports whether a recent change is still pending on the host, which revision is currently applied, and when the host last verified it.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID.

This endpoint does not accept a request body.

Example request

cURL

curl -X GET "https://api.hoody.com/api/v1/containers/67e89abc123def456789abcd/env" \
  -H "Authorization: Bearer $HOODY_TOKEN"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.containers.env.list('67e89abc123def456789abcd');

Response

200

{
  "statusCode": 200,
  "message": "Environment variables retrieved",
  "data": {
    "environment_vars": {
      "DATABASE_URL": "postgres://app:secret@db.internal:5432/app",
      "LOG_LEVEL": "info",
      "FEATURE_FLAGS": "billing_v2,checkout_v3"
    },
    "values_redacted": false,
    "env_sync": {
      "pending": false,
      "revision": 42,
      "applied_revision": 42,
      "verified_at": "2026-02-15T10:42:13.000Z",
      "attempted_at": "2026-02-15T10:42:13.000Z",
      "last_error": null,
      "exhausted": false
    }
  }
}

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>.
RESOURCE_ACCESS_DENIED	Resource access denied	You do not have permission to access this specific resource.	Ensure you own this resource or have been granted access by the owner.
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.

422

Validation Error: the request does not match the operation schema, or its JSON body cannot be parsed. message names each failing check, and data, when present, lists them one entry per failing field.

{
  "statusCode": 422,
  "error": "Validation Error",
  "message": "Validation failed: /name must NOT have fewer than 3 characters"
}

Bulk set container environment variables

PUT /api/v1/containers/{id}/env

Merge multiple environment variables into the container in one call. Existing keys are updated, new keys are added, and keys not present in the request body are left unchanged (merge semantics).

The body is a flat JSON object where each property is an environment variable name and its value is a string between 1 and 4,096 characters. Key names must match ^[a-zA-Z_][a-zA-Z0-9_]*$, are at most 128 characters long, and may not start with the reserved HOODY_ prefix. A single request must contain between 1 and 256 properties.

Note

The PATCH HTTP verb is accepted on the same path as an alias for PUT. The SDK issues PUT.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID.

Request body

A flat object of environment variable names to values. Between 1 and 256 entries; each value is a string of 1 to 4,096 characters.

{
  "DATABASE_URL": "postgres://app:secret@db.internal:5432/app",
  "LOG_LEVEL": "info",
  "FEATURE_FLAGS": "billing_v2,checkout_v3"
}

Example request

cURL

curl -X PUT "https://api.hoody.com/api/v1/containers/67e89abc123def456789abcd/env" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "DATABASE_URL": "postgres://app:secret@db.internal:5432/app",
    "LOG_LEVEL": "info",
    "FEATURE_FLAGS": "billing_v2,checkout_v3"
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.containers.env.update('67e89abc123def456789abcd', {
  DATABASE_URL: 'postgres://app:secret@db.internal:5432/app',
  LOG_LEVEL: 'info',
  FEATURE_FLAGS: 'billing_v2,checkout_v3'
});

Response

200

{
  "statusCode": 200,
  "message": "Environment variables updated",
  "data": {
    "environment_vars": {
      "DATABASE_URL": "postgres://app:secret@db.internal:5432/app",
      "LOG_LEVEL": "info",
      "FEATURE_FLAGS": "billing_v2,checkout_v3",
      "LEGACY_FLAG": "off"
    },
    "values_redacted": false,
    "synced": true,
    "env_sync": {
      "pending": false,
      "revision": 43,
      "applied_revision": 43,
      "verified_at": "2026-02-15T11:00:00.000Z",
      "attempted_at": "2026-02-15T11:00:00.000Z",
      "last_error": null,
      "exhausted": false
    }
  }
}

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_ENV_KEY	Invalid Environment Variable Key	The environment variable key is invalid. Keys must start with a letter or underscore, contain only alphanumeric characters and underscores, and must not start with the reserved HOODY_ prefix.	Use a key that matches [a-zA-Z_][a-zA-Z0-9_]* and does not start with HOODY_.
RESERVED_ENV_PREFIX	Reserved Environment Variable Prefix	Environment variable keys starting with HOODY_ are reserved for system use and cannot be set or deleted by users.	Use a different key name that does not start with HOODY_.
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>.
RESOURCE_ACCESS_DENIED	Resource access denied	You do not have permission to access this specific resource.	Ensure you own this resource or have been granted access by the owner.
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.

422

Validation Error: the request does not match the operation schema, or its JSON body cannot be parsed. message names each failing check, and data, when present, lists them one entry per failing field.

{
  "statusCode": 422,
  "error": "Validation Error",
  "message": "Validation failed: /name must NOT have fewer than 3 characters"
}

Set a single environment variable

PUT /api/v1/containers/{id}/env/{key}

Set or update one environment variable, identified by key in the path. Use this when you only need to touch a single variable and do not want to merge into the whole map.

The value field is required and must be a string between 1 and 4,096 characters. The key must match ^[a-zA-Z_][a-zA-Z0-9_]*$, must be at most 128 characters long, and may not start with the reserved HOODY_ prefix.

Note

The PATCH HTTP verb is accepted on the same path as an alias for PUT. The SDK issues PUT.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID.
key	path	string	Yes	Environment variable key.

Request body

Field	Type	Required	Description
value	string	Yes	Value for the environment variable. Must be 1 to 4,096 characters.

{
  "value": "postgres://app:secret@db.internal:5432/app"
}

Example request

cURL

curl -X PUT "https://api.hoody.com/api/v1/containers/67e89abc123def456789abcd/env/DATABASE_URL" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value":"postgres://app:secret@db.internal:5432/app"}'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.containers.env.set('67e89abc123def456789abcd', 'DATABASE_URL', {
  value: 'postgres://app:secret@db.internal:5432/app'
});

Response

200

{
  "statusCode": 200,
  "message": "Environment variable updated",
  "data": {
    "environment_vars": {
      "DATABASE_URL": "postgres://app:secret@db.internal:5432/app",
      "LOG_LEVEL": "info"
    },
    "values_redacted": false,
    "synced": true,
    "env_sync": {
      "pending": false,
      "revision": 44,
      "applied_revision": 44,
      "verified_at": "2026-02-15T11:15:00.000Z",
      "attempted_at": "2026-02-15T11:15:00.000Z",
      "last_error": null,
      "exhausted": false
    }
  }
}

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_ENV_KEY	Invalid Environment Variable Key	The environment variable key is invalid. Keys must start with a letter or underscore, contain only alphanumeric characters and underscores, and must not start with the reserved HOODY_ prefix.	Use a key that matches [a-zA-Z_][a-zA-Z0-9_]* and does not start with HOODY_.
RESERVED_ENV_PREFIX	Reserved Environment Variable Prefix	Environment variable keys starting with HOODY_ are reserved for system use and cannot be set or deleted by users.	Use a different key name that does not start with HOODY_.
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>.
RESOURCE_ACCESS_DENIED	Resource access denied	You do not have permission to access this specific resource.	Ensure you own this resource or have been granted access by the owner.
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.

422

Validation Error: the request does not match the operation schema, or its JSON body cannot be parsed. message names each failing check, and data, when present, lists them one entry per failing field.

{
  "statusCode": 422,
  "error": "Validation Error",
  "message": "Validation failed: /name must NOT have fewer than 3 characters"
}

Delete a single environment variable

DELETE /api/v1/containers/{id}/env/{key}

Remove a single environment variable from the container. The call is idempotent and returns 200 whether or not the key was present. Reserved keys (those starting with HOODY_) are rejected.

The variable is removed from /etc/environment and from the container runtime environment. Already-running processes keep their copy of the variable until they re-exec.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID.
key	path	string	Yes	Environment variable key.

This endpoint does not accept a request body.

Example request

cURL

curl -X DELETE "https://api.hoody.com/api/v1/containers/67e89abc123def456789abcd/env/LEGACY_FLAG" \
  -H "Authorization: Bearer $HOODY_TOKEN"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.containers.env.delete('67e89abc123def456789abcd', 'LEGACY_FLAG');

Response

200

{
  "statusCode": 200,
  "message": "Environment variable deleted",
  "data": {
    "environment_vars": {
      "DATABASE_URL": "postgres://app:secret@db.internal:5432/app",
      "LOG_LEVEL": "info"
    },
    "values_redacted": false,
    "synced": true,
    "env_sync": {
      "pending": false,
      "revision": 45,
      "applied_revision": 45,
      "verified_at": "2026-02-15T11:30:00.000Z",
      "attempted_at": "2026-02-15T11:30:00.000Z",
      "last_error": null,
      "exhausted": false
    }
  }
}

Error Code	Title	Description	Resolution
RESERVED_ENV_PREFIX	Reserved Environment Variable Prefix	Environment variable keys starting with HOODY_ are reserved for system use and cannot be set or deleted by users.	Use a different key name that does not start with HOODY_.
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>.
RESOURCE_ACCESS_DENIED	Resource access denied	You do not have permission to access this specific resource.	Ensure you own this resource or have been granted access by the owner.
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.

422

Validation Error: the request does not match the operation schema, or its JSON body cannot be parsed. message names each failing check, and data, when present, lists them one entry per failing field.

{
  "statusCode": 422,
  "error": "Validation Error",
  "message": "Validation failed: /name must NOT have fewer than 3 characters"
}