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.
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/ 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 — you must run an external IdP that does (Authentik, Keycloak, …). Only needed for the native Claude web connector. See doc/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.

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:

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

cp .env.example .env
# edit .env: FAMILIAR_HTTP_TOKEN (openssl rand -hex 32), FAMILIAR_DOMAIN,
#            cert resolver, 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

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.

Traefik (labels included)

docker-compose.yml already carries Traefik router labels. Set in .env:

FAMILIAR_DOMAIN=familiar.yourdomain.tld
TRAEFIK_CERTRESOLVER=letsencrypt

Traefik terminates HTTPS and forwards to the container's port 8080 on the proxy network. Your public URL is then https://familiar.yourdomain.tld/mcp.

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.