Skip to main content

Quick Start

This quick start is for operators setting up the HTTP Egress Proxy for the first time. By the end, an agent's call to the Stripe API goes through the proxy, which authenticates, authorizes, and logs the call, and a call to any other host is denied.

You enable the proxy, store the Stripe credential, create an API workflow that allows api.stripe.com, mint an agent token bound to that workflow, and send test requests through the proxy. The last step turns on HTTPS interception so the proxy injects the credential into HTTPS requests.

You can enable the proxy, store credentials, and mint tokens in the dashboard or with the asg CLI. You create API workflows in the dashboard, because the asg CLI has no workflow command. This guide uses the dashboard to create the workflow and the CLI for the other steps.

Prerequisites​

In every command, replace acme with your host's subdomain.

1. Enable the proxy for your host​

Proxy mode is off by default for every host. Turn proxy mode on for your host:

asg proxy config acme --enable

In the dashboard, go to CLIs / APIs → Overview and click Enable proxy mode.

2. Store the upstream credential​

Store the Stripe secret key in the gateway so the proxy can inject it and the agent never holds it. Stored secrets are write-only: you can overwrite or delete a secret, but no interface returns its value.

Save your Stripe secret key to ./stripe.key, then create a credential named stripe:

asg proxy credentials create stripe acme \
  --host api.stripe.com \
  --injection header \
  --header-name Authorization \
  --value-template "Bearer {secret}" \
  --secret-file ./stripe.key

The proxy adds the Authorization: Bearer header to matching requests and scrubs the secret from responses. For OAuth providers such as GitHub, Google, Notion, and Atlassian, use asg proxy connect instead of a static key.

In the dashboard, go to CLIs / APIs → Credentials and click Add credential.

Enable the KMS vault before storing production keys

Credential encryption at rest is off unless the gateway runs with the KMS vault enabled. Without the vault, the gateway writes credentials to its store in plaintext. Confirm the vault is enabled before you store a live key. See Credential isolation.

3. Create an API workflow​

An API workflow is the unit of access an agent token binds to: a set of allowed domains and the rules for each domain. Create one in the dashboard:

  1. Go to CLIs / APIs → Workflows and click Create workflow.
  2. Enter a name, for example Charge customers, and note the slug, for example charge_customers. Optionally add an Intent. Click Create workflow. The dashboard opens the workflow's page.
  3. On the workflow's page, click Add domain and enter api.stripe.com.
  4. Inside the api.stripe.com domain, click Add rule. Create the tunnel rule that HTTPS requires: set method class to All, leave the path empty, and attach the stripe credential. Set a required trust level, or leave Auto.

After these steps, the workflow allows HTTPS requests to api.stripe.com and denies every other destination. The stripe credential is attached to the tunnel rule, but the proxy injects it into HTTPS requests only after you turn on interception in step 7.

Why HTTPS needs a rule with method class All and no path

An HTTPS request reaches the proxy as a CONNECT request, and the proxy cannot see the path or method inside the encrypted tunnel. A CONNECT request can only match a rule with method class All and no path. If the domain has only a read rule for /v1/customers*, the proxy denies every HTTPS call to that domain. Path and method rules apply to plain HTTP, and to HTTPS once the tunnel rule uses intercept mode. See HTTPS needs a tunnel rule.

4. Mint a workflow-bound agent token​

The agent authenticates to the proxy with a short-lived token bound to one workflow. For an automated agent with no human delegating access, mint the token directly. Pass the workflow slug from the dashboard:

asg proxy token create acme \
  --client-id ci-runner \
  --workflow charge_customers \
  --out ~/.agent-security/tokens/acme.token

The token permits only requests that match the charge_customers workflow. The --out path is the default token path that asg proxy env exports in the next step.

To let a person delegate access to an agent within a trust ceiling instead, use the consent flow with asg proxy authorize.

5. Point your agent at the proxy​

The proxy uses the standard HTTP_PROXY and HTTPS_PROXY environment variables, so most HTTP libraries send traffic through it once the variables are set:

eval "$(asg proxy env acme)"

The command sets HTTP_PROXY, HTTPS_PROXY, and NO_PROXY, and exports AGENT_SECURITY_PROXY_TOKEN_FILE with the path of the token file from step 4.

The environment variables do not authenticate requests. Every request must also carry the Proxy-Authorization: Bearer <token> header, or the proxy returns 407. You have two options:

  • Configure your agent's HTTP client to read the token from $AGENT_SECURITY_PROXY_TOKEN_FILE and send the Proxy-Authorization header.
  • Launch the agent with asg run, which gets a token through browser consent and puts the token in the proxy URL for the agent process.

curl and git read only the lowercase http_proxy variable for plain HTTP. For Docker and Kubernetes, see Connecting agents.

6. Verify the allow-list​

curl does not read the token file, so pass the token in the --proxy-header option. Use curl -i to see the status line.

Send a request to the allowed host:

curl -i --proxy-header "Proxy-Authorization: Bearer $(cat "$AGENT_SECURITY_PROXY_TOKEN_FILE")" \
  https://api.stripe.com/v1/customers
# → HTTP/1.1 401 Unauthorized  (the response comes from Stripe)

Expected result: 401 Unauthorized from Stripe. The 401 shows that the proxy allowed the request and Stripe received it. In the default HTTPS passthrough mode, the proxy authorizes the tunnel but does not inject the stripe credential, so Stripe rejects the request.

Send a request to a host the workflow does not include:

curl -i --proxy-header "Proxy-Authorization: Bearer $(cat "$AGENT_SECURITY_PROXY_TOKEN_FILE")" \
  https://api.openai.com/v1/models
# → 403 from the proxy (deny-by-default); it never connects to OpenAI

Expected result: 403 from the proxy. The proxy denies the request and does not connect to api.openai.com.

If you omit the Proxy-Authorization header, the proxy returns 407 Proxy Authentication Required.

7. Inject credentials into HTTPS traffic​

To inject the stripe credential into HTTPS requests, apply path-level rules, and scrub responses, the proxy must decrypt the connection. Switch the tunnel rule to intercept mode:

  1. Set the tunnel rule to intercept. In the dashboard, go to CLIs / APIs → Workflows, edit the api.stripe.com tunnel rule, and set TLS mode to Intercept (decrypt + inject credential).

  2. Provision and trust the certificate authority. In intercept mode, the proxy terminates TLS with your host's certificate authority (CA), so your client must trust that CA:

    asg proxy ca rotate acme --yes                 # provisions the CA on first run (prompts without --yes)
    asg proxy ca download acme --output ./agent-security-ca.pem
    eval "$(asg proxy ca trust-shell acme)"         # points common TLS tools at the CA in this shell

  3. Send the request again. This time you do not send the Stripe key. The proxy injects it and scrubs it from the response:

    curl -i --cacert ./agent-security-ca.pem \
      --proxy-header "Proxy-Authorization: Bearer $(cat "$AGENT_SECURITY_PROXY_TOKEN_FILE")" \
      https://api.stripe.com/v1/customers

    Expected result: a Stripe response with a success status instead of 401, because the proxy added your Stripe key to the request.

Use intercept mode for domains where you need credential injection, path rules, or scrubbing on HTTPS. Use passthrough mode where domain-level control is enough, and for very large uploads, downloads, and long-lived streams. Over plain HTTP, the proxy injects credentials without any intercept setup. See HTTPS interception.

Troubleshooting​

Run the built-in diagnostics:

asg proxy doctor acme

asg proxy doctor checks:

  • Gateway reachability and whether proxy mode is enabled.
  • The number of stored credentials.
  • Your local proxy environment variables.
  • The interception CA's status.
  • The token file's permissions and the token's expiry.
  • When agent identity is enabled, the agent's session registration and whether the session is drift-blocked.

Each check reports pass, warn, or fail. A check that does not pass includes a suggested fix.

Next steps​

Contents

Edit this page

Need help?