> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Keep API Keys Out of Modal Sandboxes

> Run the Formal Endpoint in a Modal Sidecar with Modal OIDC so a Connector injects API keys outside the Sandbox

## 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 [Formal Endpoint](https://docs.formal.ai/docs/glossary/index.md#formal-endpoint).
   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](https://docs.formal.ai/docs/guides/network-rules.md) forwards requests for the API
   hostname to a [Connector](https://docs.formal.ai/docs/glossary/index.md#connector).
4. A [Native User](https://docs.formal.ai/docs/glossary/index.md#native-user) on the Connector adds the API key.
   [Policies](https://docs.formal.ai/docs/glossary/index.md#policy) and logs apply to every request.

The agent keeps calling the real API hostname, such as `api.stripe.com`.

```text theme={"languages":{"custom":["/languages/cel.json","/languages/rego.json"]}}
main container (no secrets, no egress)
  HTTPS_PROXY=http://formal-endpoint:3128
    -> Sidecar "formal-endpoint" (Modal OIDC token, Formal Endpoint)
         network rule: api.stripe.com -> forward_to_connector
      -> Formal Connector (STRIPE_API_KEY in its environment)
           Native User sets Authorization: Bearer $STRIPE_API_KEY
        -> 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](https://docs.formal.ai/docs/guides/core-concepts/resources/native-users.md#supported-credential-types).

### Modal features used

| Feature | Role |
| - | - |
| [Sandbox Sidecars](https://modal.com/docs/guide/sandbox-sidecars) (Beta) | Runs the Endpoint in a separate container. Code in the Sandbox cannot read or change it. |
| `include_oidc_identity_token=True` on the Sidecar | Gives only the Endpoint a workload identity. The main container never receives a token. |
| `outbound_cidr_allowlist=[]` on the Sandbox | Blocks all egress. Traffic to Sidecars is exempt, so the proxy still works. |
| `outbound_domain_allowlist` on the Sidecar | Lets the Sidecar reach only Formal and the Connector. |
| [Modal OIDC](https://modal.com/docs/guide/oidc-integration) | Issuer `https://oidc.modal.com`, with the fixed audience `oidc.modal.com`. |

## 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

```hcl theme={"languages":{"custom":["/languages/cel.json","/languages/rego.json"]}}
resource "formal_resource" "stripe" {
  name       = "stripe"
  technology = "http"
  hostname   = "api.stripe.com"
  port       = 443
}

resource "formal_resource_tls_configuration" "stripe" {
  resource_id = formal_resource.stripe.id
  tls_config  = "verify-full"
}

resource "formal_native_user_v3" "stripe" {
  resource_id = formal_resource.stripe.id
  label       = "stripe-api-key"

  http_bearer {
    header = "Authorization"
    token {
      environment_variable = "STRIPE_API_KEY"
    }
  }
}

resource "formal_resource_native_user_selection" "stripe" {
  resource_id = formal_resource.stripe.id
  cel         = "\"${formal_native_user_v3.stripe.id}\""
}

resource "formal_connector_listener" "stripe" {
  connector_id = var.connector_id
  name         = "stripe-listener"
  port         = 443
}

resource "formal_connector_listener_rule" "stripe" {
  connector_listener_id = formal_connector_listener.stripe.id
  type                  = "resource"
  rule                  = formal_resource.stripe.id
}
```

**Verify:** `stripe` appears under the Connector's **Reachable Resources**.

### 3. Create the Modal OIDC integration

Go to [OIDC Integrations](https://app.formal.ai/oidc-integrations), click
**Create Integration**, and choose the **Modal** preset. Pin the claim
condition to your workspace, environment, and app:

```cel theme={"languages":{"custom":["/languages/cel.json","/languages/rego.json"]}}
claims.aud == 'oidc.modal.com' &&
claims.workspace_id == '<WORKSPACE_ID>' &&
claims.environment_name == 'main' &&
claims.app_name == '<APP_NAME>'
```

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](https://docs.formal.ai/docs/guides/integrations/oidc.md)
for every claim Modal issues.

### 4. Forward API traffic to the Connector

```hcl theme={"languages":{"custom":["/languages/cel.json","/languages/rego.json"]}}
resource "formal_network_rule" "stripe_modal" {
  name   = "stripe-modal-sandboxes"
  status = "active"

  cel_expression = <<-EOT
    {
      "condition": {
        "pre_tls": hostname == "api.stripe.com" &&
          user.id == "<MODAL_MACHINE_USER_ID>",
        "post_tls": true
      },
      "outputs": {
        "resource_name": "stripe",
        "forward_to_connector": true
      }
    }
  EOT
}
```

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)`.

```python theme={"languages":{"custom":["/languages/cel.json","/languages/rego.json"]}}
import modal

APP_NAME = "<APP_NAME>"
INTEGRATION_ID = "<INTEGRATION_ID>"
CONNECTOR_HOSTNAME = "<CONNECTOR_HOSTNAME>"

ENDPOINT_CONFIG = f"""\
auth_mode = "oidc"

[oidc]
env = "MODAL_IDENTITY_TOKEN"
integration_id = "{INTEGRATION_ID}"

[transparent_proxy]
enable = true
enforce = true
fail = "closed"
"""

SIDECAR_CMD = """\
set -euo pipefail
test -s /etc/machine-id || tr -d - < /proc/sys/kernel/random/uuid > /etc/machine-id
ip=$(ip -4 -o addr show scope global | awk '{print $4}' | cut -d/ -f1 | head -1)
socat TCP-LISTEN:3128,bind=$ip,fork,reuseaddr TCP:127.0.0.1:3128 &
exec formal agent --headless --explicit-proxy=127.0.0.1:3128
"""

app = modal.App.lookup(APP_NAME, create_if_missing=True)

endpoint_image = (
    modal.Image.debian_slim()
    .apt_install("ca-certificates", "curl", "iproute2", "socat")
    .run_commands(
        "curl -fsSL '<FORMAL_ENDPOINT_PACKAGE_URL>' -o /tmp/formal.deb",
        "apt-get install -y /tmp/formal.deb",
        "mkdir -p /root/.formal",
    )
    .run_commands(f"cat > /root/.formal/config.toml <<'EOF'\n{ENDPOINT_CONFIG}EOF")
)
endpoint_image.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

```python theme={"languages":{"custom":["/languages/cel.json","/languages/rego.json"]}}
import base64

agent_image = modal.Image.debian_slim().apt_install("ca-certificates", "curl")
proxy = "http://formal-endpoint:3128"

sb = modal.Sandbox.create(
    "sleep", "infinity",
    app=app,
    image=agent_image,
    outbound_cidr_allowlist=[],  # no egress; Sidecars stay reachable
    env={"HTTPS_PROXY": proxy, "HTTP_PROXY": proxy},
)

sidecar = sb._experimental_sidecars.create(
    "bash", "-c", SIDECAR_CMD,
    name="formal-endpoint",
    image=endpoint_image,
    include_oidc_identity_token=True,
    outbound_domain_allowlist=["api.formal.ai", CONNECTOR_HOSTNAME],
)

# Trust the Endpoint's CA. Only the public certificate leaves the Sidecar.
ca = sidecar.exec("bash", "-c",
    "until test -s /var/lib/formal/ca/localca-cert.pem; do sleep 1; done; "
    "cat /var/lib/formal/ca/localca-cert.pem")
ca.wait()
pem = base64.b64encode(ca.stdout.read().encode()).decode()
sb.exec("bash", "-c",
    f"echo {pem} | base64 -d > /usr/local/share/ca-certificates/formal.crt "
    "&& update-ca-certificates").wait()
print(sb.object_id)
```

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>`:

```bash theme={"languages":{"custom":["/languages/cel.json","/languages/rego.json"]}}
env | grep -ci -E 'stripe|formal|identity'
# Expected: 0

curl -s 'https://api.stripe.com/v1/customers?limit=1' | head -c 200
# Expected: a Stripe JSON response, although the Sandbox sent no key

curl -s --noproxy '*' -m 5 https://api.stripe.com || echo blocked
# Expected: blocked
```

In [Logs](https://app.formal.ai/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

> [card] [Daytona](https://docs.formal.ai/docs/guides/example-use-cases/sandbox-credential-injection/daytona.md)
>
> The same pattern with linked Daytona sandboxes

> [card] [E2B](https://docs.formal.ai/docs/guides/example-use-cases/sandbox-credential-injection/e2b.md)
>
> The same pattern with the Endpoint in an E2B sandbox


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.