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

CLI

# Add an ingress rule
hoody firewall ingress create -c $CONTAINER_ID --action allow --protocol tcp --description "Allow SSH from office" --destination-port 22 --source 203.0.113.50/32

SDK

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',
});

HTTP

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 TCP Traffic

CLI

# Add an egress rule
hoody firewall egress create -c $CONTAINER_ID --action drop --protocol tcp --description "Block all TCP egress" --destination 0.0.0.0/0 --destination-port 1-65535

SDK

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

HTTP

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",
    "destination_port": "1-65535"
  }'

Use case: Switch a container’s outbound traffic off entirely.

Allow Specific Service

Allow only HTTPS to specific API:

CLI

# Add an egress rule
hoody firewall egress create -c $CONTAINER_ID --action allow --protocol tcp --description "Allow HTTPS to API" --destination-port 443 --destination 198.51.100.0/24

SDK

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',
});

HTTP

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

Single Port

{"destination_port": "80"}

Port Range

{"destination_port": "8000-9000"}

Port List

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

Combined

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

Fetch cURL PowerShell

▶ Run

Response

Click "Run" to execute the request

POST Block SSH from everyone else (broad)

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

Fetch cURL PowerShell

▶ Run

Response

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

Fetch cURL PowerShell

▶ Run

Response

Click "Run" to execute the request

Drop all other attempts:

POST Drop all other PostgreSQL attempts

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

Fetch cURL PowerShell

▶ Run

Response

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

Fetch cURL PowerShell

▶ Run

Response

Click "Run" to execute the request

Allow SSH from office only:

POST Allow SSH from office

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

Fetch cURL PowerShell

▶ Run

Response

Click "Run" to execute the request

Drop other SSH attempts:

POST Drop all other SSH attempts

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

Fetch cURL PowerShell

▶ Run

Response

Click "Run" to execute the request

Fully Offline Container (No Internet)

Block all egress:

POST Block all TCP egress

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

Fetch cURL PowerShell

▶ Run

Response

Click "Run" to execute the request

POST Block all UDP egress

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

Fetch cURL PowerShell

▶ Run

Response

Click "Run" to execute the request

POST Block all ICMP egress

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

Fetch cURL PowerShell

▶ Run

Response

Click "Run" to execute the request

Rules match per protocol, so all three (tcp, udp, icmp4) are required — otherwise ICMP egress stays open under the default-allow policy.

Perfect for agent runs you want kept fully offline until you say otherwise.

Allowlist Only What Your Programs Need

Principle: Give your programs exactly the destinations they need — nothing else gets out.

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

POST Allow HTTPS to your API

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

Fetch cURL PowerShell

▶ Run

Response

Click "Run" to execute the request

Allow DNS:

POST Allow DNS lookups

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

Fetch cURL PowerShell

▶ Run

Response

Click "Run" to execute the request

Block everything else — firewall rules are per-protocol, so a catch-all drop is needed for each of tcp, udp, and icmp4:

POST Block all other TCP traffic

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

Fetch cURL PowerShell

▶ Run

Response

Click "Run" to execute the request

POST Block all other UDP traffic

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

Fetch cURL PowerShell

▶ Run

Response

Click "Run" to execute the request

POST Block all ICMP traffic

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

Fetch cURL PowerShell

▶ Run

Response

Click "Run" to execute the request

Traffic leaves only toward destinations you chose.

---

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.

Use both together for complete control.

See: Proxy Permissions →

---

Managing Rules

List Rules

CLI

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

SDK

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

HTTP

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

Disable Rule (Keep Configuration)

CLI

# Toggle an ingress rule's state to disabled
hoody firewall ingress toggle -c $CONTAINER_ID --state disabled --description "Allow SSH from office"

SDK

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

HTTP

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:

CLI

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

SDK

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

HTTP

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):

CLI

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

SDK

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

HTTP

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

Fetch cURL PowerShell

▶ Run

Response

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

Fetch cURL PowerShell

▶ Run

Response

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

Fetch cURL PowerShell

▶ Run

Response

Click "Run" to execute the request

4. Snapshot Before Major Changes

POST Create snapshot before firewall changes

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

Fetch cURL PowerShell

▶ Run

Response

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 blackholes all outbound TCP from the container — including calls to other containers’ service URLs. 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 /api/v1/containers/{id}/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:

1. List rules: GET /api/v1/containers/{id}/firewall/rules
2. Disable blocking rule: PATCH /api/v1/containers/{id}/firewall/ingress {"state": "disabled", "description": "..."}
3. Add allow rule for your IP: POST /api/v1/containers/{id}/firewall/ingress {"action": "allow", "protocol": "tcp", "description": "Allow my IP", "source": "YOUR_IP/32", "destination_port": "1-65535"}
4. Reset firewall: POST /api/v1/containers/{id}/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

Fetch cURL PowerShell

▶ Run

Response

Click "Run" to execute the request

POST Allow DNS for package resolution

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

Fetch cURL PowerShell

▶ Run

Response

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.