Firewall

Host-enforced network security for your containers. Control exactly what can connect in (ingress) and out (egress) at the packet level.

API Endpoints Summary

Complete endpoint documentation:

GET /api/v1/containers/{id}/firewall/rules - List all firewall rules
POST /api/v1/containers/{id}/firewall/ingress - Add ingress rule
POST /api/v1/containers/{id}/firewall/egress - Add egress rule
DELETE /api/v1/containers/{id}/firewall/ingress - Remove ingress rule(s)
DELETE /api/v1/containers/{id}/firewall/egress - Remove egress rule(s)
PATCH /api/v1/containers/{id}/firewall/ingress - Toggle ingress rule state
PATCH /api/v1/containers/{id}/firewall/egress - Toggle egress rule state
POST /api/v1/containers/{id}/firewall/reset - Reset firewall

Key Concepts

Host-level enforcement: Firewall runs on YOUR server’s host kernel—completely outside containers.

What this means:

✅ Containers cannot bypass firewall rules
✅ Containers cannot modify their own firewall
✅ Rules survive container restarts/snapshots

Two directions:

Ingress - Traffic coming INTO container (who can connect)
Egress - Traffic going OUT FROM container (what container can reach)

Three actions:

allow - Permit matching traffic
reject - Block and notify (ICMP/TCP unreachable)
drop - Silently ignore (appears offline to scanners)

Three protocols: tcp, udp, icmp4

Quick Examples

Allow SSH from Specific IP

# Allow SSH from office IP
hoody firewall ingress create --container $CONTAINER_ID \
  --action allow --protocol tcp \
  --destination-port 22 --source "203.0.113.50/32" \
  --description "Allow SSH from office"

await client.api.firewall.addIngressRule(CONTAINER_ID, {
  action: 'allow',
  protocol: 'tcp',
  description: 'Allow SSH from office',
  destination_port: '22',
  source: '203.0.113.50/32',
});

curl -X POST "https://api.hoody.icu/api/v1/containers/$CONTAINER_ID/firewall/ingress" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "allow",
    "protocol": "tcp",
    "description": "Allow SSH from office",
    "destination_port": "22",
    "source": "203.0.113.50/32"
  }'

Block All Outbound Internet

# Block all TCP egress traffic
hoody firewall egress create --container $CONTAINER_ID \
  --action drop --protocol tcp \
  --destination "0.0.0.0/0" \
  --description "Block all TCP egress"

await client.api.firewall.addEgressRule(CONTAINER_ID, {
  action: 'drop',
  protocol: 'tcp',
  description: 'Block all TCP egress',
  destination: '0.0.0.0/0',
});

curl -X POST "https://api.hoody.icu/api/v1/containers/$CONTAINER_ID/firewall/egress" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "drop",
    "protocol": "tcp",
    "description": "Block all TCP egress",
    "destination": "0.0.0.0/0"
  }'

Use case: Run untrusted code in complete isolation.

Allow Specific Service

Allow only HTTPS to specific API:

# Allow HTTPS to specific API range
hoody firewall egress create --container $CONTAINER_ID \
  --action allow --protocol tcp \
  --destination-port 443 --destination "198.51.100.0/24" \
  --description "Allow HTTPS to API"

await client.api.firewall.addEgressRule(CONTAINER_ID, {
  action: 'allow',
  protocol: 'tcp',
  description: 'Allow HTTPS to API',
  destination_port: '443',
  destination: '198.51.100.0/24',
});

curl -X POST "https://api.hoody.icu/api/v1/containers/$CONTAINER_ID/firewall/egress" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "allow",
    "protocol": "tcp",
    "description": "Allow HTTPS to API",
    "destination_port": "443",
    "destination": "198.51.100.0/24"
  }'

Port Specification

{"destination_port": "80"}

{"destination_port": "8000-9000"}

{"destination_port": "80,443,8080"}

{"destination_port": "22,80-90,443,8000-9000"}

CIDR notation:

/32 - Single IP (203.0.113.50/32)
/24 - 256 IPs (203.0.113.0/24)
/0 - All IPs (0.0.0.0/0)

Rule Evaluation Order

First match wins. Put specific rules before broad rules:

✅ Correct: Specific first

POST Allow SSH from office (specific)

/api/v1/containers/{container_id}/firewall/ingress

Click "Run" to execute the request

POST Block SSH from everyone else (broad)

/api/v1/containers/{container_id}/firewall/ingress

Click "Run" to execute the request

❌ Wrong: Broad first (specific never evaluated) - If you create the drop rule first, the allow rule will never be reached.

Common Patterns

Database Container (Restrict Access)

Allow PostgreSQL from backend only:

POST Allow PostgreSQL from backend IP

/api/v1/containers/{container_id}/firewall/ingress

Click "Run" to execute the request

Drop all other attempts:

POST Drop all other PostgreSQL attempts

/api/v1/containers/{container_id}/firewall/ingress

Click "Run" to execute the request

Web Server (Public + Restricted SSH)

Allow HTTP/HTTPS from anywhere:

POST Allow HTTP/HTTPS from anywhere

/api/v1/containers/{container_id}/firewall/ingress

Click "Run" to execute the request

Allow SSH from office only:

POST Allow SSH from office

/api/v1/containers/{container_id}/firewall/ingress

Click "Run" to execute the request

Drop other SSH attempts:

POST Drop all other SSH attempts

/api/v1/containers/{container_id}/firewall/ingress

Click "Run" to execute the request

Isolated Sandbox (No Internet)

Block all egress:

POST Block all TCP egress

/api/v1/containers/{container_id}/firewall/egress

Click "Run" to execute the request

POST Block all UDP egress

/api/v1/containers/{container_id}/firewall/egress

Click "Run" to execute the request

Perfect for AI-generated code execution.

Malware Defense (Allowlist Required Services)

Security principle: Malware ALWAYS needs to communicate (command-and-control, data exfiltration). Block everything except what your programs legitimately need.

Allow only what your app needs (e.g., your API):

POST Allow HTTPS to your API

/api/v1/containers/{container_id}/firewall/egress

Click "Run" to execute the request

Allow DNS:

POST Allow DNS lookups

/api/v1/containers/{container_id}/firewall/egress

Click "Run" to execute the request

Block everything else:

POST Block all other TCP traffic

/api/v1/containers/{container_id}/firewall/egress

Click "Run" to execute the request

Even if container is compromised, malware cannot phone home.

Firewall vs Hoody Proxy

Two separate security layers:

Layer	Controls	Use For
Firewall	Network packets (TCP/UDP/ICMP)	Port restrictions, IP filtering
Proxy Permissions	HTTP service access	User auth, service-level control

Firewall controls network traffic. Proxy Permissions controls HTTP service access.

Layer both for defense-in-depth.

See: Proxy Permissions →

Managing Rules

List Rules

# List all firewall rules for a container
hoody firewall list --container $CONTAINER_ID

const rules = await client.api.firewall.list(CONTAINER_ID);
console.log(rules.data);

curl "https://api.hoody.icu/api/v1/containers/$CONTAINER_ID/firewall/rules" \
  -H "Authorization: Bearer $TOKEN"

Disable Rule (Keep Configuration)

# Disable an ingress rule by description
hoody firewall ingress toggle --container $CONTAINER_ID \
  --state disabled --description "Allow SSH from office"

await client.api.firewall.toggleIngressRule(CONTAINER_ID, {
  state: 'disabled',
  description: 'Allow SSH from office',
});

curl -X PATCH "https://api.hoody.icu/api/v1/containers/$CONTAINER_ID/firewall/ingress" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"state": "disabled", "description": "Allow SSH from office"}'

Remove Rules

Remove specific rule:

# Remove a specific ingress rule
hoody firewall ingress delete --container $CONTAINER_ID \
  --description "Allow SSH from office"

await client.api.firewall.removeIngressRule(CONTAINER_ID, {
  description: 'Allow SSH from office',
});

curl -X DELETE "https://api.hoody.icu/api/v1/containers/$CONTAINER_ID/firewall/ingress" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description": "Allow SSH from office"}'

Reset completely (remove ALL rules):

# Reset firewall to default (removes ALL rules)
hoody firewall reset --container $CONTAINER_ID

await client.api.firewall.reset(CONTAINER_ID);

curl -X POST "https://api.hoody.icu/api/v1/containers/$CONTAINER_ID/firewall/reset" \
  -H "Authorization: Bearer $TOKEN"

Best Practices

1. Specific Rules Before Broad Rules

Create specific allow rule first:

POST Allow from specific source (create first)

/api/v1/containers/{container_id}/firewall/ingress

Click "Run" to execute the request

Then create the broad drop rule:

POST Drop from all other sources (create second)

/api/v1/containers/{container_id}/firewall/ingress

Click "Run" to execute the request

2. Use Drop for Public Services

✅ "action": "drop" = stealth (appears offline to scanners)
⚠️ "action": "reject" = reveals existence (sends ICMP unreachable)

3. Allow DNS for Egress Restrictions

When blocking egress, remember to allow DNS:

POST Allow DNS for egress

/api/v1/containers/{container_id}/firewall/egress

Click "Run" to execute the request

4. Snapshot Before Major Changes

POST Create snapshot before firewall changes

/api/v1/containers/{container_id}/snapshots

Click "Run" to execute the request

See: Snapshots →

Useful Questions

Does the firewall apply to traffic through the Hoody Proxy?

No. Hoody Proxy traffic (service URLs like https://{project}-{container}-terminal-1.{server}.containers.hoody.icu) bypasses the firewall. Use Proxy Permissions for HTTP service access control.

Can containers modify their own firewall rules?

No. Firewall rules are host-enforced and only modifiable via the Hoody API. Containers cannot see or change them.

What’s the difference between firewall and Network Configuration’s “block” mode?

Network Config block mode prevents ALL outbound traffic. Firewall egress rules provide granular control—allow some, block others.

Do firewall rules persist through restarts?

Yes. Rules are stored at host level and survive container restarts, pauses, and snapshots.

What if I lock myself out with firewall rules?

Access via hoody-terminal URL (HTTP bypasses firewall) or use API to add an allow rule or reset: POST /firewall/reset

Can firewall rules use domain names?

No. Firewall operates at IP layer—use CIDR notation only.

Troubleshooting

Cannot Connect After Adding Rules

Solutions:

List rules: GET /firewall/rules
Disable blocking rule: PATCH /firewall/ingress {"state": "disabled", "description": "..."}
Add allow rule for your IP: POST /firewall/ingress {"action": "allow", "source": "YOUR_IP/32"}
Reset firewall: POST /firewall/reset (removes ALL rules)

Rules Not Working

Check:

Rule state: Must be "state": "enabled"
Rule order: Specific before broad
Protocol: TCP rule won’t block UDP traffic

Egress Blocks Package Installation

Allow package repositories:

POST Allow HTTPS for package downloads

/api/v1/containers/{container_id}/firewall/egress

Click "Run" to execute the request

POST Allow DNS for package resolution

/api/v1/containers/{container_id}/firewall/egress

Click "Run" to execute the request

What’s Next

Complete networking setup:

Network Configuration → - Route traffic through proxies/VPNs
SSH Access → - Secure shell and SFTP
IPv4 Management → - Dedicated IPs (coming soon)

Related security:

Proxy Permissions → - Application-level access control
Security Principles → - Hoody’s security philosophy

Understanding gained:

✅ Firewall enforced at host level (tamper-proof)
✅ Ingress controls inbound, egress controls outbound
✅ Rules evaluated in order (first match wins)
✅ Three actions: allow, reject, drop
✅ Independent from Hoody Proxy Permissions

Host-level enforcement. Container-level control.
Tamper-proof security that containers cannot bypass.

Network security starts at the packet level.