# Configuration

All settings are environment variables. They are read case-insensitively from the process
environment and from an env file (the environment always wins). Unknown variables are ignored.
A blank value (`KEY=` in the env file) counts as unset for the optional secrets, URLs and
paths. List values accept commas or whitespace as separators.

## Which env file is read

The env file is never trusted just because it sits in the working directory: MCP clients start
stdio servers inside the project they work on, which can be a cloned repository carrying a
planted `.env` that switches off secret masking or the audit log or points `GITEA_URL` at
another host. The file is chosen in this order:

1. `--env-file PATH` of `serve` (and `setup`): used as given. It must exist and be a regular
   file.
2. The `AEGIS_ENV_FILE` environment variable: same rules.
3. `./.env`, but only when it is a regular file (not a symlink), owned by the user running the
   server, with no group or other permissions (mode 0600, which `setup` writes). Otherwise it is
   ignored and one warning goes to stderr that says why and how to fix it:
   `chmod 600 .env`, or pass `--env-file`.

Real environment variables take precedence over every file. A missing `./.env` is silent.
Containers pass settings as environment variables (`env_file:` in compose), not through the
working directory.

`.env.example` is the annotated template. `uv run aegis-gitea-mcp setup` fills one in for you
(see [getting-started.md](getting-started.md)). Secret settings never appear in logs, errors or
`repr` output.

Requirements that depend on how the server is started are checked at start, not on import:
`GITEA_TOKEN` for stdio, authentication for a non-loopback HTTP bind, complete OAuth settings
when OAuth is on.

## Gitea

| Variable | Default | Rules |
|---|---|---|
| `GITEA_URL` | required | `http` or `https`, must have a host, no credentials, query or fragment, and no whitespace, backslash or control characters. A trailing `/api/v1` is removed and the URL is rebuilt from its parsed parts. Plain `http` to a host that is not loopback starts, but `serve` prints a warning on stderr because every token then travels unencrypted. |
| `GITEA_TOKEN` | unset | Token for stdio and for admin-token mode on HTTP. Its scopes bound what the server can do. Required for stdio (exit code 2 without it). |

## Transport

| Variable | Default | Rules |
|---|---|---|
| `MCP_TRANSPORT` | `stdio` | `stdio` or `http`. `serve --transport` overrides it. |
| `MCP_HOST` | `127.0.0.1` | Bind address for HTTP. A non-loopback value refuses to start unless HTTP auth is configured. |
| `MCP_PORT` | `8080` | 1 to 65535. |
| `MCP_PATH` | `/mcp` | Starts with a single `/`, no query, spaces or trailing slash, not just `/`. |
| `MCP_BEARER_TOKEN` | unset | Static bearer token for HTTP (admin identity). At least 32 characters. Generate with `openssl rand -hex 32`. |
| `PUBLIC_BASE_URL` | unset | Public URL behind a reverse proxy. Same URL rules as `GITEA_URL`, and `https` unless the host is loopback. Required for OAuth. |
| `ALLOWED_HOSTS` | empty | Extra `Host` header values accepted behind a proxy. The loopback names with the port and the host of `PUBLIC_BASE_URL` are always allowed. Other `Host` values are rejected (DNS-rebinding protection). A non-loopback `MCP_HOST` with neither `PUBLIC_BASE_URL` nor `ALLOWED_HOSTS` logs a startup warning on stderr, because remote clients then get 421. |
| `FORWARDED_ALLOW_IPS` | `127.0.0.1` | Comma list of IP addresses or networks (or `*`) whose `X-Forwarded-For` and `X-Forwarded-Proto` headers are trusted. Set it to the address of the reverse proxy when it is not on the same host, for example a Docker network. Otherwise the per-IP rate limit sees the proxy address for every client: a request that carries `X-Forwarded-For` from a peer outside this list is not honoured and logs one warning ("add its address to FORWARDED_ALLOW_IPS"). `*` trusts every peer and logs a warning: only use it when the port is reachable solely from the proxy, since clients could otherwise spoof their IP. |

## Per-user OAuth (HTTP only)

| Variable | Default | Rules |
|---|---|---|
| `OAUTH_ENABLED` | `false` | When true, `GITEA_OAUTH_CLIENT_ID`, `GITEA_OAUTH_CLIENT_SECRET`, `TOKEN_ENCRYPTION_KEY` and `PUBLIC_BASE_URL` are required, or the server refuses to start (exit code 2, with the list of what is missing). |
| `GITEA_OAUTH_CLIENT_ID` | unset | Client id of the Gitea OAuth application (created by `setup`). |
| `GITEA_OAUTH_CLIENT_SECRET` | unset | Its client secret. |
| `TOKEN_ENCRYPTION_KEY` | unset | At least 32 characters. Encrypts the token store. The key cannot be rotated in place: a store written with another key stops startup (exit code 2) instead of being wiped, until you restore the original key or move `DATA_DIR/oauth-store.json` away, which signs every user out. |
| `OAUTH_SCOPES` | all `write:<category>` scopes | Granular Gitea scopes only (`read:` or `write:` plus activitypub, admin, issue, misc, notification, organization, package, repository, user). Anything else is rejected, because Gitea grants full access for unknown scope strings. Must not be empty. |
| `OAUTH_REDIRECT_ALLOWLIST` | empty | Comma list of redirect URIs MCP clients may register: exact URIs (`https://client.example/cb`) or prefixes ending in `/` that allow a whole host (`https://claude.ai/`). A bare origin without a path is refused. Empty accepts any https URI (and http on `localhost`, `127.0.0.1`, `[::1]`). With a list, https URIs must match it; loopback URIs stay allowed for native clients. Checked at registration and again at `/authorize`. |

`PUBLIC_BASE_URL` is also required for OAuth. The Gitea OAuth application's redirect URI is
`<PUBLIC_BASE_URL>/oauth/callback`.

OAuth-only deployments are supported: with `OAUTH_ENABLED=true` and neither `MCP_BEARER_TOKEN`
nor `GITEA_TOKEN`, every user brings their own Gitea token and admin-token mode is simply not
available (nothing falls back to it). `GITEA_TOKEN` stays required whenever admin-token mode is
reachable: with a static bearer, without any HTTP authentication, and on stdio.

Sign-in flow and limits: `/authorize` sends the browser to the consent page `/oauth/consent`,
which names the client and the redirect URI and needs an explicit approval (CSRF token, cookie
and an `Origin` that matches `PUBLIC_BASE_URL`) before the browser goes to Gitea; the callback
`/oauth/callback` completes only in that same browser. Issued `agm_` access tokens live 1 hour
and refresh tokens 30 days (rotated on use, reuse revokes the grant); authorization codes live 5
minutes and pending sign-ins 10 minutes. Bounds: 500 registered clients (10 redirect URIs and 8
KiB of metadata each), 1024 pending sign-ins and codes, 50 sessions per Gitea login, and per
client address 20 pending sign-ins and 20 registrations per hour. The consent form body is
limited to 16 KiB and must be `application/x-www-form-urlencoded`.

## State

| Variable | Default | Rules |
|---|---|---|
| `DATA_DIR` | `~/.local/state/aegis-gitea-mcp` (`/var/lib/aegis-mcp` in the image) | `~` is expanded. Holds the encrypted token store (`oauth-store.json`, mode 0600) and the audit log. A new directory is created with mode 0700; an existing one must belong to the running user and is tightened to 0700, otherwise OAuth startup fails. |
| `AUDIT_LOG_PATH` | `DATA_DIR/audit.log` | Path of the hash-chained audit log. See [audit-logging.md](audit-logging.md). The server opens it for append at startup and exits with code 2 and a message on stderr when it cannot. |

## Tool exposure

Everything is enabled by default. These settings only narrow it. A filtered tool is neither
listed nor callable.

| Variable | Default | Rules |
|---|---|---|
| `READ_ONLY` | `false` | Expose only read-only (GET) operations. `gitea_api_request` stays listed but accepts only GET. |
| `TOOLSETS` | `all` | Comma separated domains: `admin`, `repo`, `issue`, `pull`, `release`, `wiki`, `org`, `team`, `user`, `actions`, `hook`, `package`, `notification`, `misc`, or `all`. Unknown domains are rejected. `gitea_api_request` belongs to `misc`. |
| `DISABLED_TOOLS` | empty | Exact tool names to hide, lowercased on load. An unknown name is a startup error that lists the bad names. |

## Limits and safety

| Variable | Default | Rules |
|---|---|---|
| `REQUEST_TIMEOUT_SECONDS` | `30` | 1 to 600. Timeout of each Gitea request. |
| `MAX_TOOL_RESPONSE_ITEMS` | `200` | At least 1. Longer lists are cut and reported in `truncated`. |
| `MAX_TOOL_RESPONSE_CHARS` | `60000` | At least 1. Upper bound of one serialized result. |
| `MAX_BINARY_BYTES` | `5242880` | At least 1. Larger binary bodies fail with `payload_too_large`. |
| `SECRET_DETECTION_MODE` | `mask` | `off`, `mask` or `block`. See below. |
| `LOG_LEVEL` | `INFO` | `DEBUG`, `INFO`, `WARNING`, `ERROR` or `CRITICAL`. Logs go to stderr. |
| `EXPOSE_ERROR_DETAILS` | `false` | When true, the exception class name is added to internal and transport errors. Never a stack trace. Do not enable in production. |
| `RATE_LIMIT_PER_MINUTE` | `120` | At least 1. Per client on the HTTP MCP endpoint and on the unauthenticated OAuth endpoints (`/register`, `/authorize`, `/token`, `/revoke`, `/oauth/consent`, `/oauth/callback`), keyed by the client IP (an IPv6 client counts per /64) and, on the MCP endpoint, by a hash of the Authorization header. Excess requests get 429. Only the first rejected request per client and minute is written to the audit log. Tracking is in memory and bounded (idle clients are forgotten). |

Secret detection: `mask` replaces secret-like strings in results with a placeholder, `block`
withholds a whole result that contains one (`secret_blocked`), `off` disables pattern matching.
The server's own tokens (Gitea token, bearer token, OAuth client secret, the calling user's
token) and secret values you submit in a request body are always redacted by exact match. The
tools that exist to return a new credential (create token, runner registration token, OAuth
application, deploy token) are exempt from pattern masking so the credential stays usable.

## Profiles

Read-only assistant for issues and code:

```bash
READ_ONLY=true
TOOLSETS=repo,issue,pull,release,wiki
```

Everything except instance administration and credentials:

```bash
TOOLSETS=repo,issue,pull,release,wiki,org,team,hook,actions,package,notification,misc
DISABLED_TOOLS=gitea_user_create_token
```

(`gitea_user_create_token` must be a registered name, see [tools.md](tools.md); the server
refuses to start if a name in `DISABLED_TOOLS` does not exist.)