familiar/doc/deployment.md

# Deployment — familiar as a remote MCP server

familiar runs two ways from the **same** code and token store:

1. **Local (stdio)** — the default. How Claude Desktop / Claude Code / Cowork launch it. Nothing here changes; see [getting-started](getting-started.md).
2. **Remote (HTTP)** — opt-in via `familiar serve`. Streamable HTTP behind a TLS reverse proxy, gated by a bearer token (or external OAuth). This page covers (2).

Once it's running, see [doc/clients/](clients/) for exact per-client setup.

## Secure defaults

- **stdio unless told otherwise.** `familiar serve` (not the bare `familiar`) starts HTTP.
- **Loopback bind by default** (`127.0.0.1`). The Docker image binds `0.0.0.0` so the reverse proxy can reach it.
- **Fail closed.** familiar refuses to start without authentication. In bearer mode that means no `FAMILIAR_HTTP_TOKEN` → it won't boot; a non-loopback bind without a token is called out explicitly. The only override is the explicit `FAMILIAR_ALLOW_INSECURE_BIND=true` escape hatch.
- **Writes off over HTTP.** A network-reachable, LLM-driven endpoint keeps writes disabled unless you set `FAMILIAR_ENABLE_WRITES=true`. Local stdio keeps writes on.
- **Token never in the URL.** Clients authenticate with an `Authorization: Bearer <token>` header only.

## Authentication modes

`FAMILIAR_AUTH_MODE` picks how the HTTP transport authenticates:

- **`bearer`** (default) — one static token in `FAMILIAR_HTTP_TOKEN`. Simple, and every client below except Claude web supports it. Recommended.
- **`oauth`** — familiar runs as an OAuth 2.1 **resource server**: it validates incoming JWT access tokens against an external issuer's JWKS and serves `/.well-known/oauth-protected-resource/<path>` so OAuth-only clients can discover the authorization server. familiar is **not** an authorization server and does **no** Dynamic Client Registration (DCR) — the authorization side lives in an external IdP (Authentik, Keycloak, Gitea, …). Only needed for OAuth-only clients such as the native **Claude web** connector. See [doc/clients/claude-web.md](clients/claude-web.md).

### Using Gitea as the OAuth issuer

Gitea can act as the IdP for `oauth` mode — no code change, config only. Gitea is already an OIDC provider: it signs access tokens as **RS256 JWTs** (default), publishes its keys at `https://gitea.example.com/login/oauth/keys`, and serves OIDC discovery at `https://gitea.example.com/.well-known/openid-configuration`, so familiar's `JWTVerifier` can validate its tokens.

1. In Gitea, **Settings → Applications → Create OAuth2 application** (or admin-wide under **Site Administration → Applications**). Set the redirect URI(s) your MCP client needs. Note the generated **client ID** and **secret**.
2. Point familiar at Gitea:

   ```bash
   FAMILIAR_AUTH_MODE=oauth
   FAMILIAR_OAUTH_ISSUER=https://gitea.example.com          # no trailing /login/oauth
   FAMILIAR_OAUTH_RESOURCE=https://familiar.example.com     # this server's public URL
   FAMILIAR_OAUTH_AUDIENCE=<gitea-oauth-app-client-id>      # Gitea sets aud to the client ID, not the resource URL
   # FAMILIAR_OAUTH_JWKS_URI is discovered from the issuer's OIDC metadata; leave unset.
   ```

   `FAMILIAR_OAUTH_AUDIENCE` matters: Gitea puts the OAuth **application's client ID** in the token's `aud`, which differs from familiar's default (the resource URL). If you get *invalid token / audience mismatch*, decode a real access token (`jwt.io`) and set `FAMILIAR_OAUTH_AUDIENCE` to whatever its `aud` actually is.

> **Caveat — no DCR.** Gitea does **not** support Dynamic Client Registration. Clients that let you paste a pre-registered client ID/secret (Claude Desktop/Code, VS Code, your own scripts) work fine with Gitea. The **claude.ai web** custom connector *requires* DCR, so Gitea alone can't back it — you'd need a DCR-capable IdP (Authentik/Keycloak) or a DCR proxy in front of Gitea. See [doc/clients/claude-web.md](clients/claude-web.md).

## Environment variables

| Variable | Default | Meaning |
| --- | --- | --- |
| `FAMILIAR_HTTP_HOST` | `127.0.0.1` | Bind address (image sets `0.0.0.0`). |
| `FAMILIAR_HTTP_PORT` | `8080` | Bind port. |
| `FAMILIAR_HTTP_PATH` | `/mcp` | MCP endpoint path. |
| `FAMILIAR_AUTH_MODE` | `bearer` | `bearer` or `oauth`. |
| `FAMILIAR_HTTP_TOKEN` | *(unset)* | Bearer token. **Required** in bearer mode. |
| `FAMILIAR_ALLOW_INSECURE_BIND` | `false` | Allow a bind without a token (don't). |
| `FAMILIAR_OAUTH_ISSUER` | *(unset)* | Authorization-server URL (oauth mode). |
| `FAMILIAR_OAUTH_RESOURCE` | *(unset)* | This server's public URL, e.g. `https://familiar.example.com` (oauth mode). |
| `FAMILIAR_OAUTH_AUDIENCE` | = resource | Expected token audience (oauth mode). |
| `FAMILIAR_OAUTH_JWKS_URI` | *(discovered)* | JWKS URL; if unset, discovered from the issuer's OIDC metadata. |
| `FAMILIAR_DATA_DIR` | per-user | Where `token.enc` + `key` + `audit.log` + write toggle live. Image sets `/data`. |
| `FAMILIAR_ENABLE_WRITES` | on (stdio) / off (HTTP) | `true` allows guarded writes; over HTTP it's off unless set. |

`/healthz` is an unauthenticated liveness probe (used by the Docker healthcheck and reverse-proxy probes). It returns only `{"status":"ok","server":"familiar","version":"…"}` — no account data. Every MCP call under `FAMILIAR_HTTP_PATH` requires authentication.

## One-time login (why it happens on the host)

EVE SSO login is a browser PKCE flow with a `localhost` callback — awkward inside a container. Authenticate **once on a machine with a browser**, then hand the resulting token store to the container. The container only ever *refreshes* tokens.

```bash
uv run familiar login          # opens the browser, writes token.enc + key
uv run familiar status         # confirm the character(s)
```

Then make that data dir available to the container. Point `FAMILIAR_DATA_DIR_HOST` at it, or copy `token.enc` + `key` into `./data`:

```bash
mkdir -p ./data
# Linux/macOS host default:
cp ~/.local/share/familiar/{token.enc,key} ./data/
# Windows host default:
#   copy %LOCALAPPDATA%\familiar\token.enc .\data\ ; copy %LOCALAPPDATA%\familiar\key .\data\
```

**Headless host?** Use `uv run familiar login --no-browser`: it prints the SSO URL, you authorize in any browser, and paste the redirected callback URL back on stdin. The `/data` volume is mounted read-write so token refresh (which rotates the refresh token) and the audit log persist.

## Published images (Gitea)

`.gitea/workflows/docker.yml` builds, smoke-tests (non-root, `/healthz` 200, MCP 401 without / 200 with a token), and pushes on every push to `main`/`dev`:

| Branch | Tags |
| --- | --- |
| `main` | `git.hiddenden.cafe/hiddenden/familiar:latest`, `:main`, `:sha-<12>` |
| `dev`  | `git.hiddenden.cafe/hiddenden/familiar:dev`, `:sha-<12>` |

Pushing needs a Gitea PAT with `write:package` scope stored as the repo secret `REGISTRY_TOKEN`. Pick the channel with `FAMILIAR_IMAGE` in `.env`.

## Run with Docker Compose

```bash
cp .env.example .env
# edit .env: FAMILIAR_HTTP_TOKEN (openssl rand -hex 32),
#            FAMILIAR_IMAGE (:latest prod / :dev dev channel)

docker network create proxy    # once, if your reverse proxy doesn't own it yet

docker login git.hiddenden.cafe
docker compose pull && docker compose up -d
#   ...or build locally instead:  docker compose up -d --build

docker compose logs -f familiar
```

The compose service joins the external `proxy` network (not published to the host), runs non-root with a `read_only` rootfs + tmpfs `/tmp`, `no-new-privileges` and `cap_drop: ALL`, and healthchecks `GET /healthz`.

## TLS reverse proxy

familiar terminates no TLS itself — a proxy does. Streamable HTTP holds a long-lived response open, so **disable buffering** and use a **generous read timeout** on the MCP path.

### nginx

```nginx
location /mcp {
    proxy_pass http://127.0.0.1:8080/mcp;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffering off;          # stream events straight through
    proxy_read_timeout 3600s;     # don't cut long-lived MCP sessions
}
```

(If you run the container on the `proxy` network instead of publishing to the host, point `proxy_pass` at `http://familiar:8080/mcp`.)

### Caddy

```
familiar.yourdomain.tld {
    reverse_proxy familiar:8080
}
```

Caddy fetches and renews the certificate automatically and streams by default.

### Pangolin

The compose service exposes `:8080` on the shared external `proxy` network and carries no proxy-specific labels. In Pangolin, add a resource for `familiar` that forwards to `http://familiar:8080` (target the container's `/mcp` path), and let Pangolin terminate HTTPS. Make sure Pangolin's own container is attached to the same `proxy` network so it can reach the service by name. Your public URL is then `https://familiar.yourdomain.tld/mcp`.

Because streamable HTTP holds a long-lived response open, raise the read/response timeout on the familiar resource and disable response buffering if the option is exposed (same reasoning as the nginx `proxy_read_timeout` / `proxy_buffering off` above).

## Operational notes

- **Rotate the token** by changing `FAMILIAR_HTTP_TOKEN` and restarting; update every client header.
- **Restrict inbound** at the proxy/firewall to the clients you expect.
- **Watch** `docker compose logs` for `401` auth failures and `/data/audit.log` for the write trail.
- **Re-login** (host) whenever you change requested scopes, then refresh the `/data` token store.