- Gets the proxy’s certificate authority (CA) from Infisical
- Creates an Agent Vault session for the run (learn more about sessions)
- Creates a sandbox that sends its traffic to the proxy, with the session token as the SOCKS5 password
- Adds the proxy’s CA to the sandbox’s trust store, and runs the agent
- Revokes the session and kills the sandbox when the agent finishes
Why the proxy can be reachable from the internet
Why the proxy can be reachable from the internet
- TLS on the SOCKS5 port: The SOCKS5 port only accepts TLS, so the session token and the traffic are encrypted on the way to the proxy
- No token in the sandbox: E2B holds the session token on its servers, so the agent can’t read it
- Short sessions: Your code creates a session for each run and revokes it when the run ends, so a leaked token only works until then
- A local HTTP port: The proxy’s HTTP port stays local to the proxy’s machine, and only the SOCKS5 port is public
- Private destinations blocked: Through the SOCKS5 port, the proxy refuses requests to private and internal addresses, such as cloud metadata endpoints, unless a service in the session’s access bundle names the host
Prerequisites
- The Admin role in Agent Vault
- An access bundle with a service for each key the agent uses, including its model provider’s key, such as Anthropic for Claude Code (see the quickstart)
- An E2B account with bring your own proxy turned on (E2B lists it as a private beta, so you may need to ask E2B to turn it on)
- An E2B API key in the
E2B_API_KEYenvironment variable on the machine that runs your code - The E2B SDK version 2.57.0 or later for your language: Python (with
requests) or TypeScript - A Linux machine or Kubernetes cluster to run the proxy, reachable from the internet, with a DNS name that points to it
- For the systemd setup, the Infisical CLI installed on that machine
Step 1: Set up Agent Vault
Create a proxy
sandboxes.Create a machine identity for your code
Your code creates a session for each run as a machine identity. Give the machine identity the Member role and access to only your access bundle, because an Agent Vault admin can create sessions for every access bundle.Step 2: Run the proxy on a public machine
Run the proxy where E2B can reach it from the internet, with its SOCKS5 port turned on. E2B runs sandboxes in Google Cloud’sus-west1 region by default, so a machine in or near that region adds the least latency to each request.
These commands start the proxy with its SOCKS5 port on port 1080. With --socks5-tls-name, the proxy makes the port’s TLS certificate from its CA for the DNS name you pass. Replace <proxy-dns-name> with the machine’s DNS name, and <your-instance-url> with the URL of your Infisical instance:
- systemd
- Docker
- Kubernetes
/etc/infisical/agent-vault-proxy.env:sudo chmod 600 /etc/infisical/agent-vault-proxy.env so that only root can read the file. Then save this unit as /etc/systemd/system/agent-vault-proxy.service:--listen-host 127.0.0.1 keeps the HTTP port local to the machine. Run sudo systemctl enable --now agent-vault-proxy to start the proxy now and every time the machine boots.1080.
When the proxy starts, it logs agent-vault: proxy listening, with the proxy’s ID in the proxyId field, then agent-vault: SOCKS5 listening. To read the log, run journalctl -u agent-vault-proxy for systemd, docker logs agent-vault-proxy for Docker, or kubectl logs deploy/agent-vault-proxy for Kubernetes.
Copy the proxy’s ID for Step 4.
--socks5-tls-cert and --socks5-tls-key in place of --socks5-tls-name. Then change the tls setting in Step 4 to match the certificate:Step 3: Give your code the credentials
SetINFISICAL_UNIVERSAL_AUTH_CLIENT_ID and INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET to the machine identity’s client ID and client secret, in the environment of the code that creates your sandboxes. Your code never passes these credentials to a sandbox.
The proxy token stays on the proxy’s machine, so your code doesn’t need it.
Step 4: Run a command in a sandbox
This function runs one shell command in a new sandbox and returns the command’s output. Replace the values at the top:<access-bundle-name>: your access bundle’s name<proxy-id>: the proxy’s ID from Step 2<proxy-dns-name>: the proxy machine’s DNS namehttps://app.infisical.com: if you use EU Cloud or self-host Infisical, the URL of your instance
agent-vault run sets for the tools that don’t read that store.
To keep the same CA when you rotate the proxy’s token, use your own CA. Infisical doesn’t have your own CA, so read its certificate from a file instead of getting it from Infisical.
For more about creating sessions from code, see Create sessions with the API.
Step 5: Verify it works
Call the function with a request to an API in the access bundle. This example calls the Anthropic API, which returns a list of models only if the request has an API key. If your access bundle doesn’t have an Anthropic service, replace the URL with the URL of an API that the access bundle has a service for:Step 6: Run an agent
To run an agent such as Claude Code, start the sandbox from an E2B template that has the agent installed:TEMPLATE at the top of the code from Step 4 to the template’s name. For Claude Code, use claude, a template E2B provides with Claude Code installed. For another agent, build a template with the agent installed.SANDBOX_ENV. For Claude Code, add these:claude -p 'Reply with the word OK.' --permission-mode bypassPermissions.HTTPS_PROXY or infisical agent-vault run.
Security considerations
Network access from the sandbox
The sandbox can look up hostnames over DNS at8.8.8.8, which E2B lets through without the proxy, so an agent can still send data out in the names it looks up, though never a credential. To limit DNS, see E2B’s DNS settings.
Every other connection goes through the proxy:
- Hosts through the proxy: under the default traffic policy, Any host, the proxy forwards the sandbox’s requests to any host on the internet
- Ports: E2B only sends connections on ports
80and443to the proxy, so the sandbox can’t reach a service on any other port
registry.npmjs.org, to the proxy’s exceptions.
Compromised sandboxes or leaked tokens
The session token is in your code and in E2B’s settings for the sandbox, not in the sandbox. If you think a session token leaked, revoke the session. The proxy token is only on the proxy’s machine. If you think someone took control of that machine, rotate the proxy’s token.Troubleshooting
The proxy's systemd service fails to start
The proxy's systemd service fails to start
sudo systemctl status agent-vault-proxy shows status=203/EXEC, systemd couldn’t find the Infisical CLI. Run which infisical to find your CLI’s path. In /etc/systemd/system/agent-vault-proxy.service, replace infisical at the start of the ExecStart= line with that path, then reload and restart the proxy:Requests fail with a certificate error, or reach the API without a credential
Requests fail with a certificate error, or reach the API without a credential
closed a SOCKS5 connection the proxy can't handle with a TLS handshake error for the host’s IP address.E2B only sends hostnames for traffic that a domain entry allows, so create the sandbox with allow_out set to ["*"] and deny_out set to ["0.0.0.0/0"], as the function in Step 4 does.Connections from the sandbox fail right away
Connections from the sandbox fail right away
agent-vault: refused, the session is no longer valid: the session expired or was revokedagent-vault: refused, Infisical rejected this proxy's token: someone rotated or revoked the proxy’s token, so restart the proxy with the new tokenagent-vault: refused, the session could not be resolved: the proxy couldn’t reach Infisical to check the sessionagent-vault: a client spoke plain SOCKS5 to the TLS port: the sandbox’segress_proxyhas notlssetting
--log-level debug to log these refusals too.Requests fail with a 403 partway through a run
Requests fail with a 403 partway through a run
ttl a few minutes longer than the sandbox’s timeout, so the session lasts as long as the sandbox can run.Requests to a host fail with a 403 from the start
Requests to a host fail with a 403 from the start
the destination is a private or internal address, the host resolves to an internal address, such as a private network or the proxy’s own machine. The SOCKS5 port refuses those for every host that no service covers, including exceptions. Add a service for the host, or start the proxy with --socks5-allow-private-destinations.A service on a port other than 80 or 443 doesn't work
A service on a port other than 80 or 443 doesn't work
80 and 443 to the proxy. Use the service’s HTTPS endpoint on port 443 instead.A tool in the sandbox rejects the proxy's certificate
A tool in the sandbox rejects the proxy's certificate
The sandbox's traffic stops going through the proxy
The sandbox's traffic stops going through the proxy
update_network (updateNetwork in TypeScript) replaces all of them. If the update doesn’t include egress_proxy, E2B sends the sandbox’s traffic out directly. Include the same egress_proxy, with its tls setting, in every update.Getting the CA from Infisical fails with a 409
Getting the CA from Infisical fails with a 409
--ca-cert from a file instead.