Skip to main content

Overview

Agents in a Modal Sandbox often need API keys. Prompt-injected code can read a key from the Sandbox’s environment and send it anywhere. With Formal, the key never enters the Sandbox:
  1. A Modal Sidecar runs the headless . Only the Sidecar receives a Modal OIDC token, which the Endpoint uses to log in.
  2. The main Sandbox container has no outbound network access except to the Sidecar. Its HTTP clients use the Sidecar as HTTPS_PROXY.
  3. A network rule forwards requests for the API hostname to a .
  4. A on the Connector adds the API key. and logs apply to every request.
The agent keeps calling the real API hostname, such as api.stripe.com.
This guide uses the Stripe API with a bearer key. The same setup works for any HTTP API and every Native User type.

Prerequisites

  • A Formal Connector with a public hostname that you can add a listener to.
  • A Modal workspace. Copy its workspace ID (ac-...) from the Modal dashboard.
  • The Modal Python SDK with Sidecar support (sb._experimental_sidecars).

Steps

1. Store the key on the Connector

Set STRIPE_API_KEY in the Connector’s environment. Remove the key from any Modal Secret that a Sandbox can use.

2. Create the resource, Native User, and listener

Verify: stripe appears under the Connector’s Reachable Resources.

3. Create the Modal OIDC integration

Go to OIDC Integrations, click Create Integration, and choose the Modal preset. Pin the claim condition to your workspace, environment, and app:
Map the integration to a new machine user. Copy the integrationoidc_... ID and the machine user’s user_... ID. Modal tokens use a fixed audience, so the Endpoint selects the integration with integration_id in its config. See OIDC integrations for every claim Modal issues.

4. Forward API traffic to the Connector

Linux Endpoints ignore pre_tcp, so pre_tls checks the hostname and user.

5. Build the Sidecar image

Copy the Ubuntu/Debian (x86, headless) package link from the Control Plane (Download > Linux). Sidecar images must be built before you create the Sidecar, so call .build(app).
The Endpoint serves Explicit Proxy mode only on loopback. socat exposes it on the Sidecar’s bridge address, which only containers in this Sandbox can reach. Modal containers have no /etc/machine-id, so the script creates one for the Endpoint’s device identity.

6. Create the Sandbox and Sidecar

Runtimes with their own certificate store need the CA too. For example, set NODE_EXTRA_CA_CERTS for Node.js. Verify: the script prints a Sandbox ID (sb-...). In the Control Plane, the machine user from step 3 shows a new device.

7. Verify the key stays out

Open a shell in the Sandbox with modal shell <SANDBOX_ID>:
In Logs, each request shows the Modal machine user and the stripe resource. The Modal claims, such as sandbox_id, are in input.user.oidc.claims for policies.

Operational notes

  • Set HTTPS_PROXY and HTTP_PROXY for your agent’s tools, as in the Sandbox above. The main container has no other route out.
  • Keep the Sandbox timeout under 48 hours, the lifetime of the Sidecar’s Modal token.
  • Sidecars are in Beta. The SDK exposes them as _experimental_sidecars.

Next Steps

Daytona

The same pattern with linked Daytona sandboxes

E2B

The same pattern with the Endpoint in an E2B sandbox