Configuration

The gateway is configured entirely through environment variables — there is no config file. In the Docker Compose deployment, set them in a .env file or in your shell; docker-compose.yml passes them through to the gateway container.

Core

Variable	Required	Default	Description
GIG_BEARER_TOKEN	Yes	—	Bearer token MCP clients must present. The gateway refuses to start without it.
GIG_MASTER_KEY	Yes	—	Hex-encoded 32-byte master key (KEK) for the credential vault. Generate with openssl rand -hex 32. The gateway refuses to start without it.
GIG_LISTEN	No	:8080	Address the HTTP listener binds.
GIG_DB_PATH	No	gigmcp.db	Path to the SQLite database file. The Docker image sets this to /data/gigmcp.db, so in Compose the database lands in the gigmcp-data volume.
GIG_DATA_DIR	No	/data	Directory for extracted server binaries. In Docker Compose this is the gigmcp-data volume.
GIG_PROXY_PORT	No	8081	Port the embedded MITM egress proxy listens on (sandbox-facing; not published outside the container).
GIG_BOOTSTRAP_PATH	No	/usr/local/bin/bootstrap	Path to the in-sandbox bootstrap binary that configures networking and drops privileges before exec'ing the server.

danger

GIG_MASTER_KEY wraps every per-secret data-encryption key in the vault. It is never stored in the database. Losing it makes all stored credentials unrecoverable; leaking it undoes the vault's encryption. See vault.

Registry installs

Variable	Required	Default	Description
GIG_REGISTRY_INDEX_URL	With GIG_INSTALL	—	https:// or file:// location of the signed registry index.json.
GIG_REGISTRY_PUBKEY	With GIG_INSTALL	—	32-byte ed25519 hex public key used to verify the index signature (the trust root).
GIG_INSTALL	No	—	Comma-separated server refs installed at boot (auto-consented). Setting this without both registry variables is a startup error.

Demo / development

Variable	Required	Default	Description
GIG_DEMO_TOKEN	No	—	Seeds a demo credential for the bundled echo server on startup. Unset means no demo credential.
GIG_DEMO_ALLOW	No	api.example.com	Comma-separated allowed hosts for the demo credential.
GIG_ECHO_BIN	No	—	Legacy/dev fallback: path to an echo server binary to seed. Registry-driven install replaces seeding.

OIDC control plane

The dashboard's REST API (/api) is gated behind OIDC. When GIG_OIDC_ISSUER is unset, the control plane is disabled (/api returns an error) but the MCP endpoint keeps working with bearer auth. The three core variables are all-or-none — setting only some of them is a startup error. See authentication.

Variable	Required	Default	Description
GIG_OIDC_ISSUER	To enable /api	—	OIDC issuer URL, e.g. http://localhost:8082. Empty disables the control plane.
GIG_OIDC_CLIENT_ID	With issuer	—	OAuth client ID.
GIG_OIDC_CLIENT_SECRET	No	—	OAuth client secret. Optional — PKCE public clients (e.g. Zitadel) have none.
GIG_OIDC_CLIENT_SECRET_FILE	No	—	Path to a file containing the client secret (Docker secrets pattern). The plain variable wins if both are set.
GIG_OIDC_REDIRECT_URL	With issuer	—	Callback URL, e.g. https://gig.example.com/api/auth/callback.
GIG_OIDC_ADMIN_ROLE	No	gigmcp-admin	IdP role that maps to the gateway's admin role.
GIG_SESSION_TTL	No	168h	Session lifetime, as a Go duration. Must be positive.
GIG_PUBLIC_URL	No	http://localhost:8080 in compose	The gateway's browser-facing origin. An https:// prefix turns on Secure cookies. When OIDC is enabled and this is unset, it is derived from GIG_OIDC_REDIRECT_URL (scheme + host) so Secure-cookie behavior always matches the redirect origin.

:::note Dashboard as the entry point When users reach the gateway through the dashboard, point GIG_OIDC_REDIRECT_URL and GIG_PUBLIC_URL at the browser-facing origin (e.g. http://localhost:3000) so the OIDC callback lands on the right origin. :::

_FILE secrets

Compose environment variables are visible via docker inspect. For values supporting the _FILE pattern, you can instead point a <VAR>_FILE variable at a file (e.g. a Docker secret); the gateway reads and trims its contents. The plain variable always wins over the _FILE variant.

Currently implemented: GIG_OIDC_CLIENT_SECRET_FILE. The design calls for _FILE support on all sensitive values (including GIG_MASTER_KEY); that extension has not shipped yet — today the master key and bearer token are read from plain environment variables only.

Storage

The current storage backend is SQLite — zero-config, stored at GIG_DB_PATH. The store layer is written against a driver-agnostic repository interface, and the design record commits to a Postgres driver with the rule "no Postgres-only features in core," but only the SQLite driver is implemented today.

TLS notes

• Client → gateway: the compose deployment serves plain HTTP on port 8080. Terminate TLS in front of it (reverse proxy) for production; set GIG_PUBLIC_URL to the https:// origin so session cookies are marked Secure.
• Sandbox → proxy: the embedded egress proxy MITMs sandbox HTTPS traffic using a runtime-generated ECDSA P-256 CA, injected into sandboxes via NODE_EXTRA_CA_CERTS / SSL_CERT_FILE. This is internal to the gateway and needs no configuration. See egress proxy.

Container runtime requirements

These are already set in docker-compose.yml; you only need them if you write your own deployment:

Setting	Why
cap_add: NET_ADMIN	The gateway creates a veth pair per sandbox and moves the peer end into the sandbox's network namespace. No SYS_ADMIN or privileged mode is needed.
security_opt: seccomp=unconfined	bubblewrap needs unprivileged user namespaces, which Docker's default seccomp profile blocks. A scoped allow-userns profile is a planned follow-up; meanwhile an application-level seccomp-BPF filter inside each sandbox closes the namespace-escape and privilege-escalation vectors.
security_opt: apparmor=unconfined	Same reason — Docker's default AppArmor profile blocks userns creation.
security_opt: systempaths=unconfined	Unmasks /proc so bubblewrap can mount a fresh procfs in the sandbox's PID namespace.

See sandbox isolation for what the application-level filter denies and security model for the accepted residual risks.

Endpoints reference

Path	Auth	Purpose
/ and /mcp	GIG_BEARER_TOKEN	Legacy single MCP endpoint (current default surface)
/mcp/p/<slug>	Per-profile bearer token	Per-profile MCP endpoints
/api/	OIDC session	Control plane REST API; disabled when OIDC is unset