Proxy Aliases

Overview

Proxy aliases let you create custom short URLs that route to a container, masking the underlying Project ID and Container ID. Instead of sharing https://{projectId}-{containerId}.{server_name}.containers.hoody.com/, you can share https://{alias}.{server_name}.containers.hoody.com/. This page covers listing, retrieving, creating, updating, enabling/disabling, and deleting proxy aliases.

List proxy aliases

GET /api/v1/proxy/aliases

List all proxy aliases for your account with optional filtering by project, container, realm, enabled status, or expiration.

Parameters

Name	In	Type	Required	Description
`project_id`	query	string	No	Filter by project ID
`container_id`	query	string	No	Filter by container ID
`realm_id`	query	string	No	Filter by realm ID. Alternative to using realm subdomain in URL.
`enabled`	query	string	No	Filter by enabled status (`"true"` or `"false"`)
`expired`	query	string	No	Filter by expiration: `"true"` = only expired, `"false"` = only non-expired

Response

{
  "statusCode": 200,
  "message": "Proxy aliases retrieved successfully",
  "data": {
    "aliases": [
      {
        "id": "507f1f77bcf86cd799439022",
        "user_id": "507f1f77bcf86cd799439088",
        "project_id": "507f1f77bcf86cd799439033",
        "container_id": "507f1f77bcf86cd799439011",
        "alias": "my-portfolio",
        "program": "http",
        "index": 3000,
        "target_path": null,
        "allow_path_override": true,
        "expires_at": null,
        "enabled": true,
        "created_at": "2025-01-15T10:30:00.000Z",
        "updated_at": "2025-01-15T10:30:00.000Z",
        "server_id": "507f1f77bcf86cd799439044",
        "server_name": "node-sg-sin-1",
        "url": "https://my-portfolio.node-sg-sin-1.containers.hoody.com"
      },
      {
        "id": "507f1f77bcf86cd799439055",
        "project_id": "507f1f77bcf86cd799439033",
        "container_id": "507f1f77bcf86cd799439066",
        "alias": "c3a8f1b2e4d5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3",
        "program": "https",
        "index": 8443,
        "target_path": "/v1",
        "allow_path_override": true,
        "expires_at": "2025-06-30T23:59:59.000Z",
        "enabled": true,
        "created_at": "2025-01-10T08:00:00.000Z",
        "updated_at": "2025-01-10T08:00:00.000Z",
        "server_id": "507f1f77bcf86cd799439044",
        "server_name": "node-sg-sin-1",
        "subserver_name": "user-slice-7",
        "url": "https://c3a8f1b2e4d5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3.node-sg-sin-1.containers.hoody.com"
      }
    ],
    "count": 2
  }
}

SDK usage

for await (const alias of client.api.proxyAliases.listIterator({ project_id: "507f1f77bcf86cd799439033" })) {
  console.log(alias.alias, alias.url);
}

Get proxy alias by ID

GET /api/v1/proxy/aliases/{id}

Retrieve detailed information about a specific proxy alias, including the associated project and container.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Proxy alias ID

Response

{
  "statusCode": 200,
  "message": "Proxy alias retrieved successfully",
  "data": {
    "id": "507f1f77bcf86cd799439022",
    "user_id": "507f1f77bcf86cd799439077",
    "project_id": "507f1f77bcf86cd799439033",
    "container_id": "507f1f77bcf86cd799439011",
    "alias": "my-app",
    "program": "http",
    "index": 3000,
    "target_path": "/api",
    "allow_path_override": true,
    "expires_at": "2025-12-31T23:59:59.000Z",
    "enabled": true,
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T10:30:00.000Z",
    "url": "https://my-app.node-sg-sin-1.containers.hoody.com",
    "server_id": "507f1f77bcf86cd799439044",
    "server_name": "node-sg-sin-1",
    "subserver_name": "user-slice-7",
    "project": {
      "id": "507f1f77bcf86cd799439033",
      "alias": "production"
    },
    "container": {
      "id": "507f1f77bcf86cd799439011",
      "name": "web-app-1"
    }
  }
}

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Proxy alias not found"
}

SDK usage

const alias = await client.api.proxyAliases.get("507f1f77bcf86cd799439022");
console.log(alias.data.url);

Create a new proxy alias

POST /api/v1/proxy/aliases

Create a custom domain alias for a container. You can supply a custom alias (3–61 characters, lowercase a–z, 0–9, hyphens) or omit alias (or pass null/false) to auto-generate a 48-character hex string for maximum obscurity.

Request Body

Field	Type	Required	Default	Description
`container_id`	string	Yes	—	Container ID this alias points to. You must own this container.
`program`	string	Yes	—	Built-in Hoody program (`terminal`, `files`, `code`, `browser`, `agent`, `display`, …) or transport protocol (`http`, `https`, `ssh`). Use `http`/`https` with `port` to reach an HTTP server running inside the container (e.g. `program: "http"` + `port: 3000`). Must exist in `container-programs.json`.
`alias`	string \| null \| false	No	—	Custom alias name (lowercase a–z, 0–9, hyphens; 3–61 chars; cannot start/end with hyphen) or `null`/`false` to auto-generate a 48-char hex. Must be unique across your account.
`port`	integer	No	—	Target port for the `http`/`https` protocol (1–65535). The port your server listens on inside the container. Takes precedence over `index` and any port embedded in `program` (e.g. `http-3000`). Ignored for built-in programs.
`index`	integer	No	—	Instance index for built-in programs (≥ 1), or legacy port for `http`/`https`. Defaults to 1. Prefer the `port` field for HTTP.
`target_path`	string \| null	No	—	Base path for routing. Auto-prefixed with `/` if missing. Max 2048 characters.
`allow_path_override`	boolean	No	`true`	Whether to allow URL paths beyond `target_path`.
`expires_at`	string	No	—	Optional ISO 8601 expiration date. The alias is automatically disabled after this date.
`enabled`	boolean	No	`true`	Whether the alias is initially enabled.

Response

{
  "statusCode": 201,
  "message": "Proxy alias created successfully",
  "data": {
    "id": "507f1f77bcf86cd799439022",
    "user_id": "507f1f77bcf86cd799439088",
    "project_id": "507f1f77bcf86cd799439033",
    "container_id": "507f1f77bcf86cd799439011",
    "alias": "my-app",
    "program": "http",
    "index": 3000,
    "target_path": "/api",
    "allow_path_override": true,
    "expires_at": "2025-12-31T23:59:59.000Z",
    "enabled": true,
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T10:30:00.000Z",
    "server_id": "507f1f77bcf86cd799439044",
    "server_name": "node-sg-sin-1",
    "subserver_name": "user-slice-7",
    "url": "https://my-app.node-sg-sin-1.containers.hoody.com"
  }
}

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation failed"
}

Error Code	Title	Description	Resolution
`VALIDATION_ERROR`	Invalid input parameters	One or more request parameters failed validation.	Check the error message for specific field requirements and correct your input.
`INVALID_ALIAS_FORMAT`	Invalid Alias Format	The alias contains invalid characters or does not meet length requirements.	Use 3–61 characters, lowercase a–z, 0–9, and hyphens only (not at start/end).

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}

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>`.
`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.

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

Error Code	Title	Description	Resolution
`INSUFFICIENT_PERMISSIONS`	Insufficient permissions	You do not have the required permissions to perform this action.	Contact the resource owner or administrator to request access.

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Container not found"
}

Error Code	Title	Description	Resolution
`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.

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Alias is already in use."
}

Error Code	Title	Description	Resolution
`ALIAS_IN_USE`	Alias In Use	The requested alias is already in use by another user or project.	Choose a different alias.

SDK usage

const alias = await client.api.proxyAliases.create({
  container_id: "507f1f77bcf86cd799439011",
  alias: "my-app",
  program: "http",
  port: 3000
});
console.log(alias.data.url);

Update proxy alias

PATCH /api/v1/proxy/aliases/{id}

Update an existing proxy alias. Only the fields you include are modified. Renaming the alias also renames the underlying file on the server.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Proxy alias ID to update

Request Body

Field	Type	Required	Description
`alias`	string	No	New alias name (3–61 chars; lowercase a–z, 0–9, hyphens; cannot start/end with hyphen). Must be unique across your account.
`program`	string	No	Built-in Hoody program (`terminal`, `files`, `code`, …) or transport protocol (`http`, `https`, `ssh`). Use `http`/`https` with `port` to reach an HTTP server running inside the container. Order of authority for ports is `port` > port embedded in `program` (`http-3000`) > `index`. Must exist in `container-programs.json`.
`port`	integer	No	Target port for the `http`/`https` protocol (1–65535). The port your server listens on inside the container. Takes precedence over `index` and any port embedded in `program`. Ignored for built-in programs.
`index`	integer	No	Instance index (≥ 1), or legacy target port for `http`/`https`. Prefer the `port` field when set.
`target_path`	string \| null	No	Base path for routing. Set to `null` to remove the path prefix. Max 2048 characters.
`allow_path_override`	boolean	No	Whether to allow paths beyond `target_path`.
`expires_at`	string \| number \| null	No	Expiration date — ISO 8601 string, Unix timestamp (seconds or milliseconds), or `null` to remove expiration.
`enabled`	boolean	No	Whether the alias is enabled.

Response

{
  "statusCode": 200,
  "message": "Proxy alias updated successfully",
  "data": {
    "id": "507f1f77bcf86cd799439022",
    "user_id": "507f1f77bcf86cd799439077",
    "project_id": "507f1f77bcf86cd799439033",
    "container_id": "507f1f77bcf86cd799439011",
    "alias": "updated-app-name",
    "program": "http",
    "index": 8080,
    "target_path": "/v2",
    "allow_path_override": false,
    "expires_at": null,
    "enabled": true,
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T14:45:00.000Z",
    "url": "https://updated-app-name.node-sg-sin-1.containers.hoody.com",
    "server_id": "507f1f77bcf86cd799439044",
    "server_name": "node-sg-sin-1",
    "subserver_name": "user-slice-7"
  }
}

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid request payload"
}

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Proxy alias not found"
}

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Alias is already in use."
}

SDK usage

const result = await client.api.proxyAliases.update("507f1f77bcf86cd799439022", {
  alias: "my-new-name",
  enabled: false
});
console.log(result.data.alias);

Enable or disable proxy alias

PATCH /api/v1/proxy/aliases/{id}/state

Temporarily enable or disable a proxy alias without deleting it. Disabled aliases return 404 but can be re-enabled later.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Proxy alias ID

Request Body

Field	Type	Required	Description
`enabled`	boolean	Yes	Set to `true` to enable, `false` to disable.

Response

{
  "statusCode": 200,
  "message": "Proxy alias disabled successfully",
  "data": {
    "id": "507f1f77bcf86cd799439022",
    "user_id": "507f1f77bcf86cd799439077",
    "project_id": "507f1f77bcf86cd799439033",
    "container_id": "507f1f77bcf86cd799439011",
    "alias": "my-app",
    "program": "http",
    "index": 3000,
    "target_path": "/api",
    "allow_path_override": true,
    "expires_at": "2025-12-31T23:59:59.000Z",
    "enabled": false,
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T14:45:00.000Z",
    "url": "https://my-app.node-sg-sin-1.containers.hoody.com",
    "server_id": "507f1f77bcf86cd799439044",
    "server_name": "node-sg-sin-1",
    "subserver_name": "user-slice-7"
  }
}

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Proxy alias not found"
}

SDK usage

const result = await client.api.proxyAliases.setState("507f1f77bcf86cd799439022", {
  enabled: false
});
console.log(result.data.enabled);

Delete proxy alias

DELETE /api/v1/proxy/aliases/{id}

Permanently delete a proxy alias and remove its file from the server. The alias URL immediately returns 404.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Proxy alias ID to delete

Response

{
  "statusCode": 200,
  "message": "Proxy alias deleted successfully"
}

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Proxy alias not found"
}

SDK usage

await client.api.proxyAliases.delete("507f1f77bcf86cd799439022");