Skip to main content
E2B sandboxes are isolated virtual machines you create from code to run an agent. The agent in a sandbox runs commands that a prompt can influence, so any API key you give the sandbox can leak through a prompt injection. With Agent Vault, you don’t give the sandbox any API keys. E2B’s bring your own proxy option sends the sandbox’s outbound connections to a SOCKS5 proxy you run. You run an Agent Vault proxy with its SOCKS5 port turned on, and the proxy attaches the real credential to requests for the APIs you allowed. E2B connects to the proxy from its own servers, not from inside the sandbox, so nothing in the sandbox is configured to use the proxy, and code in the sandbox can’t send traffic that skips it. For each run, your code does the following:
  1. Gets the proxy’s certificate authority (CA) from Infisical
  2. Creates an Agent Vault session for the run (learn more about sessions)
  3. Creates a sandbox that sends its traffic to the proxy, with the session token as the SOCKS5 password
  4. Adds the proxy’s CA to the sandbox’s trust store, and runs the agent
  5. Revokes the session and kills the sandbox when the agent finishes
One proxy serves every sandbox, so you set it up once.
E2B only connects to proxies that are reachable from the internet, so the proxy can’t be on a private network. These parts of the setup protect the session tokens and the proxy:
  • 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
You can also use a firewall to limit the SOCKS5 port to the Google Cloud address ranges of the regions your sandboxes run in, as E2B describes. E2B publishes no ranges for its AWS region, and other Google Cloud customers share the Google Cloud ranges, so the firewall adds to these protections rather than replacing them.

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_KEY environment 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

1
In Agent Vault, go to Proxies and select Create Proxy.
2
Enter a Name, such as sandboxes.
3
Select Create, then copy the proxy token from the Proxy Token dialog. Infisical shows the token only once.

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.
1
In Agent Vault, go to Access Control > Machine Identities and select Add Machine Identity.
2
On the Create New tab, enter a Name, choose Member in Role, then select Create. Infisical creates the machine identity with Universal Auth and opens its page.
To use a machine identity that already exists in your organization, select the Assign Existing tab instead.
3
On the machine identity’s page, select Universal Auth under Authentication. Copy the Client ID, then select Add Client Secret and copy the client secret.
4
Go to Access Bundles and open the access bundle the agent uses. Select Options > Manage Access, then select Grant Access. Select the machine identity, then select Grant Access.

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’s us-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:
Save the proxy token in /etc/infisical/agent-vault-proxy.env:
Run 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.
To check that the proxy is up, such as in a load balancer’s health check, open a TCP connection to port 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.
To serve your own certificate on the SOCKS5 port instead, pass --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:Learn more about the SOCKS5 port’s certificate.

Step 3: Give your code the credentials

Set INFISICAL_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 name
  • https://app.infisical.com: if you use EU Cloud or self-host Infisical, the URL of your instance
The function adds the proxy’s CA to the sandbox’s system trust store, and sets the variables that 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:
The response lists Anthropic’s models, even though the sandbox has no Anthropic API key and no settings for the proxy.
Each run now gets its own sandbox and session. The session token never enters the sandbox, and your code revokes the session when the run ends.
To check which requests the sandbox made, set up session logs, then view the session’s logs in Agent Vault. Requests that got a credential have the outcome Brokered.

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:
1
Set 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.
2
Add the agent’s settings to SANDBOX_ENV. For Claude Code, add these:
3
Call the function with the agent’s non-interactive command, such as claude -p 'Reply with the word OK.' --permission-mode bypassPermissions.
The agent calls its APIs the same way it does without Agent Vault, and E2B sends the connections to the proxy, so the agent doesn’t need HTTPS_PROXY or infisical agent-vault run.

Security considerations

Network access from the sandbox

The sandbox can look up hostnames over DNS at 8.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 80 and 443 to the proxy, so the sandbox can’t reach a service on any other port
To allow only the hosts that services in the session’s access bundle cover, set the traffic policy to Access bundle hosts only. Add any other hosts the agent needs, such as 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

If 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:
E2B sent the proxy an IP address instead of a hostname, so HTTPS requests fail with a certificate error, and the proxy can’t match the request to a service. The proxy’s log shows 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.
The proxy refused the connection before any request. Check the proxy’s log for one of these lines:
  • agent-vault: refused, the session is no longer valid: the session expired or was revoked
  • agent-vault: refused, Infisical rejected this proxy's token: someone rotated or revoked the proxy’s token, so restart the proxy with the new token
  • agent-vault: refused, the session could not be resolved: the proxy couldn’t reach Infisical to check the session
  • agent-vault: a client spoke plain SOCKS5 to the TLS port: the sandbox’s egress_proxy has no tls setting
If none of these lines appears, the password might not be a session token, or E2B might not trust the SOCKS5 port’s certificate. Start the proxy with --log-level debug to log these refusals too.
The session expired or was revoked while the sandbox was running. Set the session’s ttl a few minutes longer than the sandbox’s timeout, so the session lasts as long as the sandbox can run.
If the proxy’s traffic policy is Access bundle hosts only, the proxy blocks hosts that no service in the access bundle covers. Add a service for the host, or add the host to the proxy’s exceptions.If the 403 says 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.
E2B only sends connections on ports 80 and 443 to the proxy. Use the service’s HTTPS endpoint on port 443 instead.
The tool doesn’t read the system trust store or the variables the function sets. Java programs use their own keystore, and some Rust programs have a built-in certificate list. Add the proxy’s CA to the tool’s own trust settings.
Updating a running sandbox’s network settings with 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.
The proxy serves your own CA, which Infisical doesn’t have. With your own CA, read the certificate you passed with --ca-cert from a file instead.

Next steps

Proxies

Learn more about the proxy’s SOCKS5 port and its settings.

Session logs

Record every request an agent makes during a session.