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

# Sandbox proxy

> Install the runagain proxy in your sandbox to capture outbound HTTP calls into your traces.

The `runagain` package is a transparent HTTP(S) proxy you drop into your agent's sandbox. It
captures every outbound API/tool call and ships it to RunAgain as a span in the agent's trace. See
[Probes](/concepts/probes) for the concept.

It bundles [mitmproxy](https://mitmproxy.org) — there is nothing else to install or run.

## Install

```bash theme={null}
pip install runagain-proxy
```

## Run your agent through it

Wrap your agent's command with `runagain-proxy run`:

```bash theme={null}
runagain-proxy run -- python my_agent.py
```

`runagain-proxy run` starts the bundled proxy, points the child process at it
(`HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY`), runs your command, and tears the proxy down on exit.

<Steps>
  <Step title="Set your key and collector">
    ```bash theme={null}
    export RUNAGAIN_API_KEY=sk_…
    export RUNAGAIN_COLLECTOR=https://ingest.runagain.ai
    ```
  </Step>

  <Step title="Trust the CA (once per image)">
    HTTPS interception needs the proxy's CA certificate in the sandbox trust store:

    ```bash theme={null}
    runagain-proxy trust
    ```

    Prints the certificate path and install steps for common base images (Debian/Ubuntu, Alpine, RHEL).
  </Step>

  <Step title="Run">
    ```bash theme={null}
    runagain-proxy run -- python my_agent.py
    ```

    Outbound calls now appear in the agent's traces with an `http` badge.
  </Step>
</Steps>

## Configuration

Set via environment variables (or overridden per session by the backend):

| Variable               | Default | Meaning                                          |
| ---------------------- | ------- | ------------------------------------------------ |
| `RUNAGAIN_API_KEY`     | —       | Project write key (`sk_…`). Required.            |
| `RUNAGAIN_COLLECTOR`   | —       | Collector base URL. Required.                    |
| `RUNAGAIN_MODE`        | `learn` | `learn` (capture) or `passthrough` (proxy only). |
| `RUNAGAIN_FIXTURE_SET` | —       | Name the captured set (e.g. `v1`).               |
| `RUNAGAIN_SCENARIO`    | —       | Scenario label for grouping.                     |
| `RUNAGAIN_RUN_ID`      | —       | Caller-supplied run grouping.                    |

On startup the proxy registers with `POST /sessions` and applies any backend-configured policy, so
you can change mode or fixture set without rebuilding the sandbox.

## Trace matching

Captured calls nest under the span that made them **only if** the agent's HTTP client propagates the
W3C `traceparent` header — standard for any OpenTelemetry-instrumented client. Without it, captures
fall back to a degraded, best-effort match. See [OTLP → trace context](/integrations/otlp).

<Warning>
  Probes capture request and response bodies. Secret headers (Authorization, Cookie, API keys) are
  redacted inside the sandbox before anything leaves it, but review your capture scope for sensitive
  payload bodies, and use `passthrough` for traffic you don't want recorded.
</Warning>