Configure an obs-agent Forward Proxy¶

This guide explains how to route self-hosted obs-agent traffic to Beak, LLM and AI Hub services, remote MCP servers, and Agent release services through an HTTP forward proxy.

Prepare Proxy Information¶

Prepare the proxy URL and bypass list:

export HTTP_PROXY='http://<PROXY-USER>:<PROXY-PASSWORD>@<PROXY-HOST>:<PROXY-PORT>'
export HTTPS_PROXY="$HTTP_PROXY"
export NO_PROXY='localhost,127.0.0.1,::1,<INTERNAL-DOMAIN>'

The current version supports unauthenticated HTTP proxies, Basic Auth in URL user information, uppercase and lowercase forms of HTTP_PROXY, HTTPS_PROXY, and NO_PROXY, and enterprise CAs selected with SSL_CERT_FILE or SSL_CERT_DIR.

The proxy endpoint must use http://. For HTTPS and WSS targets, the Agent establishes an HTTP CONNECT tunnel and then validates the target TLS certificate. If uppercase and lowercase forms of the same variable are both set, their values must match. The installer fills in the other case and always retains localhost,127.0.0.1,::1 in NO_PROXY.

Protect proxy credentials

Proxy URLs may contain usernames and passwords. Do not include complete URLs in tickets, public logs, chats, or screenshots. /etc/obs-agent/agent.env contains sensitive configuration and should remain readable only by administrators and the obs-agent group.

Use a Proxy During Linux Installation¶

Export the proxy variables, download the installer, and explicitly preserve the variables through sudo:

export HTTP_PROXY='http://<PROXY-USER>:<PROXY-PASSWORD>@<PROXY-HOST>:<PROXY-PORT>'
export HTTPS_PROXY="$HTTP_PROXY"
export NO_PROXY='localhost,127.0.0.1,::1,<INTERNAL-DOMAIN>'

curl -fsSL https://static.guance.com/obs-agent/install.sh \
  -o /tmp/obs-agent-install.sh

sudo --preserve-env=HTTP_PROXY,http_proxy,HTTPS_PROXY,https_proxy,NO_PROXY,no_proxy,SSL_CERT_FILE,SSL_CERT_DIR \
  bash /tmp/obs-agent-install.sh <INSTALL-OPTIONS-FROM-BEAK>

The installer writes normalized proxy settings to /etc/obs-agent/agent.env. Restart and verify the service:

sudo systemctl restart obs-agent
systemctl status obs-agent
journalctl -u obs-agent -n 100

obs-agent forward proxy configured followed by obs-agent websocket connected indicates that the proxy was loaded and the Beak connection succeeded. Credentials are redacted from startup logs.

Add a Proxy to an Existing Linux Installation¶

Back up and edit the configuration:

sudo cp /etc/obs-agent/agent.env /etc/obs-agent/agent.env.bak

Set both cases consistently:

HTTP_PROXY="http://<PROXY-USER>:<PROXY-PASSWORD>@<PROXY-HOST>:<PROXY-PORT>"
http_proxy="http://<PROXY-USER>:<PROXY-PASSWORD>@<PROXY-HOST>:<PROXY-PORT>"
HTTPS_PROXY="http://<PROXY-USER>:<PROXY-PASSWORD>@<PROXY-HOST>:<PROXY-PORT>"
https_proxy="http://<PROXY-USER>:<PROXY-PASSWORD>@<PROXY-HOST>:<PROXY-PORT>"
NO_PROXY="localhost,127.0.0.1,::1,<INTERNAL-DOMAIN>"
no_proxy="localhost,127.0.0.1,::1,<INTERNAL-DOMAIN>"

Protect the file and restart:

sudo chown root:obs-agent /etc/obs-agent/agent.env
sudo chmod 0640 /etc/obs-agent/agent.env
sudo systemctl restart obs-agent

Restore the backup with sudo cp /etc/obs-agent/agent.env.bak /etc/obs-agent/agent.env if rollback is required.

Keep Automatic Updates on the Proxy¶

The Linux update service and manual updater read /etc/obs-agent/agent.env. The same proxy is used to fetch latest-version.json, download install.sh, release archives and checksums, report upgrade status to Beak, and run Owl CLI updates.

systemctl status obs-agent-update-check.timer
systemctl list-timers obs-agent-update-check.timer
journalctl -u obs-agent-update-check.service -n 100

sudo systemctl start obs-agent-update-check.service
journalctl -u obs-agent-update-check.service -n 100

sudo /usr/local/bin/obs-agent-updater

If the proxy is unavailable or authentication fails, the update fails while the installed version remains unchanged; it does not silently fall back to direct internet access.

Use a Proxy with Docker¶

Store proxy variables in a protected env file:

cat > obs-agent-proxy.env <<'EOF'
HTTP_PROXY=http://<PROXY-USER>:<PROXY-PASSWORD>@<PROXY-HOST>:<PROXY-PORT>
http_proxy=http://<PROXY-USER>:<PROXY-PASSWORD>@<PROXY-HOST>:<PROXY-PORT>
HTTPS_PROXY=http://<PROXY-USER>:<PROXY-PASSWORD>@<PROXY-HOST>:<PROXY-PORT>
https_proxy=http://<PROXY-USER>:<PROXY-PASSWORD>@<PROXY-HOST>:<PROXY-PORT>
NO_PROXY=localhost,127.0.0.1,::1,<INTERNAL-DOMAIN>
no_proxy=localhost,127.0.0.1,::1,<INTERNAL-DOMAIN>
EOF
chmod 0600 obs-agent-proxy.env

docker run -d \
  --name obs-agent \
  --restart unless-stopped \
  --env-file ./obs-agent.env \
  --env-file ./obs-agent-proxy.env \
  -v obs-agent-work:/app \
  -v obs-agent-profile-cache:/var/lib/obs-agent/profile-cache \
  "${OBS_AGENT_IMAGE}"

The entrypoint validates proxy variables before requesting Beak configuration. Check with docker logs obs-agent 2>&1 | tail -n 100.

Use a Proxy with Kubernetes or Helm¶

Store proxy URLs with credentials in a Kubernetes Secret alongside the Agent credentials:

kubectl -n obs-agent create secret generic obs-agent-secret \
  --from-literal=AGENT_ID='<AGENT-ID>' \
  --from-literal=AGENT_API_KEY='<AGENT-API-KEY>' \
  --from-literal=HTTP_PROXY='http://<PROXY-USER>:<PROXY-PASSWORD>@<PROXY-HOST>:<PROXY-PORT>' \
  --from-literal=HTTPS_PROXY='http://<PROXY-USER>:<PROXY-PASSWORD>@<PROXY-HOST>:<PROXY-PORT>'

Reference the Secret and set NO_PROXY separately in the Deployment. For Helm, ensure secret.keys includes HTTP_PROXY and HTTPS_PROXY, then upgrade:

helm upgrade obs-agent obs-agent/obs-agent \
  --namespace obs-agent \
  --reuse-values \
  --set 'secret.keys={AGENT_API_KEY,AGENT_ID,HTTP_PROXY,HTTPS_PROXY}'

After changing the Secret or values, wait for the Pod to be recreated and inspect kubectl -n obs-agent logs deploy/obs-agent --tail=100.

Configure an Enterprise CA¶

If the proxy re-signs TLS certificates, mount the CA bundle and set SSL_CERT_FILE or SSL_CERT_DIR. On Linux, store the CA in a root-owned location and add the variable to /etc/obs-agent/agent.env. In Docker or Kubernetes, mount the CA read-only and point SSL_CERT_FILE to the container path. Never disable TLS verification.

SSL_CERT_FILE=/etc/obs-agent/certs/enterprise-ca.pem

Confirm Which Requests Use the Proxy¶

The proxy applies to Beak config API and WebSocket traffic, LLM and AI Hub requests, remote MCP HTTP traffic, release metadata and downloads, installer and updater requests, and Owl update requests. Local filesystem and process tools do not use the proxy. Targets matched by NO_PROXY connect directly.

Troubleshoot Proxy Connections¶

Agent Reports Conflicting Proxy Variables¶

Check both cases and make their values identical:

sudo grep -E '^(HTTP_PROXY|http_proxy|HTTPS_PROXY|https_proxy|NO_PROXY|no_proxy)=' \
  /etc/obs-agent/agent.env

Proxy Returns 407 Proxy Authentication Required¶

Verify the username, password, and proxy authorization policy. URL-encode special characters in credentials. Do not print the complete proxy URL while troubleshooting.

HTTPS Requests Report Certificate Errors¶

Confirm that the enterprise CA is mounted, readable by obs-agent, and selected by SSL_CERT_FILE or SSL_CERT_DIR. Keep the proxy endpoint as http://; HTTPS targets are protected inside CONNECT tunnels.

Internal Addresses Incorrectly Use the Proxy¶

Add internal domains, IPs, or CIDRs to both NO_PROXY and no_proxy. Do not use NO_PROXY=* as a permanent configuration because it bypasses the proxy for every target.

Agent Connects but Automatic Updates Fail¶

Check journalctl -u obs-agent-update-check.service -n 100 and journalctl -u obs-agent -n 100. Confirm that the AGENT_UPDATE_BASE_URL domain is not incorrectly listed in NO_PROXY and that the proxy allows latest-version.json, install.sh, release archives, and checksums.