Skip to main content

Connecting Agents

The proxy uses the standard HTTP_PROXY / HTTPS_PROXY convention, so most HTTP client libraries route through it automatically once the environment is set. Connecting an agent has two parts: the environment variables that point traffic at the gateway, and a proxy access token the agent presents to authenticate.

The pieces​

PieceWhat it is
HTTP_PROXY / HTTPS_PROXYPoint your agent's outbound HTTP and HTTPS at the gateway.
NO_PROXYHosts that should bypass the proxy (e.g. localhost).
Proxy access tokenA short-lived, workflow-bound token the agent presents to the proxy. Minted with asg proxy token create or the consent flow, and referenced via a token file.

You rarely set these by hand — asg proxy env and asg proxy container-config generate them for you.

Shell / local process​

eval "$(asg proxy env acme)"

This exports HTTP_PROXY, HTTPS_PROXY, NO_PROXY, and AGENT_SECURITY_PROXY_TOKEN_FILE (the path to the token file) into the current shell. Mint the token first (step 4 of the Quick Start) at the path asg proxy env expects — $HOME/.agent-security/tokens/<subdomain>.token — or point AGENT_SECURITY_PROXY_TOKEN_FILE at wherever you wrote it.

Routing traffic through the proxy is only half of it: every request must also carry Proxy-Authorization: Bearer <token>. Exporting the env does not authenticate your requests — your HTTP client has to read the token from $AGENT_SECURITY_PROXY_TOKEN_FILE and send that header (or launch the agent with asg run, which injects the token into the proxy URL for you). Without it the proxy answers 407.

Docker and Kubernetes​

Generate ready-to-use container configuration:

# Docker env file or Compose snippet.
asg proxy container-config acme --format docker-env
asg proxy container-config acme --format docker-compose

# Kubernetes ConfigMap.
asg proxy container-config acme --format k8s-configmap

Mount or reference the emitted configuration in your agent's container so the proxy variables are present in its environment. Supply the proxy token through your platform's normal secret mechanism (a mounted file or secret), and point AGENT_SECURITY_PROXY_TOKEN_FILE at it.

HTTPS interception​

By default the proxy handles HTTPS in passthrough mode: it authenticates and authorizes the connection against the domain's tunnel rule (the all-method, path-less rule — see Workflows & Rules), but the encrypted tunnel is forwarded opaquely — the proxy does not see the request path or body, and it can't inject a credential or scrub the response inside the tunnel.

To apply full governance to HTTPS — path-level rules, credential injection, and response scrubbing inside the encrypted connection — switch the domain's tunnel rule to intercept mode. You set TLS mode in the dashboard workflow editor (CLIs / APIs → Workflows, open the workflow, edit the tunnel rule, set TLS mode to Intercept (decrypt + inject credential)). TLS mode is read from the tunnel rule, so setting it on a path- or method-scoped rule has no effect.

In intercept mode the proxy terminates the agent's TLS using a certificate authority issued for your host and re-applies every check to the decrypted request. For your agent to trust those connections, it must trust that CA certificate — manage it with the CLI:

# Inspect your host's interception CA.
asg proxy ca status acme

# Download the CA certificate to install in your agent's trust store.
asg proxy ca download acme --output ./agent-security-ca.pem

# Print a shell snippet that points common tools at the CA.
asg proxy ca trust-shell acme

# Rotate the CA, keeping the previous one valid during a grace window.
asg proxy ca rotate acme --grace-days 7
Choosing a mode

Use passthrough when domain-level control is enough, or for very large uploads, downloads, and long-lived streaming connections. Use intercept when you need path-level rules, credential injection, or response scrubbing on HTTPS traffic. Mode is decided by the rule that authorizes the tunnel, so in practice it's per domain for HTTPS — you can mix passthrough and intercept across domains.

Diagnose with doctor​

When something isn't connecting, run the built-in diagnostic:

asg proxy doctor acme

doctor checks, end to end:

  • Gateway reachability
  • Whether the proxy is enabled for the host
  • How many credentials are configured
  • Your local proxy environment variables
  • The interception CA's status and expiry, and whether your environment trusts it
  • The token file's permissions and the token's expiry

Each check reports pass, warn, or fail; anything that isn't a pass carries a suggested fix. doctor exits 0 (clean), 1 (operator-fixable failure), or 2 (gateway fault), so it's safe to gate CI on — and it's the first thing to run whenever an agent's traffic isn't behaving.

What's next​

  • Quick Start — the end-to-end setup these commands fit into.
  • Security — what the proxy enforces on the traffic you route through it.
  • The asg CLI — full command reference.

Contents