Container Firewall

The Container Firewall API controls the ingress and egress rules attached to a container. Use these endpoints to inspect the live rule set, append new rules, toggle rules on and off without deleting them, remove specific or bulk rules, or fully reset the firewall back to an open state.

Note

Every new rule defaults to state: "enabled". Each container enforces a combined rule-count and serialized-size budget (max_rules, max_bytes on the list endpoint); additions that would exceed those limits fail closed with CONTAINER_FIREWALL_RULE_LIMIT or CONTAINER_FIREWALL_BYTES_LIMIT.

Rule Listing

GET /api/v1/containers/{id}/firewall/rules

Get all ingress and egress firewall rules for a container.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID

Response

200

{
  "statusCode": 200,
  "message": "Firewall rules retrieved successfully",
  "data": {
    "ingress": [
      {
        "action": "allow",
        "protocol": "tcp",
        "description": "Allow HTTPS traffic",
        "destination_port": "443",
        "source": "0.0.0.0/0",
        "state": "enabled",
        "direction": "ingress"
      },
      {
        "action": "allow",
        "protocol": "icmp4",
        "description": "Allow ping from any source",
        "source": "0.0.0.0/0",
        "state": "enabled",
        "icmp_type": "8",
        "icmp_code": "0",
        "direction": "ingress"
      }
    ],
    "egress": [
      {
        "action": "allow",
        "protocol": "tcp",
        "description": "Allow outbound HTTPS",
        "destination_port": "443",
        "destination": "0.0.0.0/0",
        "state": "enabled",
        "direction": "egress"
      },
      {
        "action": "drop",
        "protocol": "tcp",
        "description": "Block outbound SMTP",
        "destination_port": "25",
        "destination": "0.0.0.0/0",
        "state": "enabled",
        "direction": "egress"
      }
    ],
    "rule_count": 4,
    "byte_count": 412,
    "max_rules": 500,
    "max_bytes": 262144
  }
}

401

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

Error Code	Title	Description	Resolution
MISSING_TOKEN	Authentication token missing	No authentication token was provided in the request	Include a valid JWT token in the Authorization header as Bearer <token>
INVALID_TOKEN	Invalid authentication token	The provided authentication token is malformed or invalid	Obtain a new token by logging in again or using a valid auth token

403

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

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

404

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

Error Code	Title	Description	Resolution
CONTAINER_NOT_FOUND	Container not found	The requested container does not exist or you do not have permission to access it.	Verify the container ID is correct and that you have access to the project it belongs to.

SDK Usage

cURL

curl -X GET https://api.hoody.com/api/v1/containers/{id}/firewall/rules \
  -H "Authorization: Bearer <token>"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

const { data } = await client.api.firewall.list({ id: '{id}' });
console.log(data.ingress, data.egress);

Ingress Rules

POST /api/v1/containers/{id}/firewall/ingress

Add a new ingress (inbound) firewall rule to a container. Use this endpoint to control which traffic can reach your container. All rules default to state: "enabled" if not specified.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID

Request Body

Field	Type	Required	Description
action	string	Yes	Action to take: allow (permit), reject (deny with response), drop (deny silently)
protocol	string	Yes	Network protocol: tcp, udp, or icmp4
description	string	Yes	Human-readable rule description (max 255 chars)
destination_port	string	No	Port number, range (e.g. 80-90), or comma-separated list (e.g. 80,443). Required for TCP/UDP.
source	string	No	Source IPv4 address or CIDR range. Use 0.0.0.0/0 for any source.
source_port	string	No	Source port filter (rarely used)
state	string	No	Rule state: enabled or disabled (defaults to enabled)
icmp_type	string	No	ICMP type number (e.g. 8 for echo request/ping)
icmp_code	string	No	ICMP code number

{
  "action": "allow",
  "protocol": "tcp",
  "description": "Allow HTTPS",
  "destination_port": "443",
  "source": "0.0.0.0/0"
}

Response

200

{
  "statusCode": 200,
  "message": "Rule already exists",
  "data": {}
}

201

{
  "statusCode": 201,
  "message": "Ingress rule added successfully",
  "data": {}
}

400

{
  "statusCode": 400,
  "error": "CONTAINER_FIREWALL_RULE_LIMIT",
  "message": "This container has reached its firewall rule limit.",
  "data": {
    "field": "container_firewall_rule_limit",
    "container_id": "507f1f77bcf86cd799439011",
    "server_id": "507f1f77bcf86cd799439022",
    "current_count": 500,
    "limit": 500
  }
}

Error Code	Title	Description	Resolution
CONTAINER_FIREWALL_RULE_LIMIT	Container firewall rule limit reached	The container already holds the maximum number of firewall rules allowed (ingress and egress counted together). The applicable limit is returned as max_rules when listing firewall rules.	Remove an existing firewall rule on this container before adding a new one.
CONTAINER_FIREWALL_BYTES_LIMIT	Container firewall rule size limit reached	The container’s firewall rules have reached their total serialized size budget. This can be hit below the rule-count limit when individual rules are large (long descriptions or address lists). The applicable limit is returned as max_bytes when listing firewall rules.	Remove rules, or shorten descriptions and address lists, before adding a new rule.

404

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

503

{
  "statusCode": 503,
  "error": "FIREWALL_INVENTORY_UNAVAILABLE",
  "message": "Unable to verify this container's firewall rules. No changes were made.",
  "data": {
    "field": "firewall_inventory",
    "container_id": "507f1f77bcf86cd799439011"
  }
}

Error Code	Title	Description	Resolution
FIREWALL_INVENTORY_UNAVAILABLE	Firewall inventory unavailable	The container’s live firewall rule list could not be established (host unreachable, or a malformed response), so the rule limit could not be evaluated. The request fails closed: no rule was added.	Retry shortly. If it persists, the hosting server may be unreachable.

SDK Usage

cURL

curl -X POST https://api.hoody.com/api/v1/containers/{id}/firewall/ingress \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "allow",
    "protocol": "tcp",
    "description": "Allow HTTPS",
    "destination_port": "443",
    "source": "0.0.0.0/0"
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.firewall.addIngressRule('{id}', {
  action: 'allow',
  protocol: 'tcp',
  description: 'Allow HTTPS',
  destination_port: '443',
  source: '0.0.0.0/0'
});

PATCH /api/v1/containers/{id}/firewall/ingress

Enable or disable an ingress (inbound) firewall rule without deleting it. Provide filters to identify which rule to toggle. Useful for temporarily disabling rules.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID

Request Body

Field	Type	Required	Description
state	string	Yes	New state for the rule: enabled or disabled
action	string	No	Action for matching traffic: allow, reject, or drop
protocol	string	No	Protocol type: tcp, udp, or icmp4
destination_port	string	No	Destination port, range (e.g. 80-90), or list (e.g. 80,443)
source_port	string	No	Source port, range, or list
source	string	No	Source IPv4 address or CIDR range
description	string	No	Rule description (max 255 chars)
icmp_type	string	No	ICMP type number
icmp_code	string	No	ICMP code number

{
  "state": "disabled",
  "protocol": "tcp",
  "destination_port": "443"
}

Response

200

{
  "statusCode": 200,
  "message": "Ingress rule state toggled successfully",
  "data": {
    "direction": "ingress",
    "new_state": "disabled",
    "updated": {
      "action": "allow",
      "protocol": "tcp",
      "description": "Allow HTTPS traffic",
      "destination_port": "443",
      "source": "0.0.0.0/0",
      "state": "disabled"
    }
  }
}

404

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

SDK Usage

cURL

curl -X PATCH https://api.hoody.com/api/v1/containers/{id}/firewall/ingress \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "disabled",
    "protocol": "tcp",
    "destination_port": "443"
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.firewall.toggleIngressRule('{id}', {
  state: 'disabled',
  protocol: 'tcp',
  destination_port: '443'
});

DELETE /api/v1/containers/{id}/firewall/ingress

Remove one or more ingress (inbound) firewall rules. Provide filters to match specific rules, or use all: true to remove all ingress rules. Not equivalent to reset — this only deletes rules and leaves the firewall/ACL attached.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID

Request Body

Field	Type	Required	Default	Description
all	boolean	No	—	Remove all matching rules (default: first match only). Set to true with no other filters to remove all ingress rules.
action	string	No	—	Action for matching traffic: allow, reject, or drop
protocol	string	No	—	Protocol type: tcp, udp, or icmp4
destination_port	string	No	—	Destination port, range, or list
source	string	No	—	Source IPv4 address or CIDR range
source_port	string	No	—	Source port, range, or list
description	string	No	—	Rule description
state	string	No	"enabled"	Rule state: enabled or disabled
icmp_type	string	No	—	ICMP type number
icmp_code	string	No	—	ICMP code number

{
  "protocol": "tcp",
  "destination_port": "22",
  "source": "192.168.1.0/24"
}

Response

200

{
  "statusCode": 200,
  "message": "Ingress rule removed successfully",
  "data": {
    "direction": "ingress",
    "removed_count": 1,
    "removed": [
      {
        "action": "allow",
        "protocol": "tcp",
        "description": "Allow SSH from office",
        "destination_port": "22",
        "source": "192.168.1.0/24",
        "state": "enabled"
      }
    ]
  }
}

404

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

SDK Usage

cURL

curl -X DELETE https://api.hoody.com/api/v1/containers/{id}/firewall/ingress \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": "tcp",
    "destination_port": "22",
    "source": "192.168.1.0/24"
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.firewall.removeIngressRule('{id}', {
  protocol: 'tcp',
  destination_port: '22',
  source: '192.168.1.0/24'
});

Egress Rules

POST /api/v1/containers/{id}/firewall/egress

Add a new egress (outbound) firewall rule to a container. Use this endpoint to control which traffic your container can send. All rules default to state: "enabled" if not specified.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID

Request Body

Field	Type	Required	Description
action	string	Yes	Action to take: allow (permit), reject (deny with response), drop (deny silently)
protocol	string	Yes	Network protocol: tcp, udp, or icmp4
description	string	Yes	Human-readable rule description (max 255 chars)
destination_port	string	No	Port number, range (e.g. 80-90), or comma-separated list (e.g. 80,443). Required for TCP/UDP.
destination	string	No	Destination IPv4 address or CIDR range. Use 0.0.0.0/0 for any destination.
source_port	string	No	Source port filter (rarely used)
state	string	No	Rule state: enabled or disabled (defaults to enabled)
icmp_type	string	No	ICMP type number
icmp_code	string	No	ICMP code number

{
  "action": "allow",
  "protocol": "tcp",
  "description": "Allow outbound HTTPS",
  "destination_port": "443",
  "destination": "0.0.0.0/0"
}

Response

200

{
  "statusCode": 200,
  "message": "Rule already exists",
  "data": {}
}

201

{
  "statusCode": 201,
  "message": "Egress rule added successfully",
  "data": {}
}

400

{
  "statusCode": 400,
  "error": "CONTAINER_FIREWALL_RULE_LIMIT",
  "message": "This container has reached its firewall rule limit.",
  "data": {
    "field": "container_firewall_rule_limit",
    "container_id": "507f1f77bcf86cd799439011",
    "server_id": "507f1f77bcf86cd799439022",
    "current_count": 500,
    "limit": 500
  }
}

Error Code	Title	Description	Resolution
CONTAINER_FIREWALL_RULE_LIMIT	Container firewall rule limit reached	The container already holds the maximum number of firewall rules allowed (ingress and egress counted together). The applicable limit is returned as max_rules when listing firewall rules.	Remove an existing firewall rule on this container before adding a new one.
CONTAINER_FIREWALL_BYTES_LIMIT	Container firewall rule size limit reached	The container’s firewall rules have reached their total serialized size budget. This can be hit below the rule-count limit when individual rules are large (long descriptions or address lists). The applicable limit is returned as max_bytes when listing firewall rules.	Remove rules, or shorten descriptions and address lists, before adding a new rule.

404

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

503

{
  "statusCode": 503,
  "error": "FIREWALL_INVENTORY_UNAVAILABLE",
  "message": "Unable to verify this container's firewall rules. No changes were made.",
  "data": {
    "field": "firewall_inventory",
    "container_id": "507f1f77bcf86cd799439011"
  }
}

Error Code	Title	Description	Resolution
FIREWALL_INVENTORY_UNAVAILABLE	Firewall inventory unavailable	The container’s live firewall rule list could not be established (host unreachable, or a malformed response), so the rule limit could not be evaluated. The request fails closed: no rule was added.	Retry shortly. If it persists, the hosting server may be unreachable.

SDK Usage

cURL

curl -X POST https://api.hoody.com/api/v1/containers/{id}/firewall/egress \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "allow",
    "protocol": "tcp",
    "description": "Allow outbound HTTPS",
    "destination_port": "443",
    "destination": "0.0.0.0/0"
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.firewall.addEgressRule('{id}', {
  action: 'allow',
  protocol: 'tcp',
  description: 'Allow outbound HTTPS',
  destination_port: '443',
  destination: '0.0.0.0/0'
});

PATCH /api/v1/containers/{id}/firewall/egress

Enable or disable an egress (outbound) firewall rule without deleting it. Provide filters to identify which rule to toggle. Useful for temporarily disabling rules.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID

Request Body

Field	Type	Required	Description
state	string	Yes	New state for the rule: enabled or disabled
action	string	No	Action for matching traffic: allow, reject, or drop
protocol	string	No	Protocol type: tcp, udp, or icmp4
destination_port	string	No	Destination port, range (e.g. 80-90), or list (e.g. 80,443)
source_port	string	No	Source port, range, or list
destination	string	No	Destination IPv4 address or CIDR range
description	string	No	Rule description (max 255 chars)
icmp_type	string	No	ICMP type number
icmp_code	string	No	ICMP code number

{
  "state": "disabled",
  "protocol": "tcp",
  "destination_port": "25"
}

Response

200

{
  "statusCode": 200,
  "message": "Egress rule state toggled successfully",
  "data": {
    "direction": "egress",
    "new_state": "enabled",
    "updated": {
      "action": "allow",
      "protocol": "tcp",
      "description": "Allow outbound HTTPS",
      "destination_port": "443",
      "destination": "0.0.0.0/0",
      "state": "enabled"
    }
  }
}

404

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

SDK Usage

cURL

curl -X PATCH https://api.hoody.com/api/v1/containers/{id}/firewall/egress \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "disabled",
    "protocol": "tcp",
    "destination_port": "25"
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.firewall.toggleEgressRule('{id}', {
  state: 'disabled',
  protocol: 'tcp',
  destination_port: '25'
});

DELETE /api/v1/containers/{id}/firewall/egress

Remove one or more egress (outbound) firewall rules. Provide filters to match specific rules, or use all: true to remove all egress rules. Not equivalent to reset — this only deletes rules and leaves the firewall/ACL attached.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID

Request Body

Field	Type	Required	Default	Description
all	boolean	No	—	Remove all matching rules (default: first match only). Set to true with no other filters to remove all egress rules.
action	string	No	—	Action for matching traffic: allow, reject, or drop
protocol	string	No	—	Protocol type: tcp, udp, or icmp4
destination_port	string	No	—	Destination port, range, or list
destination	string	No	—	Destination IPv4 address or CIDR range
source_port	string	No	—	Source port, range, or list
description	string	No	—	Rule description
state	string	No	"enabled"	Rule state: enabled or disabled
icmp_type	string	No	—	ICMP type number
icmp_code	string	No	—	ICMP code number

{
  "protocol": "tcp",
  "destination_port": "25"
}

Response

200

{
  "statusCode": 200,
  "message": "Egress rules removed successfully",
  "data": {
    "direction": "egress",
    "removed_count": 2,
    "removed": [
      {
        "action": "allow",
        "protocol": "tcp",
        "description": "Allow outbound HTTPS",
        "destination_port": "443",
        "destination": "0.0.0.0/0",
        "state": "enabled"
      },
      {
        "action": "allow",
        "protocol": "tcp",
        "description": "Allow outbound DNS",
        "destination_port": "53",
        "destination": "8.8.8.8",
        "state": "enabled"
      }
    ]
  }
}

404

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

SDK Usage

cURL

curl -X DELETE https://api.hoody.com/api/v1/containers/{id}/firewall/egress \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": "tcp",
    "destination_port": "25"
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.firewall.removeEgressRule('{id}', {
  protocol: 'tcp',
  destination_port: '25'
});

Reset

POST /api/v1/containers/{id}/firewall/reset

Delete the ACL and detach the container from its firewall bridge, returning the container to an open state. Use this to wipe a misconfigured rule set quickly; rebuilding the rule set afterwards requires adding rules one by one.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID

Response

200

{
  "statusCode": 200,
  "message": "Firewall reset successfully",
  "data": {
    "rules": {
      "ingress": [],
      "egress": []
    }
  }
}

404

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

SDK Usage

cURL

curl -X POST https://api.hoody.com/api/v1/containers/{id}/firewall/reset \
  -H "Authorization: Bearer <token>"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.firewall.reset('{id}');