Skip to content
Hoody Documentation
Hoody.com
Download Page (.md)

Proxy Permissions

Section titled “Proxy Permissions”

Every request to a container service passes through the Hoody Proxy, which checks it against your permission configuration. You decide who can access which services, per group and per instance, at project or container level.

This builds on the proxy architecture and aliases.

API endpoints summary

Section titled “API endpoints summary”

This Foundation page explains permission concepts and configuration strategies. The complete endpoint documentation:

Project-level permissions:

Container-level permissions:

Container proxy hooks (MITM traffic interception):

Container proxy settings (root enable/default policy):

The permission system

Section titled “The permission system”

Access control happens in layers:

┌─────────────────────────────────────┐
│  Hoody API Authentication           │  ← User login, API tokens
│  (api.hoody.com)                    │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│  Hoody Proxy Permissions            │  ← THIS PAGE
│  (Container access control)         │
│                                     │
│  ├─ Project-Level Permissions       │  ← Apply to all containers
│  └─ Container-Level Permissions     │  ← Override for specific containers
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│  Container Services                 │
│  (terminal, display, files, etc.)   │
└─────────────────────────────────────┘

Two separate systems are involved:

  1. Hoody API auth - Access to platform management (create containers, configure firewall)
  2. Proxy permissions - Access to container services (execute commands, read files, view displays)

This page covers proxy permissions: how to control who can use your container’s terminal, files, displays, and other services.

Core concepts

Section titled “Core concepts”

Groups (who can access)

Section titled “Groups (who can access)”

Groups define authentication methods. Each group specifies how users prove their identity:

  • JWT - Token-based with secret verification and claims validation
  • Password - Username/password via HTTP Basic Auth
  • IP - Allow/deny based on client IP address or CIDR range
  • Token - Bearer token validation
  • Hoody Identity - Native Hoody identity-claim verification (hoody-identity)

For example:

{
  "groups": {
    "developers": {
      "type": "ip",
      "range": "203.0.113.0/24"
    },
    "customers": {
      "type": "jwt",
      "secret": "a-long-random-signing-key-with-32-plus-chars",
      "algorithm": "HS256",
      "sources": ["header:Authorization"]
    },
    "admin": {
      "type": "password",
      "username": "admin",
      "password": "hashed-password",
      "algorithm": "sha256",
      "salt": "unique-salt"
    }
  }
}

Permissions (what they can access)

Section titled “Permissions (what they can access)”

Permissions map groups to programs, with per-instance control.

Each group gets specific access to container programs using:

  • true - Allow all instances
  • false - Deny all instances
  • number - Allow only this instance/port (e.g., 1 allows instance 1)
  • array - Allow specific instances/ports (e.g., [1, 2])
  • "8000-8100" - Allow a port range (network programs only)
  • "*" - Allow every instance (any indexed program; rejected for http/https, which must name ports)

Indexed programs (terminal, display, code, browser, …) accept all of the above. The programs files, exec, services, and notifications accept only true/false.

Explicit ports for http and https

Section titled “Explicit ports for http and https”

http and https are not programs. They are the transport labels in a container hostname (<project>-<container>-http-8080). Their permission cell gates raw ports, so it must name the ports it opens:

"http": [8080]        // this port only
"http": [80, 8080]    // these ports
"http": 8080          // shorthand for one port
"http": "8000-8100"   // an inclusive range

A bare "http": true or "http": "*" is rejected: the API returns 422 Validation Error naming the port form, and a range covering more than 16384 ports is rejected the same way. There is no “all ports” grant: name the ports your application serves and you get exactly those.

"http": false cannot be written either; every bare boolean is rejected. To deny raw-port access, omit the http cell entirely (with "default": "deny" nothing is granted). A document that already contains "http": false still acts as an explicit deny at the proxy.

What a port grant opens

Section titled “What a port grant opens”

A port grant opens whatever is listening on that port inside your container.

Ports belonging to Hoody’s own always-on services are refused outright, so a grant can never reach them: the container daemon, file server, terminal, code server, browser, exec, the agent API and the shared display server are all off limits, and an attempt to name one is denied even inside a wide range.

What a grant does not do is inspect what else your container put on the port. If you started a display instance that happens to occupy the port you granted, the grant reaches that display, and a "display": false cell in the same group will not prevent it: the request arrives as a raw port, not as the display program. This matters only if you both deny a program and grant a port that program happens to be using; grant the ports your application serves and it does not arise.

ssh is not a permission gate. An ssh hostname carries no port and routes to the dedicated SSH proxy, so an ssh cell in this document has no effect; use the container’s SSH key configuration instead.

{
  "permissions": {
    "developers": {
      "terminal": [1, 2],    // Allow terminal instances 1 and 2 only
      "files": true,         // Allow all file service instances
      "display": 1,          // Allow only display instance 1
      "http": [8080]         // Allow port 8080 only
    },
    "customers": {
      "http": [8080],        // Allow only port 8080
      "terminal": false,     // Deny all terminal access
      "files": false         // Deny all file access
    },
    "admin": {
      "terminal": true,      // Full access to all terminals
      "files": true,         // Full access to files
      "display": true,       // Full access to all displays
      "http": [8080, 8443]   // Allow ports 8080 and 8443
    }
  }
}

Default policy (fallback)

Section titled “Default policy (fallback)”

The default policy decides what happens when no group matches:

{
  "default": "deny"  // or "allow"
}
  • “deny” - Block access if no group matches (secure by default)
  • “allow” - Permit access if no group matches (open by default)

Hierarchy (project vs container)

Section titled “Hierarchy (project vs container)”

Permissions can be set at two levels:

Project Level
  ├─ Applies to ALL containers in project
  └─ Good for consistent team access
      ↓
Container Level
  ├─ Overrides project settings for specific container
  └─ Good for exceptions (public container in private project)

If both are configured, the two documents merge and container-level values take precedence wherever they overlap.

Open by default

Section titled “Open by default”

A new container has no proxy permissions configured. Its URLs are reachable by anyone who has them: the proxy applies no authentication and no group matching, and the two 24-character IDs in the hostname are the credential.

The URL contains:

https://67e89abc123def456789abcd-890abcdef12345678901cdef-terminal-1.node-us.containers.hoody.com
       └────────24-char hex────┘ └────────24-char hex────┘

The project and container IDs give 2^96 × 2^96 = 2^192 possible combinations, which makes the pair practically unguessable. Sharing the URL grants access, and so does any other way the URL travels: pasted into Slack, captured in a screenshot, logged by a referer header, or cached by a browser extension, it lets the holder hit the container directly. Unguessability prevents blind discovery; it does not contain leaks or replace access control.

This default is what makes instant collaboration work: sharing the URL is the whole setup, nothing needs configuring, and anyone who has the link can join.

When you need real access control, set proxy permissions before sharing anything sensitive. Do not rely on URL secrecy, and never paste container URLs into public channels, public dashboards, or untrusted third-party tools.

Configure permissions

Section titled “Configure permissions”

Project-level permissions

Section titled “Project-level permissions”

To apply authentication to every container in a project:

Terminal window
# Set project-level proxy permissions (IP-restricted team access).
# Whole-document `permissions replace` is currently unavailable in the CLI;
# build the document one field at a time. Each write bumps file_version, so
# re-read the If-Match ETag before every command with
# `hoody projects proxy permissions get --project $PROJECT_ID -o json`.
hoody projects proxy groups ip set --project $PROJECT_ID \
  --group-name team --range 203.0.113.0/24 --if-match file:v<N>
hoody projects proxy groups permissions set --project $PROJECT_ID \
  --group-name team --program terminal --access '[1,2]' --if-match file:v<N>
hoody projects proxy groups permissions set --project $PROJECT_ID \
  --group-name team --program files --access true --if-match file:v<N>
hoody projects proxy groups permissions set --project $PROJECT_ID \
  --group-name team --program display --access 1 --if-match file:v<N>
hoody projects proxy groups permissions set --project $PROJECT_ID \
  --group-name team --program http --access '[8080]' --if-match file:v<N>
hoody projects proxy default --project $PROJECT_ID --default deny --if-match file:v<N>
PATCH Set project-level proxy permissions
/api/v1/projects/{project_id}/proxy/permissions
Click "Run" to execute the request

Every container in this project now:

  • requires a client IP in the 203.0.113.0/24 range
  • grants that group access to terminal, files, display, and http
  • denies all other access

Container-level permissions

Section titled “Container-level permissions”

To override the project settings for a specific container:

Terminal window
# Override permissions for a specific container (public HTTP only).
# Whole-document `permissions replace` is currently unavailable in the CLI;
# build the document one field at a time, re-reading the If-Match ETag before
# every command with `hoody containers proxy permissions get -c $CONTAINER_ID -o json`.
hoody containers proxy groups ip set -c $CONTAINER_ID \
  --group-name public --range 0.0.0.0/0 --if-match file:v<N>
hoody containers proxy groups permissions set -c $CONTAINER_ID \
  --group-name public --program http --access '[8080]' --if-match file:v<N>
hoody containers proxy groups permissions set -c $CONTAINER_ID \
  --group-name public --program terminal --access false --if-match file:v<N>
hoody containers proxy groups permissions set -c $CONTAINER_ID \
  --group-name public --program files --access false --if-match file:v<N>
hoody containers proxy default -c $CONTAINER_ID --default deny --if-match file:v<N>
PATCH Set container-level proxy permissions (overrides project)
/api/v1/containers/{container_id}/proxy/permissions
Click "Run" to execute the request

This container now:

  • accepts requests from any IP (public access)
  • allows HTTP services only
  • denies terminal and files for the public group
  • overrides the project document only where entries overlap; project groups this document does not name stay in force

A typical use: a public demo container in an otherwise private project.

Authentication groups

Section titled “Authentication groups”

A group defines how a client authenticates.

JWT authentication

Section titled “JWT authentication”

A jwt group validates JSON Web Tokens:

{
  "groups": {
    "authenticated_users": {
      "type": "jwt",
      "secret": "a-long-random-signing-key-with-32-plus-chars",
      "algorithm": "HS256",
      "sources": ["header:Authorization", "cookie:auth_token"],
      "claims": {
        "iss": "mycompany.com",
        "aud": "production-api"
      }
    }
  }
}

Parameters:

  • secret - JWT signing key (required). For HS256 the key must be at least 32 characters and must not contain a common weak word (secret, password, 123456, test, dev, default); the API returns 422 otherwise. For RS256/ES256 this is the PEM-encoded public key.
  • algorithm - HS256, RS256, or ES256 (required)
  • sources - Where to look for the token (required). Each entry must match header:Name or cookie:Name; JWTs can only be read from a header or a cookie.
  • claims - Required JWT claims to validate (optional)

Token source examples:

  • header:Authorization - Bearer token in the Authorization header
  • cookie:session - JWT in a session cookie

Use this when your application issues JWTs to users and Hoody validates them at the proxy.

Hoody identity authentication

Section titled “Hoody identity authentication”

A hoody-identity group gates a service on “a valid Hoody user”. The proxy verifies the ED25519 identity claim Hoody mints (via POST /api/v1/users/auth/identity-claim), rejects everything else, and injects verified identity headers your app can trust:

{
  "groups": {
    "hoody_users": {
      "type": "hoody-identity",
      "audience": "myapp.example.com",
      "allow_types": ["user", "admin"],
      "users": ["507f1f77bcf86cd799439011"],
      "max_age_seconds": 86400,
      "expose_type": false
    }
  }
}

Parameters:

  • audience - Required. The claim’s aud must equal this exactly. Clients mint a bound claim with POST /api/v1/users/auth/identity-claim { "audience": "myapp.example.com" }. Unbound (login-issued) claims are always rejected; an audience gate can never be satisfied by a generic 30-day login claim.
  • sources - Optional header sources within the reserved namespace (default ["header:X-Hoody-Identity-Claim"]). Clients send the claim as <kid>.<payload_b64>.<signature_hex>.
  • allow_types - Optional subset of ["user", "admin"] (default both).
  • users - Optional allowlist of user IDs (up to 256); enforces “my users only” at the proxy.
  • max_age_seconds - Optional freshness gate on the claim’s iat (min 300).
  • expose_type - Also inject X-Hoody-Identity-Type (user|admin). Off by default so platform-admin isn’t mistaken for app-admin.

Your app receives verified X-Hoody-Identity-Sub (user ID) and X-Hoody-Identity-Username headers, injected by the edge after it unconditionally strips any client-supplied X-Hoody-Identity-* headers. The values are trustworthy on every proxied request, and the claim credential itself never reaches your app. Key material is operator-owned (the proxy’s trust keyring); group config never carries keys.

A group alone is not a gate. The file must also set explicit service cells and "default": "deny", or unauthenticated traffic falls through to the default policy:

{
  "groups":      { "hoody_users": { "type": "hoody-identity", "audience": "myapp.example.com" } },
  "permissions": { "hoody_users": { "run": true } },
  "default":     "deny"
}

After activating, verify that anonymous access is denied: a curl without the header must get 403. Once a gate file has been active, a missing or undistributed file fails closed (deny), never open.

In v1 the gate covers programmatic clients: CLIs, SDKs, native apps, and server-to-server calls. Browsers cannot attach custom headers on navigation, so use a proxy hook for browser apps. It applies on the reverse-proxy path only (not the forward-proxy/CONNECT products) and gates WebSocket handshakes; established sockets outlive claim expiry, so terminate server-side if you need live cutoff.

Password authentication

Section titled “Password authentication”

A password group uses HTTP Basic Auth:

{
  "groups": {
    "admin_access": {
      "type": "password",
      "username": "admin",
      "password": "hashed-password-here",
      "algorithm": "sha256",
      "salt": "unique-salt-value"
    }
  }
}

Parameters:

  • username - Exact username match required
  • password - Plain or hashed password
  • algorithm - Hashing algorithm (sha256)
  • salt - Salt for password hashing

Browsers show their built-in Basic Auth prompt automatically.

Basic Auth is an old protocol, and that is its value here: it is portable. It needs no JWT library or token management, every browser has a native prompt, and any HTTP client can send it with nothing but a username and password. Credentials are simple enough for a person to remember and type, and they can be embedded in a URL (https://user:pass@domain.com works in most contexts). There is no token expiration, refresh flow, or claims validation to manage, and it keeps working when an external OAuth provider is down.

Common uses:

  • Simple admin access
  • Quick demos and prototypes
  • Temporary contractor access
  • Emergency access paths
  • Internal tools where JWT overhead isn’t worth it
  • Any scenario where portability matters more than sophistication

IP-based authentication

Section titled “IP-based authentication”

An ip group allows or denies by client IP address:

{
  "groups": {
    "office_network": {
      "type": "ip",
      "range": "203.0.113.0/24"
    },
    "vpn_users": {
      "type": "ip",
      "range": "198.51.100.0/24"
    }
  }
}

Parameters:

  • range - IPv4 CIDR notation (e.g., 203.0.113.50/32 for a single IP)

Use this to restrict access to an office network, a VPN, or known IPs.

The proxy sees real client IPs (not proxy IPs) thanks to Hoody’s netfilter hooks, so IP rules match the actual client.

Token authentication

Section titled “Token authentication”

A token group validates bearer tokens:

{
  "groups": {
    "api_partners": {
      "type": "token",
      "value": "token-abc-123",
      "header": "X-Api-Token"
    }
  }
}

A token group carries a single value plus exactly one of header, cookie, or param specifying where the token is read from.

Use this to distribute tokens to API consumers, partners, and integrations.

Authentication without headers (hoody-curl)

Section titled “Authentication without headers (hoody-curl)”

Some environments cannot send custom headers: browser bookmarks (just URLs), QR codes (GET only), email links (no header control), and restricted platforms (iOS Shortcuts, some automation tools). hoody-curl works around this by transforming an authenticated request into a plain GET URL.

How it works:

Terminal window
# Requires ability to send Authorization header
curl "https://PROJECT_ID-CONTAINER_ID-terminal-1.node-us.containers.hoody.com/execute" \
  -H "Authorization: Bearer jwt-token-here" \
  -H "Content-Type: application/json" \
  -d '{"command": "ls -la"}'


# Can't do this from browser bookmark
# Can't do this from QR code
# Can't embed in simple URL

For example, a bookmark that triggers a deployment:

// Create a bookmark URL that deploys your app
const curlService = "https://PROJECT_ID-CONTAINER_ID-curl-1.node-us.containers.hoody.com";
const targetService = "https://PROJECT_ID-CONTAINER_ID-exec-1.node-us.containers.hoody.com/api/deploy";
const authToken = "your-jwt-token";


const bookmarkUrl = `${curlService}/api/v1/curl/request?` + new URLSearchParams({
  url: targetService,
  method: 'POST',
  header: `Authorization: Bearer ${authToken}`,
  json: JSON.stringify({ environment: 'production' })
});


// Save as bookmark: "Deploy Production"
// Clicking the bookmark triggers the deployment
// without a terminal or a curl command

Use cases:

  • Emergency deployments - A bookmark that deploys
  • Mobile access - A QR code that triggers a workflow
  • Email notifications - “Click here to approve” links
  • Restricted automation - iOS Shortcuts, Zapier webhooks
  • Simple sharing - Send a URL instead of a curl command

See Hoody cURL for complete documentation on wrapping HTTP requests.

Per-program permissions

Section titled “Per-program permissions”

Every program takes an access rule, and most of them can name individual instances instead of the whole program.

Access rule value types

Section titled “Access rule value types”

A permission cell holds a boolean, a number, an array, a port-range string, or a wildcard:

{
  "permissions": {
    "developers": {
      "terminal": true,      // Allow ALL terminal instances
      "files": false         // Deny ALL file service instances
    }
  }
}

Use when: Simple all-or-nothing access

Available programs

Section titled “Available programs”

The programs you can configure:

  • http - HTTP services (port-based: http-80, http-3000, etc.)
  • ssh - SSH access to container
  • terminal - Hoody Terminal service instances
  • display - Hoody Display (desktop / web-UI) instances
  • files - Hoody Files service
  • exec - Hoody Exec script execution
  • services - Container service endpoints
  • notifications - Notification service

Instance-level isolation

Section titled “Instance-level isolation”

A container running five terminal instances can give each team its own:

{
  "permissions": {
    "frontend_team": {
      "terminal": [1, 2],    // Frontend devs get terminals 1 and 2
      "display": 1,
      "http": [8080]
    },
    "backend_team": {
      "terminal": [3, 4],    // Backend devs get terminals 3 and 4
      "display": 2,
      "http": [8080]
    },
    "ops_team": {
      "terminal": true,      // Ops gets ALL terminals
      "display": true,       // ALL displays
      "http": [8080]
    }
  }
}

Each team reaches only its own instances, and all three share one container.

Configuration examples

Section titled “Configuration examples”

Development team access

Section titled “Development team access”

An internal team with broad access, restricted to the office IP range:

Terminal window
# Configure IP-restricted developer access for entire project.
# Whole-document `permissions replace` is currently unavailable in the CLI;
# build the document one field at a time, re-reading the If-Match ETag before
# every command with `hoody projects proxy permissions get --project $PROJECT_ID -o json`.
hoody projects proxy groups ip set --project $PROJECT_ID \
  --group-name developers --range 203.0.113.0/24 --if-match file:v<N>
hoody projects proxy groups permissions set --project $PROJECT_ID \
  --group-name developers --program terminal --access true --if-match file:v<N>
hoody projects proxy groups permissions set --project $PROJECT_ID \
  --group-name developers --program display --access true --if-match file:v<N>
hoody projects proxy groups permissions set --project $PROJECT_ID \
  --group-name developers --program files --access true --if-match file:v<N>
hoody projects proxy groups permissions set --project $PROJECT_ID \
  --group-name developers --program http --access '[8080]' --if-match file:v<N>
hoody projects proxy default --project $PROJECT_ID --default deny --if-match file:v<N>
PATCH Configure IP-restricted developer access
/api/v1/projects/{project_id}/proxy/permissions
Click "Run" to execute the request

With this configuration:

  • developers from the office network (203.0.113.0/24) get full access
  • everyone else is denied
  • the rules apply to every container in the project

Public API with private admin

Section titled “Public API with private admin”

A container-level override that opens the HTTP API while keeping the admin services behind a password:

Terminal window
# Public API (JWT for customers) + private admin group (password).
# Whole-document `permissions replace` is currently unavailable in the CLI;
# build the document one field at a time, re-reading the If-Match ETag before
# every command with `hoody containers proxy permissions get -c $CONTAINER_ID -o json`.
hoody containers proxy groups jwt set -c $CONTAINER_ID \
  --group-name customers --secret 'a-long-random-signing-key-with-32-plus-chars' \
  --algorithm HS256 --sources header:Authorization --if-match file:v<N>
hoody containers proxy groups password set -c $CONTAINER_ID \
  --group-name admin --auth-username admin --auth-password 'hashed-admin-password' \
  --salt 'unique-salt' --if-match file:v<N>
hoody containers proxy groups permissions set -c $CONTAINER_ID \
  --group-name customers --program http --access '[8080]' --if-match file:v<N>
hoody containers proxy groups permissions set -c $CONTAINER_ID \
  --group-name admin --program terminal --access true --if-match file:v<N>
hoody containers proxy groups permissions set -c $CONTAINER_ID \
  --group-name admin --program display --access true --if-match file:v<N>
hoody containers proxy groups permissions set -c $CONTAINER_ID \
  --group-name admin --program files --access true --if-match file:v<N>
hoody containers proxy groups permissions set -c $CONTAINER_ID \
  --group-name admin --program http --access '[8080]' --if-match file:v<N>
hoody containers proxy default -c $CONTAINER_ID --default deny --if-match file:v<N>
PATCH Configure public API with private admin access
/api/v1/containers/{container_id}/proxy/permissions
Click "Run" to execute the request

With this configuration:

  • customers with a valid JWT reach the HTTP API only
  • the admin group authenticates with a password and reaches terminal, display, and all files
  • everyone else is denied

Multi-tier team access

Section titled “Multi-tier team access”

Three teams on one project document, each with a different level of access:

Terminal window
# Multi-tier: ops (full), developers (partial), readonly (HTTP only).
# Whole-document `permissions replace` is currently unavailable in the CLI;
# build the document one field at a time, re-reading the If-Match ETag before
# every command with `hoody projects proxy permissions get --project $PROJECT_ID -o json`.
hoody projects proxy groups ip set --project $PROJECT_ID \
  --group-name ops_team --range 203.0.113.0/24 --if-match file:v<N>
hoody projects proxy groups ip set --project $PROJECT_ID \
  --group-name developers --range 198.51.100.0/24 --if-match file:v<N>
hoody projects proxy groups password set --project $PROJECT_ID \
  --group-name readonly_users --auth-username viewer --auth-password 'hashed-pass' \
  --salt 'salt' --if-match file:v<N>


# ops_team: terminal, display, files, http
hoody projects proxy groups permissions set --project $PROJECT_ID \
  --group-name ops_team --program terminal --access true --if-match file:v<N>
hoody projects proxy groups permissions set --project $PROJECT_ID \
  --group-name ops_team --program display --access true --if-match file:v<N>
hoody projects proxy groups permissions set --project $PROJECT_ID \
  --group-name ops_team --program files --access true --if-match file:v<N>
hoody projects proxy groups permissions set --project $PROJECT_ID \
  --group-name ops_team --program http --access '[8080]' --if-match file:v<N>


# developers: terminal, files, http
hoody projects proxy groups permissions set --project $PROJECT_ID \
  --group-name developers --program terminal --access true --if-match file:v<N>
hoody projects proxy groups permissions set --project $PROJECT_ID \
  --group-name developers --program files --access true --if-match file:v<N>
hoody projects proxy groups permissions set --project $PROJECT_ID \
  --group-name developers --program http --access '[8080]' --if-match file:v<N>


# readonly_users: http only
hoody projects proxy groups permissions set --project $PROJECT_ID \
  --group-name readonly_users --program http --access '[8080]' --if-match file:v<N>
hoody projects proxy groups permissions set --project $PROJECT_ID \
  --group-name readonly_users --program terminal --access false --if-match file:v<N>
hoody projects proxy groups permissions set --project $PROJECT_ID \
  --group-name readonly_users --program display --access false --if-match file:v<N>
hoody projects proxy groups permissions set --project $PROJECT_ID \
  --group-name readonly_users --program files --access false --if-match file:v<N>


hoody projects proxy default --project $PROJECT_ID --default deny --if-match file:v<N>
PATCH Configure multi-tier team access
/api/v1/projects/{project_id}/proxy/permissions
Click "Run" to execute the request

The three groups resolve to:

  • Ops team (203.0.113.0/24): every program
  • Developers (198.51.100.0/24): terminal, files, and HTTP; no SSH and no display
  • Read-only users (password auth): HTTP only

Permission hierarchy

Section titled “Permission hierarchy”

When both documents exist, the proxy resolves a request like this:

Request arrives at container service URL
        ↓
Check: which permission documents exist?
        ↓
   BOTH    → Merge project and container permissions
             (container values win conflicts)
   ONE     → Use the one that exists
   NEITHER → Default open (anyone with URL can access)

For example, a project restricted to the office IP, with one container opened for public HTTP:

Terminal window
# Project: Restrict all containers to office IP
PATCH /api/v1/projects/{id}/proxy/permissions
{
  "groups": { "office": { "type": "ip", "range": "203.0.113.0/24" } },
  "permissions": { "office": { "terminal": true, "http": [8080] } },
  "default": "deny"
}


# Container: Override one container for public access
PATCH /api/v1/containers/{id}/proxy/permissions
{
  "groups": { "public": { "type": "ip", "range": "0.0.0.0/0" } },
  "permissions": { "public": { "http": [8080] } },
  "default": "deny"
}

With both documents in place:

  • most containers: office-only access (terminal and HTTP)
  • public container: anyone can reach HTTP
  • public container: its own document lists only the public group, and the office grant is not repeated there. Both documents govern a container, so read the project file and the container file together before assuming what a given request resolves to.

Configuration endpoints

Section titled “Configuration endpoints”

Project-level operations

Section titled “Project-level operations”
Terminal window
# Get current config (read the file_version ETag for If-Match)
hoody projects proxy permissions get --project $PROJECT_ID


# Set project permissions. Whole-document `permissions replace` is currently
# unavailable in the CLI; use granular group/permission/default commands or
# the SDK/HTTP example.
hoody projects proxy groups ip set --project $PROJECT_ID \
  --group-name <name> --range 203.0.113.0/24 --if-match file:v<N>
hoody projects proxy groups permissions set --project $PROJECT_ID \
  --group-name <name> --program http --access '[8080]' --if-match file:v<N>


# Delete all permissions (revert to open)
hoody projects proxy permissions delete --project $PROJECT_ID --if-match file:v<N>


# Update default policy only
hoody projects proxy default --project $PROJECT_ID --if-match file:v<N> --default deny


# Enable the proxy. The CLI can only enable via this subcommand:
# --enable-proxy is a required, presence-only boolean flag; there is
# no --no-enable-proxy or --enable-proxy=false form.
hoody projects proxy state --project $PROJECT_ID --if-match file:v<N> --enable-proxy


# To disable the proxy, use the SDK or HTTP directly with enable_proxy: false
# (e.g. client.api.proxyPermissionsProject.updateState(id, { enable_proxy: false }, { ifMatch: 'file:v<N>' }))

Container-level operations

Section titled “Container-level operations”
Terminal window
# Get container config (read the file_version ETag for If-Match)
hoody containers proxy permissions get --container $CONTAINER_ID


# Set container permissions (override project). Whole-document `permissions replace`
# is currently unavailable in the CLI; use the granular CLI commands below, the
# granular SDK example, or the HTTP example for a whole-document replacement.
hoody containers proxy groups ip set -c $CONTAINER_ID \
  --group-name <name> --range 203.0.113.0/24 --if-match file:v<N>
hoody containers proxy groups permissions set -c $CONTAINER_ID \
  --group-name <name> --program http --access '[8080]' --if-match file:v<N>


# Delete container permissions (revert to project-level)
hoody containers proxy permissions delete --container $CONTAINER_ID --if-match file:v<N>


# Update default policy
hoody containers proxy default --container $CONTAINER_ID --if-match file:v<N> --default allow

Group operations

Section titled “Group operations”

Add, update, or remove a single group without replacing the whole document:

Terminal window
# Add JWT group to project
hoody projects proxy groups jwt set --project $PROJECT_ID --group-name api-users \
  --if-match file:v<N> \
  --secret "a-long-random-signing-key-with-32-plus-chars" --algorithm HS256 --sources "header:Authorization"


# Add IP group to project
hoody projects proxy groups ip set --project $PROJECT_ID --group-name office \
  --if-match file:v<N> --range "198.51.100.0/24"


# Remove group entirely
hoody projects proxy groups delete --project $PROJECT_ID --group-name office \
  --if-match file:v<N>

Permission operations

Section titled “Permission operations”

Set or remove a group’s program permissions:

Terminal window
# Set permissions for a group (boolean, all instances)
hoody projects proxy groups permissions set --project $PROJECT_ID --group-name developers \
  --if-match file:v<N> --program terminal --access true


# Set permissions (specific instance)
hoody projects proxy groups permissions set --project $PROJECT_ID --group-name developers \
  --if-match file:v<N> --program display --access 1


# Set permissions (multiple instances)
hoody projects proxy groups permissions set --project $PROJECT_ID --group-name developers \
  --if-match file:v<N> --program terminal --access "[1,2,3]"


# Remove all permissions for a group
hoody projects proxy groups permissions clear --project $PROJECT_ID --group-name developers \
  --if-match file:v<N>


# Remove specific program permission
hoody projects proxy groups permissions delete --project $PROJECT_ID --group-name developers \
  --if-match file:v<N> --program terminal

Operational scenarios

Section titled “Operational scenarios”

Progressive lockdown from dev to production

Section titled “Progressive lockdown from dev to production”

Development phase. No permissions are configured, so anyone holding a URL can reach the container and the team shares URLs directly.

Staging phase. Restrict the whole project to the office IP range:

Terminal window
PATCH /api/v1/projects/{id}/proxy/permissions
{
  "groups": {
    "team": { "type": "ip", "range": "203.0.113.0/24" }
  },
  "permissions": {
    "team": { "terminal": true, "http": [8080], "display": true }
  },
  "default": "deny"
}

Production phase (strict JWT auth):

Terminal window
# Override production container only
PATCH /api/v1/containers/{prod_id}/proxy/permissions
{
  "groups": {
    "customers": {
      "type": "jwt",
      "secret": "a-long-random-signing-key-with-32-plus-chars",
      "algorithm": "HS256",
      "sources": ["header:Authorization"]
    }
  },
  "permissions": {
    "customers": { "http": [8080] }
  },
  "default": "deny"
}

Result:

  • Dev containers: Open (cryptographic URLs)
  • Staging containers: Office IP only
  • Production container: JWT required

Customer support access

Section titled “Customer support access”

Give support team temporary terminal access:

Terminal window
# Add support group to specific container
PATCH /api/v1/containers/{id}/proxy/permissions/groups/support/password
{
  "username": "support",
  "password": "temporary-password-hash",
  "algorithm": "sha256",
  "salt": "salt"
}


# Grant specific access to support team
PATCH /api/v1/containers/{id}/proxy/permissions/permissions/support
{
  "program": "terminal",
  "access": 1                // Only terminal 1
}


PATCH /api/v1/containers/{id}/proxy/permissions/permissions/support
{
  "program": "display",
  "access": 1                // Only display 1
}


PATCH /api/v1/containers/{id}/proxy/permissions/permissions/support
{
  "program": "files",
  "access": true             // All file instances
}

Support can:

  • Access terminal instance 1 only
  • View display instance 1 only
  • Use all file service instances

Instance control prevents accidental access to other terminals/displays used by your team.

After support session: Delete the support group or disable it.

API partners with rate limiting

Section titled “API partners with rate limiting”

Different token tiers for partners:

Terminal window
# Mutating /proxy/permissions requires an If-Match: file:v<N> header (ETag from a prior GET).
PATCH /api/v1/containers/{api_id}/proxy/permissions
{
  "groups": {
    "tier1_partners": {
      "type": "token",
      "value": "partner-abc-tier1",
      "header": "X-Api-Token"
    },
    "tier2_partners": {
      "type": "token",
      "value": "partner-def-tier2",
      "header": "X-Api-Token"
    }
  },
  "permissions": {
    "tier1_partners": {
      "http": [8080],            // All HTTP services
      "files": true           // All file instances
    },
    "tier2_partners": {
      "http": [80, 3000],     // Only HTTP on ports 80 and 3000
      "files": false          // No file access (files is boolean-only)
    }
  },
  "default": "deny"
}

Permission Testing

Section titled “Permission Testing”

Verify Configuration

Section titled “Verify Configuration”

After setting permissions, test each group:

Terminal window
# Get current config
hoody projects proxy permissions get --project $PROJECT_ID


# Test access from your machine (for IP groups)
curl "https://PROJECT_ID-CONTAINER_ID-terminal-1.node-us.containers.hoody.com"


# Test with Basic Auth (for password groups)
curl -u "username:password" \
  "https://PROJECT_ID-CONTAINER_ID-terminal-1.node-us.containers.hoody.com"


# Test with JWT (for JWT groups)
curl -H "Authorization: Bearer eyJhbG..." \
  "https://PROJECT_ID-CONTAINER_ID-http-8080.node-us.containers.hoody.com/api/endpoint"

Debugging access issues

Section titled “Debugging access issues”

If access is denied unexpectedly:

  1. Check group matches:

    Terminal window
    GET /api/v1/projects/{id}/proxy/permissions
    # Verify group exists and credentials/IP match

  2. Check program permissions:

    // Ensure the program is allowed for the group
    "permissions": {
      "yourgroup": {
        "terminal": true  // Must be explicitly true
      }
    }

  3. Check default policy:

    "default": "deny"  // If no group matches, deny

  4. Check container override:

    Terminal window
    GET /api/v1/containers/{id}/proxy/permissions
    # Container config might override project

  5. Check proxy enabled:

    "enable_proxy": true  // Must be true

Security best practices

Section titled “Security best practices”

Start with default deny

Section titled “Start with default deny”
{
  "default": "deny"
}

Why: Explicit allow is more secure than implicit allow. If you add new programs later, they’re denied by default until you explicitly permit them.

Use least privilege

Section titled “Use least privilege”

Grant minimum necessary access:

{
  "permissions": {
    "api_users": {
      "http": [80],           // Only HTTP on port 80 (public API)
      "terminal": false,      // No terminal access
      "files": false,         // No file access
      "display": false,       // No display access
      "exec": false          // No exec access
    }
  }
}

3. Layer Security

Section titled “3. Layer Security”

Combine multiple authentication methods:

{
  "groups": {
    "secure_access": {
      "type": "ip",
      "range": "203.0.113.0/24"  // Matches users from the office network
    },
    "with_jwt": {
      "type": "jwt",
      "secret": "a-long-random-signing-key-with-32-plus-chars",
      "algorithm": "HS256",
      "sources": ["header:Authorization"]  // Matches users with a valid JWT
    }
  }
}

Any matching group grants access. All groups are checked in order. A user from the office network matches secure_access; a user with a valid JWT matches with_jwt. Either path works independently. If you need a single group that requires both IP and a JWT simultaneously, that is not supported natively by the permissions model; use a proxy hook for that logic.

Audit permissions regularly

Section titled “Audit permissions regularly”
Terminal window
# List all project permissions
curl "https://api.hoody.com/api/v1/projects" \
  -H "Authorization: Bearer $HOODY_TOKEN"


# For each project, check permissions
curl "https://api.hoody.com/api/v1/projects/{id}/proxy/permissions" \
  -H "Authorization: Bearer $HOODY_TOKEN"


# Look for:
# - Overly broad IP ranges (0.0.0.0/0)
# - Expired access that should be removed
# - Groups no longer needed

Disabling the proxy

Section titled “Disabling the proxy”

Completely disable proxy for a project/container:

Terminal window
# The CLI cannot disable the proxy: --enable-proxy is a required,
# presence-only boolean flag (there is no --no-enable-proxy or
# --enable-proxy=false form). Use the SDK or HTTP tab with
# enable_proxy: false to disable at project or container level:
#   client.api.proxyPermissionsProject.updateState($PROJECT_ID, { enable_proxy: false }, { ifMatch: 'file:v<N>' })
#   client.api.proxyPermissionsContainer.updateState($CONTAINER_ID, { enable_proxy: false }, { ifMatch: 'file:v<N>' })


# Re-enable
hoody containers proxy state --container $CONTAINER_ID --if-match file:v<N> --enable-proxy

When disabled:

  • enable_proxy: false is a kill-switch, not a bypass. New requests that reach the proxy’s permission layer are denied with 403, because the proxy answers itself instead of forwarding to your service
  • The check runs before authentication groups, permission rules, and the default policy, so no configured rule can re-open access while the switch is off
  • The container keeps running, and access that never traverses the proxy (for example SSH) is unaffected. Established WebSocket and CONNECT tunnels are not torn down, because the gate applies to new connections. Compiled config is cached for a couple of seconds, so a flip is not instantaneous
  • Re-enable to restore group/permission enforcement

Scope, and read this before disabling at project level. The container-level setting wins over the project-level one in both directions: a container document with enable_proxy: true stays reachable even while its project is set to false. This is not a corner case: the API writes enable_proxy: true explicitly whenever a container permissions document is saved, so most containers carry an explicit true. To reliably disable a specific container, set it at container level.

Permission configuration reference

Section titled “Permission configuration reference”

Full configuration structure

Section titled “Full configuration structure”
{
  "project": "string (required, project ID)",
  "container": "string (optional, for container-level only)",
  "groups": {
    "{groupName}": {
      "type": "jwt" | "password" | "ip" | "token" | "hoody-identity",
      // ... type-specific fields
    }
  },
  "permissions": {
    "{groupName}": {
      // Network programs (terminal, ssh, display, http): boolean, a port/instance
      // number, an array of numbers, a port-range string like "8000-8100", or "*"
      "terminal": true | false | number | [number] | "8000-8100" | "*",
      "display": true | false | number | [number] | "8000-8100" | "*",
      "http": [8080] | 8080 | "8000-8100",   // must NAME ports — true, false, and "*" are rejected on write
      // Boolean-only programs (files, exec, services, notifications)
      "files": true | false,
      "exec": true | false,
      "services": true | false,
      "notifications": true | false
    }
  },
  "default": "allow" | "deny",
  "enable_proxy": true | false  // optional, defaults to true
}

enable_proxy is an optional field of the permissions document body (it defaults to true and is persisted in the document’s settings alongside default). To flip it without rewriting the whole document, use the dedicated proxy state/settings endpoint instead (PATCH .../proxy/permissions/state or PATCH .../proxy/settings).

Authentication type fields

Section titled “Authentication type fields”

JWT:

{
  "type": "jwt",
  "secret": "string (required)",
  "algorithm": "HS256 | RS256 | ES256 (required)",
  "sources": ["string"] (required, e.g., ["header:Authorization"]),
  "claims": {} (optional, required JWT claims)
}

Password:

{
  "type": "password",
  "username": "string (required)",
  "password": "string (required, plain or hashed)",
  "algorithm": "sha256 (required — only sha256 is accepted)",
  "salt": "string (required)"
}

IP:

{
  "type": "ip",
  "range": "string (required, IPv4 CIDR)"
}

Token:

{
  "type": "token",
  "value": "string (required, the token to match)",
  "header": "string" | "cookie": "string" | "param": "string"
  // exactly one of header | cookie | param specifying where the token is read from
}

Hoody Identity:

{
  "type": "hoody-identity",
  "audience": "string (required, the claim's aud must equal this exactly)",
  "sources": ["string"] (optional, defaults to ["header:X-Hoody-Identity-Claim"]),
  "allow_types": ["user" | "admin"] (optional, defaults to both),
  "users": ["string"] (optional, allowlist of up to 256 user IDs),
  "max_age_seconds": 86400 (optional, freshness gate on the claim's iat, minimum 300),
  "expose_type": false (optional, also inject X-Hoody-Identity-Type)
}

Details and caveats: Hoody Identity Authentication.

Useful Questions

Section titled “Useful Questions”

Can I use multiple authentication methods for the same group?

Section titled “Can I use multiple authentication methods for the same group?”

No. Each group uses exactly one authentication type (JWT, password, IP, token, or hoody-identity). However, you can create multiple groups with different auth methods and all will be checked. If any group matches, the user gets access with that group’s permissions.

Do container-level permissions merge with project-level permissions?

Section titled “Do container-level permissions merge with project-level permissions?”

Yes. Container-level permissions merge with project-level permissions. Project entries remain effective unless an overlapping container group or permission overrides them; the container default takes precedence when present.

What happens if no permissions are configured at all?

Section titled “What happens if no permissions are configured at all?”

The container is open by default - anyone with the URL can access all services. This is intentional for rapid development and instant collaboration. The cryptographic URL (2^192 combinations) provides security through obscurity.

Can I restrict access to specific HTTP ports?

Section titled “Can I restrict access to specific HTTP ports?”

Yes. Use instance numbers for the http program. For example, "http": [80, 3000] allows only ports 80 and 3000. Each port is treated as an instance.

How do I temporarily disable access to a container?

Section titled “How do I temporarily disable access to a container?”

Use the proxy state endpoint:

Terminal window
PATCH /api/v1/containers/{id}/proxy/permissions/state
{ "enable_proxy": false }

New requests to that container’s proxied service URLs then return 403 until you re-enable it. This is a hard cut, not a bypass: the switch is evaluated before groups, rules, and the default policy. The container keeps running, and access that does not traverse the proxy (for example SSH) still works. Set it at container level, because a project-level false does not override a container whose own document says true.

Can IP authentication work with dynamic IPs?

Section titled “Can IP authentication work with dynamic IPs?”

IP auth requires static IPs or CIDR ranges. For dynamic IPs, use JWT or token authentication instead, or combine IP with a VPN that provides static exit IPs.

What’s the difference between “default”: “allow” and no permissions?

Section titled “What’s the difference between “default”: “allow” and no permissions?”
  • No permissions configured: Open by default, no auth required
  • “default”: “allow”: If groups exist but none match, still allow access
  • “default”: “deny”: If groups exist but none match, deny access

Use "default": "deny" for security when you have authentication groups.

Can I see who accessed my containers?

Section titled “Can I see who accessed my containers?”

Not through the proxy permissions system directly. For access logging, use:

  • Container firewall logs for connection attempts
  • Service-level logging (terminal, exec, etc. all support logging)
  • MITM via hoody-exec to log all HTTP traffic

How do I rotate JWT secrets or tokens?

Section titled “How do I rotate JWT secrets or tokens?”
  1. Add new group with new secret/tokens
  2. Update client applications to use new credentials
  3. Verify new group works
  4. Delete old group: DELETE /api/v1/projects/{id}/proxy/permissions/groups/{oldGroupName}

Can password authentication use bcrypt or argon2?

Section titled “Can password authentication use bcrypt or argon2?”

Currently only SHA256 is supported for password hashing. For stronger auth, use JWT with a proper authentication service.

What’s Next

Section titled “What’s Next”

The proxy now enforces:

  1. Authentication configured - Groups define who can access
  2. Permissions set - Programs define what they can do
  3. Default policy chosen - Deny by default for security

Explore related security:

The three tiers cover the usual progression: a new container is reachable by its unguessable URL, project-level rules give a team consistent access across containers, and container-level rules lock down what reaches production.

Permissions scale from open collaboration to strict access control, all through the same HTTP layer.