Egress proxy

Route Oktapod HTTP and HTTPS through CrabTrap or another separately operated policy proxy.

Oktapod can route outbound HTTP and HTTPS through a separately operated proxy such as CrabTrap, a corporate policy gateway, or a local debugging proxy.

The feature is optional and disabled by default. It adds transport-level inspection without replacing Oktapod's first-party action policy, approvals, effect ledger, or audit trail.

#How it fits

The controls protect different boundaries:

A proxy is useful defense in depth when agents hold valuable credentials, execute third-party tools, or access production APIs. Many personal installations can rely on Oktapod's native policy, approval, sandbox, and credential controls without adding one.

#Configure a proxy

Add a top-level egress_proxy block to ~/.oktapod/oktapod.json:

{
  "version": 1,
  "egress_proxy": {
    "mode": "optional",
    "url": "http://127.0.0.1:8080",
    "ca_certificate_path": "./crabtrap-ca.pem",
    "no_proxy": "localhost,127.0.0.1,::1",
    "apply_to": ["core", "gateway", "ctl", "workers", "subprocesses"]
  }
}

Restart Oktapod after changing the configuration:

oktapod restart
oktapod doctor

The proxy itself remains independently installed, configured, started, updated, and stopped. Oktapod does not bundle or manage CrabTrap.

#Modes

Both enabled modes deliberately avoid direct retry after a proxied request fails. A proxy may have forwarded a mutation before the response was lost; retrying the same request directly could duplicate the side effect.

#What enforced guarantees

For selected Oktapod surfaces, enforced provides application-level control:

• startup rejects missing or invalid proxy configuration;
• HTTP and HTTPS use the configured proxy dispatcher;
• a denied or unavailable proxy makes the request fail;
• requests never fall back to direct transport;
• oktapod doctor treats an unreachable proxy as blocking.

enforced does not create a host firewall. A subprocess that ignores proxy variables and opens its own socket may still connect directly if the operating system permits it. For non-bypassable egress, combine enforced with host or container rules that allow the workload to reach only the proxy and required local control endpoints.

#Configuration reference

Proxy URLs must use http or https. If only one of http_url or https_url is provided, Oktapod uses it for both protocols.

Relative CA paths resolve from the directory containing ~/.oktapod/oktapod.json. Oktapod augments Node's normal root certificates rather than replacing them.

#Coverage

apply_to accepts:

When subprocesses is selected, Oktapod propagates uppercase and lowercase HTTP_PROXY, HTTPS_PROXY, and NO_PROXY variables. If a CA is configured, Node subprocesses also receive NODE_EXTRA_CA_CERTS.

Network-disabled sandboxes remain offline. A personal CLI tool receives proxy configuration only when its tool contract declares network access.

#Local control traffic

Oktapod always adds these loopback destinations to no_proxy:

localhost,127.0.0.1,::1

This preserves local core-to-gateway and CLI-to-runtime control traffic. Additional entries are merged with the loopback defaults.

Every no_proxy entry is an intentional bypass. Keep the list narrow in enforced deployments and pair it with equivalent firewall policy.

#TLS interception and custom CAs

CrabTrap-style HTTPS inspection issues destination certificates from a private CA. Set ca_certificate_path so Oktapod's Node dispatcher trusts that CA in addition to the standard system roots.

For subprocesses:

• Node receives the CA through NODE_EXTRA_CA_CERTS.
• Non-Node clients may require system trust or tool-specific CA configuration.
• Certificate-pinned clients may reject interception regardless of CA trust.
• QUIC traffic may need to be disabled or separately controlled by the proxy host.

Treat CA installation as a security-sensitive operator action. Anyone controlling a trusted interception CA can inspect protected traffic routed through it.

#Environment overrides

Service managers and temporary trials can use environment variables instead of the JSON block:

export OKTAPOD_EGRESS_PROXY_MODE=optional
export OKTAPOD_EGRESS_PROXY_URL=http://127.0.0.1:8080
export OKTAPOD_EGRESS_PROXY_CA_CERT_PATH=/absolute/path/to/crabtrap-ca.pem
export OKTAPOD_EGRESS_PROXY_APPLY_TO=core,gateway,ctl,workers,subprocesses
oktapod restart

Full override set:

Environment values take precedence over file values. Proxy credentials embedded in URLs are passed to covered transports but redacted from Oktapod diagnostics.

#Doctor and troubleshooting

Run:

oktapod doctor

The doctor.egress_proxy check reports:

• active mode and configuration source;
• redacted HTTP and HTTPS endpoints;
• CA path and configuration validity;
• declared process coverage;
• whether each unique proxy endpoint accepts a TCP connection.

Common results:

Reachability proves that the proxy accepts a connection, not that every policy rule, TLS interception path, or firewall constraint is correct. Validate those separately with representative traffic.

#Traffic outside this boundary

The generic dispatcher covers HTTP and HTTPS. Other transports need separate support or host-level enforcement, including:

• IMAP and SMTP;
• raw TCP or UDP sockets;
• browser QUIC;
• native applications not launched through the covered process environment;
• subprocesses that deliberately ignore proxy configuration.

The proxy also does not replace approval logic. Oktapod should continue deciding whether an action is authorized before the proxy evaluates its network request.

#Recommended production posture

For production APIs or high-value credentials:

1. Use narrowly scoped service accounts.
2. Keep Oktapod approvals and effect authorization enabled.
3. Set the proxy to enforced for every relevant surface.
4. Keep no_proxy limited to required local endpoints.
5. Trust the interception CA only where necessary.
6. Add firewall or container rules preventing direct egress.
7. Test one allowed request, one denied request, and proxy outage behavior.
8. Confirm oktapod doctor is clean before granting production credentials.

This produces complementary controls: Oktapod governs intended effects, the proxy inspects actual HTTP traffic, and the host prevents transport bypass.