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

# Standalone

> Run Agentgateway as a standalone binary on any Linux, macOS, or Windows host.

Running Agentgateway as a standalone binary is the simplest deployment model. The proxy listens for MCP and A2A traffic, serves the admin UI, and exposes metrics and readiness endpoints — all from a single process.

## Prerequisites

To build from source you need:

* **Rust 1.86+** — install via [rustup](https://rustup.rs)
* **npm 10+** — required to build the admin UI

## Build from source

<Steps>
  <Step title="Build the admin UI">
    The UI is a separate npm project that gets embedded into the binary at compile time.

    ```bash theme={null}
    cd ui
    npm install
    npm run build
    ```
  </Step>

  <Step title="Build the binary">
    Return to the repository root and build a release binary with the `ui` feature enabled.

    ```bash theme={null}
    export CARGO_NET_GIT_FETCH_WITH_CLI=true
    make build
    ```

    This runs `cargo build --release --features ui` and places the binary at `./target/release/agentgateway`.
  </Step>

  <Step title="Verify the build">
    ```bash theme={null}
    ./target/release/agentgateway --version
    ```
  </Step>
</Steps>

## Running Agentgateway

<Tabs>
  <Tab title="Release binary">
    Pass a configuration file with the `-f` flag:

    ```bash theme={null}
    ./target/release/agentgateway -f config.yaml
    ```
  </Tab>

  <Tab title="cargo run">
    During development you can skip the explicit build step:

    ```bash theme={null}
    cargo run -- -f config.yaml
    ```

    <Note>
      `cargo run` compiles a debug build by default. For performance testing or production use, always use the release binary.
    </Note>
  </Tab>
</Tabs>

Once started, open your browser and navigate to `http://localhost:15000/ui` to access the admin UI.

## Configuration file

Agentgateway accepts a JSON or YAML configuration file. The example below is from `manifests/localhost-config.json` in the repository — it starts an SSE listener on port 8080 with JWT authentication and connects to a local XDS control plane:

```json localhost-config.json theme={null}
{
  "type": "xds",
  "xds_address": "http://127.0.0.1:9977",
  "metadata": {},
  "alt_xds_hostname": "agentgateway.default.svc.cluster.local",
  "listener": {
    "type": "sse",
    "host": "0.0.0.0",
    "port": 8080,
    "authn": {
      "type": "jwt",
      "issuer": ["me"],
      "audience": ["me.com"],
      "jwks": {
        "type": "local",
        "source": {
          "type": "file",
          "data": "manifests/jwt/pub-key"
        }
      }
    }
  }
}
```

## Static configuration options

The following fields under the `config` key control the server's built-in listeners. All values are strings in `ip:port` format.

| Field                  | Description                    | Default         |
| ---------------------- | ------------------------------ | --------------- |
| `config.adminAddr`     | Admin UI address               | `0.0.0.0:15000` |
| `config.statsAddr`     | Prometheus metrics address     | `0.0.0.0:15020` |
| `config.readinessAddr` | Readiness probe address        | `0.0.0.0:15021` |
| `config.workerThreads` | Number of Tokio worker threads | CPU count       |

### Example static config block

```yaml config.yaml theme={null}
config:
  adminAddr: "0.0.0.0:15000"
  statsAddr: "0.0.0.0:15020"
  readinessAddr: "0.0.0.0:15021"
  workerThreads: 4
```

## Environment variables

Several settings can be overridden with environment variables without changing the config file:

| Variable                       | Description                                                                    |
| ------------------------------ | ------------------------------------------------------------------------------ |
| `CARGO_NET_GIT_FETCH_WITH_CLI` | Use git CLI for Cargo dependency fetches (required in some corporate networks) |
| `DNS_EDNS0`                    | Enable or disable EDNS0 in the DNS resolver (`true` / `false`)                 |
| `VERSION`                      | Version string embedded in the binary at build time                            |
| `GIT_REVISION`                 | Git revision string embedded in the binary at build time                       |

## Session encryption

To enable encrypted session tokens, generate a 32-byte key and add it to your configuration:

```bash theme={null}
openssl rand -hex 32
```

```yaml config.yaml theme={null}
config:
  session:
    key: "<output from openssl rand -hex 32>"
```

<Warning>
  If `config.session.key` is not set, session tokens will not be encrypted. Always set this value in production deployments.
</Warning>

## Signal handling and graceful shutdown

Agentgateway responds to standard POSIX signals:

* **`SIGTERM`** — begins a graceful shutdown, waiting for in-flight requests to complete before exiting
* **`SIGINT`** (Ctrl+C) — same as `SIGTERM`; safe for interactive use

Two configuration fields control how long the process waits during shutdown:

```yaml config.yaml theme={null}
config:
  connectionTerminationDeadline: "30s"
  connectionMinTerminationDeadline: "5s"
```

## Configuration file watching

When running in static (non-XDS) mode, Agentgateway watches the config file for changes and reloads dynamically without restarting the process. This means you can update routing rules, policies, or backend addresses and have them take effect within seconds.

<Tip>
  For XDS-based deployments the control plane pushes updates over gRPC, so file watching is not used. See the [Kubernetes deployment guide](/deployment/kubernetes) for details.
</Tip>

## Production considerations

<CardGroup cols={2}>
  <Card title="Use the release build" icon="rocket">
    Always run `make build` (which sets `--release`) in production. Debug builds are significantly slower and produce much larger binaries.
  </Card>

  <Card title="Set worker threads" icon="microchip">
    Set `config.workerThreads` to match the number of CPU cores available to the process, especially when running inside a container with a CPU limit.
  </Card>

  <Card title="Secure the admin UI" icon="lock">
    Bind `config.adminAddr` to a loopback address (`127.0.0.1:15000`) or an internal network interface in production environments. The admin UI has no built-in authentication.
  </Card>

  <Card title="Enable session encryption" icon="key">
    Generate a `config.session.key` with `openssl rand -hex 32` and store it in a secrets manager. Rotate the key during scheduled maintenance windows.
  </Card>
</CardGroup>