Computer environment variables
Section titled “Computer environment variables”In the Hub, open Computers and select the computer. In Overview, open Environment variables and choose Edit variables. Add a variable, enter a New value or remove one, then choose Save. Saved values are not shown again.
Use the computer environment variables API to list, merge, set, or delete the API-managed environment variables of a computer.
Variables are persisted to /etc/environment inside the computer, where they are picked up by PAM or SSH on the next login. They are also applied to the computer runtime environment, where they appear in new exec and console sessions. Processes that are already running do not pick up the change until they re-exec.
Value redaction for Auth Tokens
Section titled “Value redaction for Auth Tokens”Every successful response that returns the environment map includes the complete API-managed 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 JWT session | Every API-managed key with its value | false |
Auth token with computers.features.env_values | Every API-managed key with its value | false |
Auth token without computers.features.env_values | Every API-managed 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 grants no access on its own: listing requires computers.read, while changing a variable requires computers.update.
The full_access and dev_team templates grant computers.features.env_values; read_only, external_customer, and finance_team do not. The Hoody Agent’s own tokens also hold it, so the agent reads values in your computers.
A computer with no variables returns {}. A redacted list response looks like this:
Media type: application/json
{ "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 } }}List computer environment variables
Section titled “List computer environment variables”GET /api/v1/computers/{id}/env
Get the computer’s API-managed environment variables and their sync state. This is not the full environment of every process on the computer. The env_sync block reports whether a recent change is still pending, which revision is currently applied, and when the computer last verified it.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Computer ID. |
This endpoint does not accept a request body.
Example request
Section titled “Example request”curl -X GET "https://api.hoody.com/api/v1/computers/67e89abc123def456789abcd/env" \ -H "Authorization: Bearer $HOODY_TOKEN"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
await client.api.computers.env.list('67e89abc123def456789abcd');Response
Section titled “Response”Media type: application/json
{ "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 } }}Media type: application/json
The request did not include valid, active credentials.
{ "statusCode": 401, "error": "INVALID_TOKEN", "message": "Invalid or expired token"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
MISSING_TOKEN | Authentication token missing | The request carries no Authorization header, or the header holds no token. | Send an Authorization header as Bearer <token> with a sign-in token or an auth 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 sign-in token (JWT) has expired. An expired auth token is refused with INVALID_TOKEN instead. | Sign in again, or refresh the session. |
AUTH_TOKEN_LINEAGE_REVOKED | Parent auth token no longer valid | The auth token was created by another auth token, and that token, or one above it, has been revoked, disabled, or has expired, so this one no longer authenticates. | Create a new auth token from a valid one, or sign in again. |
INVALID_CREDENTIALS | Invalid credentials | The provided username, email, or password is incorrect. | Verify your credentials and try again, or use the password reset feature. |
EMAIL_NOT_VERIFIED | Email not verified | Returned by the login endpoint when the password is correct but the account’s email address has not been verified yet. It is only returned after the password has been checked. The response carries data.email so the client can offer a resend verification email action without asking again. | Complete email verification by clicking the link sent to your inbox, call POST /api/v1/auth/resend-verification to receive a new link, or complete a password reset, which also implicitly verifies the email. |
INVALID_OTP_CODE | Invalid OTP code | The provided 2FA code is incorrect or has expired. | Generate a new code from your authenticator app and try again. |
Media type: application/json
The credentials do not allow this operation.
{ "statusCode": 403, "error": "INSUFFICIENT_PERMISSIONS", "message": "You do not have access to this computer"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
INSUFFICIENT_PERMISSIONS | Insufficient permissions | You do not own this computer, the auth token lacks the computers.read permission, or the computer is not in the realm of the request URL. | Use an account or auth token that can manage this computer, and call the realm the computer belongs to. |
ACCOUNT_BANNED | Account banned | Your account has been banned and cannot access this resource. | Contact support for information about your account status. |
Media type: application/json
The requested computer or its project could not be found.
{ "statusCode": 404, "error": "Not Found", "message": "Computer not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
COMPUTER_NOT_FOUND | Computer not found | No computer has this ID. A computer you cannot access answers 403 INSUFFICIENT_PERMISSIONS. | Verify the computer ID is correct and that you have access to the project it belongs to. |
PROJECT_NOT_FOUND | Project Not Found | The computer exists but its project does not. | Contact support. |
Media type: application/json
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: /field_name must be string"}Media type: application/json
An unexpected error occurred while retrieving the environment variables.
{ "statusCode": 500, "error": "Internal Server Error", "message": "Failed to retrieve environment variables"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
INTERNAL_SERVER_ERROR | Internal server error | An unexpected error occurred while handling the environment variables. | Retry. If the problem persists, contact support. |
Bulk set computer environment variables
Section titled “Bulk set computer environment variables”PUT /api/v1/computers/{id}/env
Merge multiple environment variables into the computer in one call. Existing keys are updated, new keys are added, and keys not present in the request body are left unchanged.
The body is a flat JSON object where each property is an environment variable name and its value is a non-empty string of 1 to 4096 UTF-8 bytes. A multibyte value can be refused below 4096 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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Computer ID. |
Request body
Section titled “Request body”A flat object of environment variable names to values. Between 1 and 256 entries; each value is a non-empty string of 1 to 4096 UTF-8 bytes. A multibyte value can be refused below 4096 characters.
{ "DATABASE_URL": "postgres://app:secret@db.internal:5432/app", "LOG_LEVEL": "info", "FEATURE_FLAGS": "billing_v2,checkout_v3"}Example request
Section titled “Example request”curl -X PUT "https://api.hoody.com/api/v1/computers/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" }'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
await client.api.computers.env.update('67e89abc123def456789abcd', { DATABASE_URL: 'postgres://app:secret@db.internal:5432/app', LOG_LEVEL: 'info', FEATURE_FLAGS: 'billing_v2,checkout_v3'});Response
Section titled “Response”Media type: application/json
The synced field is true when the change was applied and verified during the request. It is false when no change was detected or application is still pending.
{ "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 } }}Media type: application/json
The request body contains an invalid key, value, or resulting environment.
{ "statusCode": 400, "error": "Bad Request", "message": "Environment variable values cannot contain \"#\" (/etc/environment treats it as a comment, even inside quotes). (key: GREETING)"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
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. A key that fits this pattern is still refused when it is a system key, such as PATH, HOME, LD_PRELOAD, NODE_OPTIONS, or a proxy variable, or starts with LD_. The message names the rule and the key. | Use a key that matches ^[a-zA-Z_][a-zA-Z0-9_]*$, does not start with HOODY_ or LD_, and is not a system key. |
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_. |
ENV_VALUE_INVALID | Invalid Environment Variable Value | The value cannot be stored as written: it contains a newline, a carriage return, a NUL byte or #, is not well-formed Unicode, or is longer than 4096 bytes. When several values are set at once, the message ends with the key of the refused value. Nothing was changed. | Remove the characters the message names, or shorten the value. |
ENV_BLOCK_TOO_LARGE | Environment Too Large | The environment the change would leave on the computer is larger than the computer can hold. data gives the sizes (rendered_bytes, json_bytes, cap_bytes), the number of variables (entries), and the keys with the largest values (offending_keys). Nothing was changed. | Delete or shorten some variables, starting with the keys in data.offending_keys, then retry. |
ENV_UNREPRESENTABLE | Environment Cannot Be Applied | The environment the change would leave on the computer holds a variable that cannot be applied, or more than 256 variables. data.offending_keys names the variables that cannot be applied. data also gives entries, json_bytes, rendered_bytes, and cap_bytes. Nothing was changed. | Delete or correct the variables in data.offending_keys, or remove variables until at most 256 remain, then retry. |
Media type: application/json
The request did not include valid, active credentials.
{ "statusCode": 401, "error": "INVALID_TOKEN", "message": "Invalid or expired token"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
MISSING_TOKEN | Authentication token missing | The request carries no Authorization header, or the header holds no token. | Send an Authorization header as Bearer <token> with a sign-in token or an auth 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 sign-in token (JWT) has expired. An expired auth token is refused with INVALID_TOKEN instead. | Sign in again, or refresh the session. |
AUTH_TOKEN_LINEAGE_REVOKED | Parent auth token no longer valid | The auth token was created by another auth token, and that token, or one above it, has been revoked, disabled, or has expired, so this one no longer authenticates. | Create a new auth token from a valid one, or sign in again. |
INVALID_CREDENTIALS | Invalid credentials | The provided username, email, or password is incorrect. | Verify your credentials and try again, or use the password reset feature. |
EMAIL_NOT_VERIFIED | Email not verified | Returned by the login endpoint when the password is correct but the account’s email address has not been verified yet. It is only returned after the password has been checked. The response carries data.email so the client can offer a resend verification email action without asking again. | Complete email verification by clicking the link sent to your inbox, call POST /api/v1/auth/resend-verification to receive a new link, or complete a password reset, which also implicitly verifies the email. |
INVALID_OTP_CODE | Invalid OTP code | The provided 2FA code is incorrect or has expired. | Generate a new code from your authenticator app and try again. |
Media type: application/json
The credentials do not allow this operation.
{ "statusCode": 403, "error": "INSUFFICIENT_PERMISSIONS", "message": "You do not have access to this computer"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
INSUFFICIENT_PERMISSIONS | Insufficient permissions | You do not own this computer, the auth token lacks the computers.update permission, the computer is not in the realm of the request URL, or the computer’s owner no longer has access to its server. | Use an account or auth token that can manage this computer, and call the realm the computer belongs to. |
computer_quarantined | Computer Held for Review | The computer is held for review, so its environment cannot be changed. Nothing was changed. | Contact support. |
ACCOUNT_BANNED | Account banned | Your account has been banned and cannot access this resource. | Contact support for information about your account status. |
Media type: application/json
The requested computer or its project could not be found.
{ "statusCode": 404, "error": "Not Found", "message": "Computer not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
COMPUTER_NOT_FOUND | Computer not found | No computer has this ID. A computer you cannot access answers 403 INSUFFICIENT_PERMISSIONS. | Verify the computer ID is correct and that you have access to the project it belongs to. |
PROJECT_NOT_FOUND | Project Not Found | The computer exists but its project does not. | Contact support. |
Media type: application/json
The computer could not accept the environment change in its current state.
{ "statusCode": 409, "error": "SUBSERVER_DORMANT", "message": "This subserver is not active: its subscription is on hold, being delivered, or a change to it is in progress. Try again once it is active.", "data": { "server_id": "66f0a1b2c3d4e5f6a7b8c9d0", "reason": "not_active" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
computer_finalizing | Computer is still being set up | The computer is still being set up and refuses changes until that completes. | Retry in a few seconds. |
computer_quarantined | Computer Held for Review | The computer was held for review while the change was in flight. No change was applied. | Contact support. |
ENV_REVISION_EXHAUSTED | Environment change limit reached | The computer’s environment has been changed the maximum number of times. Nothing was changed. | Contact support to reset it. |
COMPUTER_EXPIRED | Computer Has Expired | The computer expired when its server ended or was reinstalled, so its environment cannot be changed. Nothing was changed. | The computer cannot be changed again. Delete it, then create a new computer. |
SUBSERVER_DORMANT | Subserver is not active | The computer is on a paid subserver whose subscription is not active or has a change in progress, so its environment cannot be changed. data.reason is not_active, operation_in_flight, or no_subscription. Nothing was changed. | Retry once the subserver is active again. Renew a held subscription, or wait for the change to finish. |
Media type: application/json
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: /field_name must be string"}Media type: application/json
The Retry-After response header gives the number of seconds to wait before retrying. It is sent when the request allowance is used up.
{ "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
RATE_LIMIT_EXCEEDED | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. |
Media type: application/json
An unexpected error occurred while updating the environment variables.
{ "statusCode": 500, "error": "Internal Server Error", "message": "Failed to update environment variables"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
INTERNAL_SERVER_ERROR | Internal server error | An unexpected error occurred while handling the environment variables. | Retry. If the problem persists, contact support. |
Set a single environment variable
Section titled “Set a single environment variable”PUT /api/v1/computers/{id}/env/{key}
Set or update one environment variable, identified by key in the path. Use this when you only need to change a single variable without merging into the whole map.
The value field is required and must be a non-empty string of 1 to 4096 UTF-8 bytes. A multibyte value can be refused below 4096 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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Computer ID. |
key | path | string | Yes | Environment variable key. |
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
value | string | Yes | Value for the environment variable. Must be a non-empty string of 1 to 4096 UTF-8 bytes. A multibyte value can be refused below 4096 characters. |
{ "value": "postgres://app:secret@db.internal:5432/app"}Example request
Section titled “Example request”curl -X PUT "https://api.hoody.com/api/v1/computers/67e89abc123def456789abcd/env/DATABASE_URL" \ -H "Authorization: Bearer $HOODY_TOKEN" \ -H "Content-Type: application/json" \ -d '{"value":"postgres://app:secret@db.internal:5432/app"}'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
await client.api.computers.env.set('67e89abc123def456789abcd', 'DATABASE_URL', { value: 'postgres://app:secret@db.internal:5432/app'});Response
Section titled “Response”Media type: application/json
The synced field is true when the change was applied and verified during the request. It is false when no change was detected or application is still pending.
{ "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 } }}Media type: application/json
The request contains an invalid key or value, or the resulting environment cannot be applied.
{ "statusCode": 400, "error": "Bad Request", "message": "Environment variable values cannot contain \"#\" (/etc/environment treats it as a comment, even inside quotes). (key: GREETING)"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
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. A key that fits this pattern is still refused when it is a system key, such as PATH, HOME, LD_PRELOAD, NODE_OPTIONS, or a proxy variable, or starts with LD_. The message names the rule and the key. | Use a key that matches ^[a-zA-Z_][a-zA-Z0-9_]*$, does not start with HOODY_ or LD_, and is not a system key. |
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_. |
ENV_VALUE_INVALID | Invalid Environment Variable Value | The value cannot be stored as written: it contains a newline, a carriage return, a NUL byte or #, is not well-formed Unicode, or is longer than 4096 bytes. When several values are set at once, the message ends with the key of the refused value. Nothing was changed. | Remove the characters the message names, or shorten the value. |
ENV_BLOCK_TOO_LARGE | Environment Too Large | The environment the change would leave on the computer is larger than the computer can hold. data gives the sizes (rendered_bytes, json_bytes, cap_bytes), the number of variables (entries), and the keys with the largest values (offending_keys). Nothing was changed. | Delete or shorten some variables, starting with the keys in data.offending_keys, then retry. |
ENV_UNREPRESENTABLE | Environment Cannot Be Applied | The environment the change would leave on the computer holds a variable that cannot be applied, or more than 256 variables. data.offending_keys names the variables that cannot be applied. data also gives entries, json_bytes, rendered_bytes, and cap_bytes. Nothing was changed. | Delete or correct the variables in data.offending_keys, or remove variables until at most 256 remain, then retry. |
Media type: application/json
The request did not include valid, active credentials.
{ "statusCode": 401, "error": "INVALID_TOKEN", "message": "Invalid or expired token"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
MISSING_TOKEN | Authentication token missing | The request carries no Authorization header, or the header holds no token. | Send an Authorization header as Bearer <token> with a sign-in token or an auth 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 sign-in token (JWT) has expired. An expired auth token is refused with INVALID_TOKEN instead. | Sign in again, or refresh the session. |
AUTH_TOKEN_LINEAGE_REVOKED | Parent auth token no longer valid | The auth token was created by another auth token, and that token, or one above it, has been revoked, disabled, or has expired, so this one no longer authenticates. | Create a new auth token from a valid one, or sign in again. |
INVALID_CREDENTIALS | Invalid credentials | The provided username, email, or password is incorrect. | Verify your credentials and try again, or use the password reset feature. |
EMAIL_NOT_VERIFIED | Email not verified | Returned by the login endpoint when the password is correct but the account’s email address has not been verified yet. It is only returned after the password has been checked. The response carries data.email so the client can offer a resend verification email action without asking again. | Complete email verification by clicking the link sent to your inbox, call POST /api/v1/auth/resend-verification to receive a new link, or complete a password reset, which also implicitly verifies the email. |
INVALID_OTP_CODE | Invalid OTP code | The provided 2FA code is incorrect or has expired. | Generate a new code from your authenticator app and try again. |
Media type: application/json
The credentials do not allow this operation.
{ "statusCode": 403, "error": "INSUFFICIENT_PERMISSIONS", "message": "You do not have access to this computer"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
INSUFFICIENT_PERMISSIONS | Insufficient permissions | You do not own this computer, the auth token lacks the computers.update permission, the computer is not in the realm of the request URL, or the computer’s owner no longer has access to its server. | Use an account or auth token that can manage this computer, and call the realm the computer belongs to. |
computer_quarantined | Computer Held for Review | The computer is held for review, so its environment cannot be changed. Nothing was changed. | Contact support. |
ACCOUNT_BANNED | Account banned | Your account has been banned and cannot access this resource. | Contact support for information about your account status. |
Media type: application/json
The requested computer or its project could not be found.
{ "statusCode": 404, "error": "Not Found", "message": "Computer not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
COMPUTER_NOT_FOUND | Computer not found | No computer has this ID. A computer you cannot access answers 403 INSUFFICIENT_PERMISSIONS. | Verify the computer ID is correct and that you have access to the project it belongs to. |
PROJECT_NOT_FOUND | Project Not Found | The computer exists but its project does not. | Contact support. |
Media type: application/json
The computer could not accept the environment change in its current state.
{ "statusCode": 409, "error": "SUBSERVER_DORMANT", "message": "This subserver is not active: its subscription is on hold, being delivered, or a change to it is in progress. Try again once it is active.", "data": { "server_id": "66f0a1b2c3d4e5f6a7b8c9d0", "reason": "not_active" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
computer_finalizing | Computer is still being set up | The computer is still being set up and refuses changes until that completes. | Retry in a few seconds. |
computer_quarantined | Computer Held for Review | The computer was held for review while the change was in flight. No change was applied. | Contact support. |
ENV_REVISION_EXHAUSTED | Environment change limit reached | The computer’s environment has been changed the maximum number of times. Nothing was changed. | Contact support to reset it. |
COMPUTER_EXPIRED | Computer Has Expired | The computer expired when its server ended or was reinstalled, so its environment cannot be changed. Nothing was changed. | The computer cannot be changed again. Delete it, then create a new computer. |
SUBSERVER_DORMANT | Subserver is not active | The computer is on a paid subserver whose subscription is not active or has a change in progress, so its environment cannot be changed. data.reason is not_active, operation_in_flight, or no_subscription. Nothing was changed. | Retry once the subserver is active again. Renew a held subscription, or wait for the change to finish. |
Media type: application/json
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: /field_name must be string"}Media type: application/json
The Retry-After response header gives the number of seconds to wait before retrying. It is sent when the request allowance is used up.
{ "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
RATE_LIMIT_EXCEEDED | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. |
Media type: application/json
An unexpected error occurred while setting the environment variable.
{ "statusCode": 500, "error": "Internal Server Error", "message": "Failed to set environment variable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
INTERNAL_SERVER_ERROR | Internal server error | An unexpected error occurred while handling the environment variables. | Retry. If the problem persists, contact support. |
Delete a single environment variable
Section titled “Delete a single environment variable”DELETE /api/v1/computers/{id}/env/{key}
Remove a single environment variable from the computer. The call is idempotent and returns 200 whether or not the key was present. Reserved keys, including those starting with HOODY_, are rejected.
The variable is removed from /etc/environment and from the computer runtime environment. Already-running processes keep their copy of the variable until they re-exec.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Computer ID. |
key | path | string | Yes | Environment variable key. |
This endpoint does not accept a request body.
Example request
Section titled “Example request”curl -X DELETE "https://api.hoody.com/api/v1/computers/67e89abc123def456789abcd/env/LEGACY_FLAG" \ -H "Authorization: Bearer $HOODY_TOKEN"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
await client.api.computers.env.delete('67e89abc123def456789abcd', 'LEGACY_FLAG');Response
Section titled “Response”Media type: application/json
The synced field is true when the change was applied and verified during the request. It is false when no change was detected or application is still pending.
{ "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 } }}Media type: application/json
The request contains an invalid key or the resulting environment cannot be applied.
{ "statusCode": 400, "error": "Bad Request", "message": "Environment variable keys starting with HOODY_ are reserved: HOODY_TOKEN"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
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. A key that fits this pattern is still refused when it is a system key, such as PATH, HOME, LD_PRELOAD, NODE_OPTIONS, or a proxy variable, or starts with LD_. The message names the rule and the key. | Use a key that matches ^[a-zA-Z_][a-zA-Z0-9_]*$, does not start with HOODY_ or LD_, and is not a system key. |
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_. |
ENV_BLOCK_TOO_LARGE | Environment Too Large | The environment the change would leave on the computer is larger than the computer can hold. data gives the sizes (rendered_bytes, json_bytes, cap_bytes), the number of variables (entries), and the keys with the largest values (offending_keys). Nothing was changed. | Delete or shorten some variables, starting with the keys in data.offending_keys, then retry. |
ENV_UNREPRESENTABLE | Environment Cannot Be Applied | The environment the change would leave on the computer holds a variable that cannot be applied, or more than 256 variables. data.offending_keys names the variables that cannot be applied. data also gives entries, json_bytes, rendered_bytes, and cap_bytes. Nothing was changed. | Delete or correct the variables in data.offending_keys, or remove variables until at most 256 remain, then retry. |
Media type: application/json
The request did not include valid, active credentials.
{ "statusCode": 401, "error": "INVALID_TOKEN", "message": "Invalid or expired token"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
MISSING_TOKEN | Authentication token missing | The request carries no Authorization header, or the header holds no token. | Send an Authorization header as Bearer <token> with a sign-in token or an auth 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 sign-in token (JWT) has expired. An expired auth token is refused with INVALID_TOKEN instead. | Sign in again, or refresh the session. |
AUTH_TOKEN_LINEAGE_REVOKED | Parent auth token no longer valid | The auth token was created by another auth token, and that token, or one above it, has been revoked, disabled, or has expired, so this one no longer authenticates. | Create a new auth token from a valid one, or sign in again. |
INVALID_CREDENTIALS | Invalid credentials | The provided username, email, or password is incorrect. | Verify your credentials and try again, or use the password reset feature. |
EMAIL_NOT_VERIFIED | Email not verified | Returned by the login endpoint when the password is correct but the account’s email address has not been verified yet. It is only returned after the password has been checked. The response carries data.email so the client can offer a resend verification email action without asking again. | Complete email verification by clicking the link sent to your inbox, call POST /api/v1/auth/resend-verification to receive a new link, or complete a password reset, which also implicitly verifies the email. |
INVALID_OTP_CODE | Invalid OTP code | The provided 2FA code is incorrect or has expired. | Generate a new code from your authenticator app and try again. |
Media type: application/json
The credentials do not allow this operation.
{ "statusCode": 403, "error": "INSUFFICIENT_PERMISSIONS", "message": "You do not have access to this computer"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
INSUFFICIENT_PERMISSIONS | Insufficient permissions | You do not own this computer, the auth token lacks the computers.update permission, the computer is not in the realm of the request URL, or the computer’s owner no longer has access to its server. | Use an account or auth token that can manage this computer, and call the realm the computer belongs to. |
computer_quarantined | Computer Held for Review | The computer is held for review, so its environment cannot be changed. Nothing was changed. | Contact support. |
ACCOUNT_BANNED | Account banned | Your account has been banned and cannot access this resource. | Contact support for information about your account status. |
Media type: application/json
The requested computer or its project could not be found.
{ "statusCode": 404, "error": "Not Found", "message": "Computer not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
COMPUTER_NOT_FOUND | Computer not found | No computer has this ID. A computer you cannot access answers 403 INSUFFICIENT_PERMISSIONS. | Verify the computer ID is correct and that you have access to the project it belongs to. |
PROJECT_NOT_FOUND | Project Not Found | The computer exists but its project does not. | Contact support. |
Media type: application/json
The computer could not accept the environment change in its current state.
{ "statusCode": 409, "error": "SUBSERVER_DORMANT", "message": "This subserver is not active: its subscription is on hold, being delivered, or a change to it is in progress. Try again once it is active.", "data": { "server_id": "66f0a1b2c3d4e5f6a7b8c9d0", "reason": "not_active" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
computer_finalizing | Computer is still being set up | The computer is still being set up and refuses changes until that completes. | Retry in a few seconds. |
computer_quarantined | Computer Held for Review | The computer was held for review while the change was in flight. No change was applied. | Contact support. |
ENV_REVISION_EXHAUSTED | Environment change limit reached | The computer’s environment has been changed the maximum number of times. Nothing was changed. | Contact support to reset it. |
COMPUTER_EXPIRED | Computer Has Expired | The computer expired when its server ended or was reinstalled, so its environment cannot be changed. Nothing was changed. | The computer cannot be changed again. Delete it, then create a new computer. |
SUBSERVER_DORMANT | Subserver is not active | The computer is on a paid subserver whose subscription is not active or has a change in progress, so its environment cannot be changed. data.reason is not_active, operation_in_flight, or no_subscription. Nothing was changed. | Retry once the subserver is active again. Renew a held subscription, or wait for the change to finish. |
Media type: application/json
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: /field_name must be string"}Media type: application/json
The Retry-After response header gives the number of seconds to wait before retrying. It is sent when the request allowance is used up.
{ "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
RATE_LIMIT_EXCEEDED | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. |
Media type: application/json
An unexpected error occurred while deleting the environment variable.
{ "statusCode": 500, "error": "Internal Server Error", "message": "Failed to delete environment variable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
INTERNAL_SERVER_ERROR | Internal server error | An unexpected error occurred while handling the environment variables. | Retry. If the problem persists, contact support. |