Proxies: outbound, reverse and API-level forwarding

A proxy in DeepSeek Harness points in three directions: outbound, inbound and API layer. Each direction has its own configuration location and diagnosis path, and calling all of them "proxy" is how people edit the wrong file.

Three directions

Start with where the request travels.

Outbound solves "I cannot get out." On a restricted network, the client reaches the model service through a proxy.

Inbound solves "others cannot get in." External access to your web UI needs a domain, TLS and auth at the gateway.

API forwarding solves "send the request elsewhere." It moves model calls to another endpoint or translates protocol, affecting only model traffic.

HTTP proxy: outbound

The goal is that outbound requests use the proxy.

1. Confirm the proxy address, port and whether credentials are needed.
2. Set HTTP and HTTPS proxies in the client or environment variables.
3. Keep local services off the proxy to avoid loops.
4. Test a model request and confirm it reaches the provider.
5. Read proxy logs to prove the request passed through.

Separate proxied from direct traffic. Proxy only the model calls; sending loopback traffic through the proxy creates a cycle where the client calls itself.

Certificates are the most common problem. HTTPS inspection replaces certificates, so trust the corporate root instead of disabling verification.

Reverse proxy: inbound

The goal is exposing the service safely.

1. Configure a domain and TLS certificate pointing at the local web service.
2. Add an auth layer with at least one login or access control.
3. Restrict origins to shrink the scanning surface.
4. Forward WebSocket and long-lived connections so pages do not drop.
5. Test from an external network, not the LAN.

TLS and auth are the floor. Missing either makes public access unsafe; an unusual port is not protection.

WebSocket is easy to forget. Forwarding only plain HTTP lets pages open while features break; upgrade headers need explicit configuration.

zcode forwarding: API layer

API forwarding touches model requests only, not the web UI.

1. Confirm the target endpoint and protocol: OpenAI-compatible or proprietary.
2. Configure base URL and key, watching for version segments in the path.
3. Confirm model name mapping so upstream renames do not cause 404.
4. Test both the model list and a conversation.
5. Record the forwarding rules so you can roll back.

A protocol mismatch shows up as 404 or a parse failure. API forwarding is not always a blind relay; it may need request-body translation, so read the target docs (source).

Model names may be mapped. The forwarding layer points aliases at upstream models, and a wrong alias looks like a missing model in the client.

Three scenarios side by side

Match by direction, location and verification.

All three can coexist, but one word should not cover three layers. Outbound proxy, inbound reverse proxy and API forwarding each handle a segment; identify the layer before troubleshooting. Directions differ, logs differ, and mixed edits multiply problems.

Troubleshooting

Four failure classes cover most proxy issues.

1. Nothing connects: wrong address, port or credentials; test proxy reachability first.
2. Certificate errors: a missing or replaced intermediate; repair the chain, never disable checks.
3. 502/504: the reverse proxy cannot forward or the upstream times out; read gateway and upstream logs.
4. Pages open, features fail: WebSocket, CORS or headers are not forwarded.

The first question is whether the request reached the proxy. If not, fix the client; if it arrived and failed, inspect upstream or forwarding. That splits most cases in half.

Read logs in layers. Client, proxy and upstream logs together are what locate the fault.

Security boundaries

A proxy widens the network path and raises the bar.

1. Never expose a bare port: inbound requires TLS and auth.
2. Restrict origins: limit by IP or subnet where possible.
3. Keep verification on: disabling it abandons identity checks.
4. Protect proxy credentials: never commit proxy passwords or ship them to the frontend.
5. Redact logs: proxy logs can hold keys and request bodies, so control retention.

A proxy is not a security control. It forwards traffic and does not replace auth or permissions; relying on an unlisted address is a thin defense.

Next steps

Set the direction, then the location, then read logs. For basic network proxy setup, read Network proxy configuration. For web reverse proxying, read Reverse proxy for the web UI. For API forwarding, read dsh zcode proxy.

Sources: DeepSeek Harness documentation, dsh CLI README, deepseek-harness repository