Container Environment Variables

The Container Environment Variables API lets you list, set, bulk-update, and delete environment variables on a container. Changes are written to /etc/environment (visible to PAM/SSH on next login) and to the Incus container configuration (visible to incus exec). Already-running processes do not pick up changes until they re-exec.

Key names must match the pattern ^[a-zA-Z_][a-zA-Z0-9_]*$ — start with a letter or underscore, then contain only alphanumeric characters and underscores.

List environment variables

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

Get all environment variables for a container.

Parameters

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

Response

{
  "statusCode": 200,
  "message": "Environment variables retrieved successfully",
  "data": {
    "environment_vars": {
      "DATABASE_URL": "postgres://app:secret@db.internal:5432/app_production",
      "NODE_ENV": "production",
      "REDIS_HOST": "cache.internal",
      "LOG_LEVEL": "info"
    }
  }
}

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.

curl -X GET https://api.hoody.com/api/v1/containers/5f9b3c2e1a8d4f7b6c5e2d3a/env \
  -H "Authorization: Bearer &lt;token&gt;"

const { data } = await client.api.env.list({
  id: "5f9b3c2e1a8d4f7b6c5e2d3a"
});

console.log(data.environment_vars);

Set environment variables

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

Merge environment variables into the container using merge semantics. Existing keys are updated, new keys are added, and keys not present in the body are left unchanged.

The request body is a JSON object whose keys are environment variable names and whose values are strings. Each value is limited to 32,768 characters. Each key must match ^[a-zA-Z_][a-zA-Z0-9_]*$, be at most 256 characters long, and must not start with HOODY_. The body must contain between 1 and 200 properties.

Parameters

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

Response

{
  "statusCode": 200,
  "message": "Environment variables updated successfully",
  "data": {
    "environment_vars": {
      "DATABASE_URL": "postgres://app:secret@db.internal:5432/app_production",
      "NODE_ENV": "production",
      "REDIS_HOST": "cache.internal"
    },
    "synced": true
  }
}

The data.synced field reports whether changes were propagated to the container. It is false if no changes were detected or if the sync 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_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.

Example request

cURL
TypeScript SDK

curl -X PUT https://api.hoody.com/api/v1/containers/5f9b3c2e1a8d4f7b6c5e2d3a/env \
  -H "Authorization: Bearer &lt;token&gt;" \
  -H "Content-Type: application/json" \
  -d '{
    "DATABASE_URL": "postgres://app:secret@db.internal:5432/app_production",
    "NODE_ENV": "production",
    "REDIS_HOST": "cache.internal"
  }'

await client.api.env.bulkSet({
  id: "5f9b3c2e1a8d4f7b6c5e2d3a",
  data: {
    DATABASE_URL: "postgres://app:secret@db.internal:5432/app_production",
    NODE_ENV: "production",
    REDIS_HOST: "cache.internal"
  }
});

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

Set or update a single environment variable on the container. Keys starting with HOODY_ are reserved and will be rejected.

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. Max 32,768 characters.

Response

{
  "statusCode": 200,
  "message": "Environment variable set successfully",
  "data": {
    "environment_vars": {
      "DATABASE_URL": "postgres://app:secret@db.internal:5432/app_production",
      "NODE_ENV": "production",
      "REDIS_HOST": "cache.internal"
    },
    "synced": true
  }
}

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.

Example request

cURL
TypeScript SDK

curl -X PUT https://api.hoody.com/api/v1/containers/5f9b3c2e1a8d4f7b6c5e2d3a/env/DATABASE_URL \
  -H "Authorization: Bearer &lt;token&gt;" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "postgres://app:secret@db.internal:5432/app_production"
  }'

await client.api.env.set({
  id: "5f9b3c2e1a8d4f7b6c5e2d3a",
  key: "DATABASE_URL",
  data: {
    value: "postgres://app:secret@db.internal:5432/app_production"
  }
});

Delete environment variables

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

Remove a single environment variable from the container. The operation is idempotent and returns 200 whether the key existed or not. Keys starting with HOODY_ are reserved and cannot be deleted.

Parameters

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

Response

{
  "statusCode": 200,
  "message": "Environment variable deleted successfully",
  "data": {
    "environment_vars": {
      "NODE_ENV": "production",
      "REDIS_HOST": "cache.internal"
    },
    "synced": true
  }
}

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.

Example request

cURL
TypeScript SDK

curl -X DELETE https://api.hoody.com/api/v1/containers/5f9b3c2e1a8d4f7b6c5e2d3a/env/DATABASE_URL \
  -H "Authorization: Bearer &lt;token&gt;"

await client.api.env.delete({
  id: "5f9b3c2e1a8d4f7b6c5e2d3a",
  key: "DATABASE_URL"
});