Container Environment Variables

The Container Environment Variables API lets you read, set, bulk-merge, and delete environment variables on a running container. Writes are propagated to two locations inside the container:

/etc/environment — picked up by PAM/SSH sessions on the next login.
Incus environment.<key> config — visible to incus exec.

Already-running processes keep their original environment until they re-exec. Variable keys must match ^[a-zA-Z_][a-zA-Z0-9_]*$, be at most 256 characters, and must not start with the reserved HOODY_ prefix. Variable values are strings with a maximum length of 32,768 characters.

List container environment variables

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

Retrieve every environment variable currently configured on the container.

Parameters

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

Example

curl https://api.hoody.icu/api/v1/containers/cnt_8f3a2b1c/env \
  -H "Authorization: Bearer <token>"

await client.api.env.list('cnt_8f3a2b1c');

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

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

Bulk set container environment variables

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

Merge environment variables into the container. Existing keys are overwritten with the supplied values, new keys are added, and keys absent from the body are left untouched. Writes are propagated to /etc/environment and to Incus environment.<key>; already-running processes do not pick up the change until they re-exec.

Parameters

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

Request Body

The body is a JSON object whose keys are environment variable names and whose values are the corresponding string values.

Between 1 and 200 keys per request.
Each key must match ^[a-zA-Z_][a-zA-Z0-9_]*$, be at most 256 characters, and must not start with HOODY_.
Each value is a string with a maximum length of 32,768 characters.

Example

curl -X PUT https://api.hoody.icu/api/v1/containers/cnt_8f3a2b1c/env \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "NODE_ENV": "production",
    "LOG_LEVEL": "info",
    "FEATURE_FLAG_NEW_UI": "true"
  }'

await client.api.env.bulkSet('cnt_8f3a2b1c', {
  NODE_ENV: 'production',
  LOG_LEVEL: 'info',
  FEATURE_FLAG_NEW_UI: 'true'
});

{
  "statusCode": 200,
  "message": "Environment variables updated successfully",
  "data": {
    "environment_vars": {
      "NODE_ENV": "production",
      "LOG_LEVEL": "info",
      "FEATURE_FLAG_NEW_UI": "true",
      "DATABASE_URL": "postgres://app:secret@db.internal:5432/myapp",
      "REDIS_HOST": "10.0.0.42"
    },
    "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

Set a single environment variable

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

Create or update one environment variable on the container. Writes are propagated to /etc/environment and to Incus environment.<key>; already-running processes do not pick up the change until they re-exec.

Parameters

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

Request Body

Name	Type	Required	Description
`value`	string	Yes	Value for the environment variable. Maximum length: 32,768 characters.

Example

curl -X PUT https://api.hoody.icu/api/v1/containers/cnt_8f3a2b1c/env/NODE_ENV \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "value": "production" }'

await client.api.env.set('cnt_8f3a2b1c', 'NODE_ENV', {
  value: 'production'
});

{
  "statusCode": 200,
  "message": "Environment variable updated successfully",
  "data": {
    "environment_vars": {
      "NODE_ENV": "production",
      "LOG_LEVEL": "info",
      "DATABASE_URL": "postgres://app:secret@db.internal:5432/myapp"
    },
    "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

Delete a single environment variable

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

Remove a single environment variable from the container. The operation is idempotent — the response is 200 whether or not the key previously existed. The variable is removed from /etc/environment (new PAM/SSH logins will no longer see it) and unset from Incus environment.<key>. Already-running processes keep their copy until they re-exec.

Parameters

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

Example

curl -X DELETE https://api.hoody.icu/api/v1/containers/cnt_8f3a2b1c/env/NODE_ENV \
  -H "Authorization: Bearer <token>"

await client.api.env.delete('cnt_8f3a2b1c', 'NODE_ENV');

{
  "statusCode": 200,
  "message": "Environment variable removed successfully",
  "data": {
    "environment_vars": {
      "LOG_LEVEL": "info",
      "DATABASE_URL": "postgres://app:secret@db.internal:5432/myapp"
    },
    "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