Firewall Rules - Codex-LB

Overview

The Firewall API allows you to manage an IP allowlist for restricting access to proxy endpoints. When the allowlist is active (contains at least one IP), only requests from listed IPs can access the proxy routes.

Dashboard endpoints (/api/*) are never restricted by the firewall. Only proxy endpoints are affected.

Protected Endpoints

The firewall protects these proxy-facing paths:

/v1/* - OpenAI-compatible API endpoints
/backend-api/codex/* - Codex-specific endpoints
/backend-api/transcribe - Audio transcription endpoint

Dashboard and management endpoints remain accessible regardless of firewall rules.

List Firewall IPs

GET /api/firewall/ips

endpoint

Retrieve the current firewall mode and all allowed IP addresses.

Response

mode

string

required

Current firewall mode:

allow_all: Allowlist is empty, all IPs are permitted
allowlist_active: Allowlist is active, only listed IPs are permitted

entries

array

required

Array of allowed IP addresses

Show FirewallIpEntry

ip_address

string

IP address (IPv4 or IPv6)

created_at

string

ISO 8601 timestamp when added

Example Request

curl -X GET "https://your-instance.com/api/firewall/ips" \
  -H "Cookie: dashboard_session=your-session-token"

Example Response - Allow All Mode

{
  "mode": "allow_all",
  "entries": []
}

Example Response - Allowlist Active

{
  "mode": "allowlist_active",
  "entries": [
    {
      "ip_address": "203.0.113.45",
      "created_at": "2026-03-03T14:30:00Z"
    },
    {
      "ip_address": "198.51.100.0",
      "created_at": "2026-03-03T15:00:00Z"
    },
    {
      "ip_address": "2001:db8::1",
      "created_at": "2026-03-03T16:00:00Z"
    }
  ]
}

Add IP to Allowlist

POST /api/firewall/ips

endpoint

Add an IP address to the allowlist. The firewall automatically activates when the first IP is added.

Request Body

ip_address

string

required

IP address to allow (IPv4 or IPv6 format)

Response

Returns the created firewall entry.

ip_address

string

required

The normalized IP address

created_at

string

required

Timestamp when the IP was added

Example Request - IPv4

curl -X POST "https://your-instance.com/api/firewall/ips" \
  -H "Cookie: dashboard_session=your-session-token" \
  -H "Content-Type: application/json" \
  -d '{
    "ip_address": "203.0.113.45"
  }'

Example Request - IPv6

curl -X POST "https://your-instance.com/api/firewall/ips" \
  -H "Cookie: dashboard_session=your-session-token" \
  -H "Content-Type: application/json" \
  -d '{
    "ip_address": "2001:db8::1"
  }'

Example Response

{
  "ip_address": "203.0.113.45",
  "created_at": "2026-03-03T19:45:00Z"
}

Error Responses

400

error

invalid_ip: The provided IP address format is invalid

409

error

ip_exists: This IP address is already in the allowlist

Remove IP from Allowlist

DELETE /api/firewall/ips/{ip_address}

endpoint

Remove an IP address from the allowlist. When the last IP is removed, the firewall returns to allow_all mode.

Path Parameters

ip_address

string

required

The IP address to remove (URL-encoded if necessary)

Response

status

string

required

Always returns “deleted” on success

Example Request

curl -X DELETE "https://your-instance.com/api/firewall/ips/203.0.113.45" \
  -H "Cookie: dashboard_session=your-session-token"

Example Request - IPv6 (URL-encoded)

curl -X DELETE "https://your-instance.com/api/firewall/ips/2001%3Adb8%3A%3A1" \
  -H "Cookie: dashboard_session=your-session-token"

Example Response

{
  "status": "deleted"
}

Error Responses

400

error

invalid_ip: The provided IP address format is invalid

404

error

ip_not_found: The specified IP address is not in the allowlist

Firewall Behavior

Allow All Mode (Default)

When the allowlist is empty:

mode: "allow_all"
All client IPs can access proxy endpoints
Dashboard endpoints remain accessible
No IP validation is performed

Allowlist Active Mode

When one or more IPs are in the allowlist:

mode: "allowlist_active"
Only listed IPs can access proxy endpoints
Unlisted IPs receive 403 Forbidden
Dashboard endpoints remain accessible from any IP

Blocked Request Response

When a request from an unlisted IP is blocked:

{
  "error": {
    "code": "ip_forbidden",
    "message": "Your IP address is not allowed to access this endpoint",
    "type": "permission_error"
  }
}

HTTP Status: 403 Forbidden

Trusted Proxy Configuration

If Codex-LB is behind a reverse proxy (nginx, Cloudflare, etc.), configure trusted proxy headers to ensure correct IP resolution.

Environment Variables

# Enable proxy header trust
FIREWALL_TRUST_PROXY_HEADERS=true

# Define trusted proxy CIDR ranges
FIREWALL_TRUSTED_PROXY_CIDRS=10.0.0.0/8,172.16.0.0/12,192.168.0.0/16

Header Resolution Logic

When FIREWALL_TRUST_PROXY_HEADERS=true:

Check if request source IP matches a trusted CIDR
If trusted, extract client IP from X-Forwarded-For header (first valid IP)
If untrusted or header missing, use source socket IP

Example Scenarios

Direct Connection
Trusted Proxy
Untrusted Proxy

Client (203.0.113.45) → Codex-LB

Firewall sees: 203.0.113.45

Client (203.0.113.45) → nginx (10.0.0.5) → Codex-LB
X-Forwarded-For: 203.0.113.45

10.0.0.5 matches trusted CIDR 10.0.0.0/8
Firewall sees: 203.0.113.45 (from header)

Client (203.0.113.45) → untrusted proxy (1.2.3.4) → Codex-LB
X-Forwarded-For: 203.0.113.45

1.2.3.4 does not match any trusted CIDR
Firewall sees: 1.2.3.4 (header ignored)

Never enable FIREWALL_TRUST_PROXY_HEADERS without properly configuring FIREWALL_TRUSTED_PROXY_CIDRS. An attacker could spoof the X-Forwarded-For header to bypass the allowlist.

Use Cases

Corporate Network

Restrict proxy access to your company’s public IP ranges.

CI/CD Pipeline

Allow only your build servers to access the API for automated testing.

Development

Permit specific developer IPs during initial deployment.

Partner Access

Grant proxy access to trusted partner organizations’ IP ranges.

Best Practices

1. Start with Dashboard-Only Access

During initial setup:

Add your admin IP to the allowlist
Test dashboard access (should always work)
Test proxy access from your IP (should work)
Test proxy access from another IP (should be blocked)

2. Use CIDR Notation

For IP ranges, you can add individual IPs or configure your reverse proxy to handle CIDR ranges upstream.

3. Monitor Blocked Requests

Check request logs for ip_forbidden errors to identify legitimate users being blocked:

grep "ip_forbidden" /var/log/codex-lb/requests.log

4. Coordinate with Network Team

Before enabling the firewall in production:

Document all allowed IP ranges
Get confirmation from network team on static IPs
Plan for IP changes (ISP reassignments, office moves)

5. Emergency Access

If you lock yourself out:

SSH into the server
Access the database directly
Clear the firewall_ips table: DELETE FROM firewall_ips;
The firewall returns to allow_all mode

Authentication

All firewall management endpoints require dashboard authentication via session cookie. The firewall enforcement itself is separate from authentication - it operates at the network layer.

Common Error Codes

Code	Description
`invalid_ip`	IP address format validation failed
`ip_exists`	Attempted to add a duplicate IP
`ip_not_found`	Attempted to remove an IP that isn’t in the allowlist
`ip_forbidden`	Client IP not in allowlist (returned to blocked proxy requests)

Overview

OpenAI-Compatible Endpoints

Codex Endpoints

Management API

​Overview

​Protected Endpoints

​List Firewall IPs

​Response

​Example Request

​Example Response - Allow All Mode

​Example Response - Allowlist Active

​Add IP to Allowlist

​Request Body

​Response

​Example Request - IPv4

​Example Request - IPv6

​Example Response

​Error Responses

​Remove IP from Allowlist

​Path Parameters

​Response

​Example Request

​Example Request - IPv6 (URL-encoded)

​Example Response

​Error Responses

​Firewall Behavior

​Allow All Mode (Default)

​Allowlist Active Mode

​Blocked Request Response

​Trusted Proxy Configuration

​Environment Variables

​Header Resolution Logic

​Example Scenarios

​Use Cases

Corporate Network

CI/CD Pipeline

Development

Partner Access

​Best Practices

​1. Start with Dashboard-Only Access

​2. Use CIDR Notation

​3. Monitor Blocked Requests

​4. Coordinate with Network Team

​5. Emergency Access

​Authentication

​Common Error Codes

Build docs developers (and LLMs) love

Overview

Protected Endpoints

List Firewall IPs

Response

Example Request

Example Response - Allow All Mode

Example Response - Allowlist Active

Add IP to Allowlist

Request Body

Response

Example Request - IPv4

Example Request - IPv6

Example Response

Error Responses

Remove IP from Allowlist

Path Parameters

Response

Example Request

Example Request - IPv6 (URL-encoded)

Example Response

Error Responses

Firewall Behavior

Allow All Mode (Default)

Allowlist Active Mode

Blocked Request Response

Trusted Proxy Configuration

Environment Variables

Header Resolution Logic

Example Scenarios

Use Cases

Best Practices

1. Start with Dashboard-Only Access

2. Use CIDR Notation

3. Monitor Blocked Requests

4. Coordinate with Network Team

5. Emergency Access

Authentication

Common Error Codes