Skip to content
Hoody Documentation
Download Page (.md)

Proxy Permissions

Section titled “Proxy Permissions”

The Hoody Proxy enforces authentication and authorization for ALL container services. Configure who can access what, at what level, with complete granularity.

After understanding the proxy architecture and creating aliases, you need to understand how to control access to your container services.

API Endpoints Summary

Section titled “API Endpoints Summary”

Official Technical Reference:

This Foundation page explains permission concepts and configuration strategies. For 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”

Hoody’s permission system is multi-layered:

┌─────────────────────────────────────┐
│  Hoody API Authentication           │  ← User login, API tokens
│  (api.hoody.icu)                    │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│  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:

  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”

1. Groups (WHO Can Access)

Section titled “1. 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

Example:

{
  "groups": {
    "developers": {
      "type": "ip",
      "range": "203.0.113.0/24"
    },
    "customers": {
      "type": "jwt",
      "secret": "your-jwt-secret",
      "sources": ["header:Authorization"]
    },
    "admin": {
      "type": "password",
      "username": "admin",
      "password": "hashed-password",
      "salt": "unique-salt"
    }
  }
}

2. Permissions (WHAT They Can Access)

Section titled “2. Permissions (WHAT They Can Access)”

Permissions map groups to programs with flexible instance control.

Each group gets specific access to container programs using:

  • true - Allow ALL instances
  • false - Deny ALL instances
  • number - Allow ONLY this instance (e.g., 1 allows instance 1)
  • array - Allow SPECIFIC instances (e.g., [1, 2] allows instances 1 and 2)
{
  "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": true          // Allow all HTTP services
    },
    "customers": {
      "http": true,          // Allow all HTTP services
      "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": true,         // Full access to HTTP
      "ssh": true           // SSH access
    }
  }
}

3. Default Policy (Fallback)

Section titled “3. Default Policy (Fallback)”

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)

4. Hierarchy (Project vs Container)

Section titled “4. 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 configured: Container-level takes precedence.

Default State: Open by Cryptographic URL

Section titled “Default State: Open by Cryptographic URL”

By default, containers have NO proxy permissions configured.

This means:

  • Anyone with the URL can access all services
  • No authentication required
  • No group matching
  • Pure “security by unguessable URL”

The URL contains:

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

2^96 × 2^96 = 2^192 possible combinations for project+container pair.

Practically unguessable. Share URL = grant access — but anyone the URL reaches (pasted into Slack, captured in a screenshot, logged by a referer header, cached by a browser extension) can hit the container directly. Unguessability prevents blind discovery; it does not contain leaks or replace access control.

This enables:

  • ✅ Instant collaboration (just share URL)
  • ✅ Zero configuration (works immediately)
  • ✅ Multiplayer by default (anyone with URL can join)

When you need real access control: Add proxy permissions — don’t rely on URL secrecy for anything sensitive, and never paste container URLs into public channels, public dashboards, or untrusted third-party tools.

Configuring Permissions

Section titled “Configuring Permissions”

Project-Level Permissions

Section titled “Project-Level Permissions”

Apply authentication to ALL containers in a project:

Terminal window
# Set project-level proxy permissions (IP-restricted team access)
# The If-Match ETag (file:v<N>) comes from a prior `permissions get`.
hoody projects proxy permissions replace --project $PROJECT_ID \
  --if-match file:v<N> \
  --groups team='{"type": "ip", "range": "203.0.113.0/24"}' \
  --permissions team='{"terminal": [1,2], "files": true, "display": 1, "http": true}' \
  --default deny
PATCH Set project-level proxy permissions
/api/v1/projects/{project_id}/proxy/permissions
Click "Run" to execute the request

Now ALL containers in this project:

  • Require IP from 203.0.113.0/24 range
  • Grant access to terminal, files, display, http
  • Deny all other access

Container-Level Permissions

Section titled “Container-Level Permissions”

Override project settings for specific container:

Terminal window
# Override permissions for a specific container (public HTTP only)
# The If-Match ETag (file:v<N>) comes from a prior `permissions get`.
hoody containers proxy permissions replace --container $CONTAINER_ID \
  --if-match file:v<N> \
  --groups public='{"type": "ip", "range": "0.0.0.0/0"}' \
  --permissions public='{"http": true, "terminal": false, "files": false}' \
  --default deny
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)
  • Only HTTP services allowed
  • Terminal and files completely denied
  • Overrides project-level restrictions

Use case: Public demo container in an otherwise private project.

Authentication Groups

Section titled “Authentication Groups”

Groups define HOW users authenticate.

JWT Authentication

Section titled “JWT Authentication”

Validate JSON Web Tokens:

{
  "groups": {
    "authenticated_users": {
      "type": "jwt",
      "secret": "your-jwt-signing-secret",
      "algorithm": "HS256",
      "sources": ["header:Authorization", "cookie:auth_token"],
      "claims": {
        "iss": "mycompany.com",
        "aud": "production-api"
      }
    }
  }
}

Parameters:

  • secret - JWT signing key (required)
  • 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 sources examples:

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

Use case: Your application issues JWTs to users, Hoody validates them at the proxy level.

Password Authentication

Section titled “Password Authentication”

HTTP Basic Auth with username/password:

{
  "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

Browser behavior: Browser will show HTTP Basic Auth prompt automatically.

Why Password Auth is Underrated:

While it’s an old protocol, password authentication is remarkably portable:

  • Works everywhere - No JWT libraries needed, no token management
  • Browser native - Built-in auth prompts on all browsers
  • Zero dependencies - Just username + password, works on any HTTP client
  • Perfect for humans - Simple, intuitive, memorable credentials
  • URL embeddable - https://user:pass@domain.com works in most contexts
  • Emergency access - When OAuth is down, password auth still works
  • Low complexity - No token expiration, no refresh flows, no claims validation

Use cases:

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

IP-Based Authentication

Section titled “IP-Based Authentication”

Allow/deny 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 single IP)

Use case: Restrict to office network, VPN, known IPs.

Note: The proxy sees real client IPs (not proxy IPs) thanks to Hoody’s netfilter hooks, so IP-based auth works perfectly.

Token Authentication

Section titled “Token Authentication”

Validate 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 case: Distribute tokens to API consumers, partners, integrations.

Authentication Without Headers (hoody-curl Workaround)

Section titled “Authentication Without Headers (hoody-curl Workaround)”

Problem: Some environments can’t send custom headers:

  • Browser bookmarks (just URLs)
  • QR codes (GET-only)
  • Email links (no header control)
  • Restricted platforms (iOS Shortcuts, some automation tools)

Solution: Use hoody-curl to transform authenticated requests into simple GET URLs.

How it works:

Terminal window
# Requires ability to send Authorization header
curl "https://67e89abc...890abc-terminal-1.node-us.containers.hoody.icu/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

Practical example - Bookmark to execute deployment:

// Create a bookmark URL that deploys your app
const curlService = "https://67e89abc...890abc-curl-1.node-us.containers.hoody.icu";
const targetService = "https://67e89abc...890abc-exec-1.node-us.containers.hoody.icu/api/deploy";
const authToken = "your-jwt-token";


const bookmarkUrl = `${curlService}/proxy?` + new URLSearchParams({
  url: targetService,
  method: 'POST',
  auth: `Bearer ${authToken}`,
  body: JSON.stringify({ environment: 'production' })
});


// Save as bookmark: "🚀 Deploy Production"
// Click bookmark → Deployment triggered
// No terminal needed, no curl command, just a click

Use cases:

  • Emergency deployments - Bookmark for instant deploy
  • Mobile access - QR code to trigger workflows
  • Email notifications - “Click here to approve” links
  • Restricted automation - iOS Shortcuts, Zapier webhooks
  • Simple sharing - Send URL instead of curl command

See: Hoody cURL → for complete documentation on wrapping HTTP requests.

Program-Specific Permissions

Section titled “Program-Specific Permissions”

Each program supports flexible instance control:

Permission Value Types

Section titled “Permission Value Types”

Four types of access control:

{
  "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”

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) instances
  • files - Hoody Files service
  • exec - Hoody Exec script execution
  • sqlite - Hoody SQLite database instances
  • browser - Hoody Browser automation instances
  • agent - Hoody Agent AI instances
  • Plus: code, curl, daemon, notifications

Why Instance-Level Control Matters

Section titled “Why Instance-Level Control Matters”

Real scenario: Container with 5 terminal instances for different teams:

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

Each team isolated to specific instances while sharing the same container.

Complete Configuration Examples

Section titled “Complete Configuration Examples”

Example 1: Development Team Access

Section titled “Example 1: Development Team Access”

Internal team, broad access, IP-restricted:

Terminal window
# Configure IP-restricted developer access for entire project
# The If-Match ETag (file:v<N>) comes from a prior `permissions get`.
hoody projects proxy permissions replace --project $PROJECT_ID \
  --if-match file:v<N> \
  --groups developers='{"type": "ip", "range": "203.0.113.0/24"}' \
  --permissions developers='{"terminal": true, "display": true, "files": true, "http": true, "ssh": true}' \
  --default deny
PATCH Configure IP-restricted developer access
/api/v1/projects/{project_id}/proxy/permissions
Click "Run" to execute the request

Result:

  • Developers from office network (203.0.113.0/24) get full access
  • Everyone else denied
  • Applies to all containers in project

Example 2: Public API with Private Admin

Section titled “Example 2: Public API with Private Admin”

Container-level override for public API:

Terminal window
# Public API (JWT for customers) + private admin group (password)
# The If-Match ETag (file:v<N>) comes from a prior `permissions get`.
hoody containers proxy permissions replace --container $CONTAINER_ID \
  --if-match file:v<N> \
  --groups customers='{"type": "jwt", "secret": "customer-jwt-secret", "algorithm": "HS256", "sources": ["header:Authorization"]}' \
  --groups admin='{"type": "password", "username": "admin", "password": "hashed-admin-password", "algorithm": "sha256", "salt": "unique-salt"}' \
  --permissions customers='{"http": true}' \
  --permissions admin='{"terminal": true, "display": true, "files": true, "http": true, "ssh": true}' \
  --default deny
PATCH Configure public API with private admin access
/api/v1/containers/{container_id}/proxy/permissions
Click "Run" to execute the request

Result:

  • Customers with valid JWT: HTTP API + read-only files
  • Admin with password: Full access (terminal, display, all files)
  • Everyone else: Denied

Example 3: Multi-Tier Access

Section titled “Example 3: Multi-Tier Access”

Different access levels for different teams:

Terminal window
# Multi-tier: ops (full), developers (partial), readonly (HTTP only)
# The If-Match ETag (file:v<N>) comes from a prior `permissions get`.
hoody projects proxy permissions replace --project $PROJECT_ID \
  --if-match file:v<N> \
  --groups ops_team='{"type": "ip", "range": "203.0.113.0/24"}' \
  --groups developers='{"type": "ip", "range": "198.51.100.0/24"}' \
  --groups readonly_users='{"type": "password", "username": "viewer", "password": "hashed-pass", "salt": "salt"}' \
  --permissions ops_team='{"terminal": true, "display": true, "files": true, "http": true, "ssh": true}' \
  --permissions developers='{"terminal": true, "files": true, "http": true, "ssh": false}' \
  --permissions readonly_users='{"http": true, "terminal": false, "display": false, "files": false}' \
  --default deny
PATCH Configure multi-tier team access
/api/v1/projects/{project_id}/proxy/permissions
Click "Run" to execute the request

Access levels:

  • Ops team (203.0.113.0/24): Full access to all programs
  • Developers (198.51.100.0/24): Terminal, files, HTTP (no SSH, no display)
  • Read-only users (password auth): Only HTTP access

Permission Hierarchy

Section titled “Permission Hierarchy”

When both project and container permissions exist:

Request arrives at container service URL
        ↓
Check: Does container have permissions configured?
        ↓
   YES → Use container permissions
   NO  → Use project permissions (if configured)
        ↓
If no permissions at either level:
   → Default open (anyone with URL can access)

Example scenario:

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": true } },
  "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": true } },
  "default": "deny"
}

Result:

  • Most containers: Office-only access (terminal + HTTP)
  • Public container: Anyone can access HTTP
  • Public container: Office can still access terminal (inherits project? No—container config replaces entirely)

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
hoody projects proxy permissions replace --project $PROJECT_ID \
  --if-match file:v<N> \
  --groups <name>='{...}' --permissions <name>='{...}' --default deny


# 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/disable proxy entirely (omit --enable-proxy to disable)
hoody projects proxy state --project $PROJECT_ID --if-match 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)
hoody containers proxy permissions replace --container $CONTAINER_ID \
  --if-match file:v<N> \
  --groups <name>='{...}' --permissions <name>='{...}' --default deny


# 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 Management

Section titled “Group Management”

Add/update/remove specific groups without replacing entire config:

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 "jwt-secret" --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 Management

Section titled “Permission Management”

Manage program permissions for groups:

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

Real-World Scenarios

Section titled “Real-World Scenarios”

Scenario 1: Open Development → Locked Production

Section titled “Scenario 1: Open Development → Locked Production”

Development phase (use cryptographic URLs):

No permissions configured
→ Anyone with URL can access
→ Share URLs with team for instant collaboration
→ Perfect for rapid iteration

Staging phase (add basic restrictions):

Terminal window
PATCH /api/v1/projects/{id}/proxy/permissions
{
  "groups": {
    "team": { "type": "ip", "range": "203.0.113.0/24" }
  },
  "permissions": {
    "team": { "terminal": true, "http": true, "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": "production-jwt-secret",
      "algorithm": "HS256",
      "sources": ["header:Authorization"]
    }
  },
  "permissions": {
    "customers": { "http": true }
  },
  "default": "deny"
}

Result:

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

Scenario 2: Customer Support Access

Section titled “Scenario 2: 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",
  "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.

Scenario 3: API Partners with Rate Limiting

Section titled “Scenario 3: 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": true,            // All HTTP services
      "files": true           // All file instances
    },
    "tier2_partners": {
      "http": [80, 3000],     // Only HTTP on ports 80 and 3000
      "files": 1              // Only file instance 1
    }
  },
  "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://67e89abc...890abc-terminal-1.node-us.containers.hoody.icu"


# Test with Basic Auth (for password groups)
curl -u "username:password" \
  "https://67e89abc...890abc-terminal-1.node-us.containers.hoody.icu"


# Test with JWT (for JWT groups)
curl -H "Authorization: Bearer eyJhbG..." \
  "https://67e89abc...890abc-http-8080.node-us.containers.hoody.icu/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”

1. Start with Default Deny

Section titled “1. 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.

2. Use Least Privilege

Section titled “2. 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"  // Must be from office
    },
    "with_jwt": {
      "type": "jwt",
      "secret": "jwt-secret",
      "sources": ["header:Authorization"]  // AND must have valid JWT
    }
  }
}

Users must satisfy BOTH: Be from office IP AND provide valid JWT.

4. Audit Permissions Regularly

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


# For each project, check permissions
curl "https://api.hoody.icu/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
# Disable at project level (all containers unreachable; omit --enable-proxy to disable)
hoody projects proxy state --project $PROJECT_ID --if-match file:v<N>


# Disable at container level (this container unreachable)
hoody containers proxy state --container $CONTAINER_ID --if-match file:v<N>


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

When disabled:

  • All service URLs return 503 Service Unavailable
  • Container still running (just not accessible via proxy)
  • Useful for maintenance or security lockdown

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",
      // ... type-specific fields
    }
  },
  "permissions": {
    "{groupName}": {
      "terminal": true | false | number | [number],
      "display": true | false | number | [number],
      "files": true | false | number | [number],
      "http": true | false | number | [number],
      "ssh": true | false | number | [number],
      "exec": true | false | number | [number],
      "sqlite": true | false | number | [number],
      "browser": true | false | number | [number],
      "agent": true | false | number | [number]
    }
  },
  "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" (optional)",
  "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
}

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, or token). 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?”

No, they replace entirely. If you set container-level permissions, the project-level config is completely ignored for that container. If you want to keep some project settings, you must re-include them in the container configuration.

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 }

All service URLs will return 503 until you re-enable.

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”

Your proxy is now secure:

  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:

Default: Open by cryptographic URL.
Project-level: Consistent team access.
Container-level: Production security.
Complete control over who accesses what.

From zero-config collaboration to enterprise-grade security—all through HTTP.