# Computer Environment Variables **Page:** api/computer-env [Download Raw Markdown](./api/computer-env.md) --- # 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. Keys starting with `HOODY_` are reserved for system use and are rejected by the bulk-set, 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 non-empty string of 1 to 4096 UTF-8 bytes. A multibyte value can be refused below 4096 characters. ## 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 ```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 } } } ``` `computers.features.env_values` is not a secrets boundary. Anyone who can run commands in the computer 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 computers that token can reach. ## 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 | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `id` | path | string | Yes | Computer ID. | This endpoint does not accept a request body. ### Example request ```bash curl -X GET "https://api.hoody.com/api/v1/computers/67e89abc123def456789abcd/env" \ -H "Authorization: Bearer $HOODY_TOKEN" ``` ```typescript 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 Media type: application/json ```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. ```json { "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 ` 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. ```json { "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. ```json { "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. ```json { "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. ```json { "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 `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. 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 | Computer ID. | ### 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. ```json { "DATABASE_URL": "postgres://app:secret@db.internal:5432/app", "LOG_LEVEL": "info", "FEATURE_FLAGS": "billing_v2,checkout_v3" } ``` ### Example request ```bash 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" }' ``` ```typescript 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 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. ```json { "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. ```json { "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. ```json { "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 ` 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. ```json { "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. ```json { "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. ```json { "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. ```json { "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. ```json { "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. ```json { "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 `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. 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 | Computer ID. | | `key` | path | string | Yes | Environment variable key. | ### 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. | ```json { "value": "postgres://app:secret@db.internal:5432/app" } ``` ### Example request ```bash 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"}' ``` ```typescript 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 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. ```json { "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. ```json { "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. ```json { "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 ` 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. ```json { "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. ```json { "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. ```json { "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. ```json { "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. ```json { "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. ```json { "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 `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 | 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 ```bash curl -X DELETE "https://api.hoody.com/api/v1/computers/67e89abc123def456789abcd/env/LEGACY_FLAG" \ -H "Authorization: Bearer $HOODY_TOKEN" ``` ```typescript 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 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. ```json { "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. ```json { "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. ```json { "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 ` 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. ```json { "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. ```json { "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. ```json { "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. ```json { "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. ```json { "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. ```json { "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. |