FAQ

Why is Gig'MCP Linux-only?

The entire isolation model is built on Linux kernel primitives: bubblewrap sandboxes using user/PID/mount/network namespaces and seccomp-BPF syscall filtering today, with Landlock and cgroup resource limits as planned hardening layers. None of these exist on macOS or Windows. The threat model is explicit about this: the kernel is the boundary between the trusted gateway and the untrusted MCP servers — so the runtime requires a Linux kernel. See Sandbox isolation.

Can I run it on macOS?

Yes — inside Docker, which is the supported dev setup. Docker Desktop runs a Linux VM, and the gateway container brings everything it needs. The integration test suite is container-native for the same reason (make test runs in a Linux container; make test-local runs the host-side subset, with Linux-only tests skipping on macOS). The Compose file needs cap_add: NET_ADMIN — no SYS_ADMIN, no privileged mode. See Deployment.

How do my API keys stay safe if the servers are untrusted?

By never entering the sandbox in the first place (in the default sealed tier). The flow:

1. Your secret is envelope-encrypted (XChaCha20-Poly1305, per-secret DEKs wrapped by a master KEK from GIG_MASTER_KEY) and stored in the vault.
2. The sandboxed server receives only a placeholder token in its environment.
3. The sandbox's only network route leads to the gateway's embedded MITM egress proxy.
4. The proxy identifies the sandbox by its connection's source IP — unforgeable, since each sandbox's network namespace can only source its own /30 — checks the destination against the manifest's egress allowlist, and swaps the placeholder for the real, vault-decrypted key.

So even a fully compromised server holds nothing worth stealing, and can only talk to the domains its reviewed manifest allows. See Egress proxy.

What happens if a server I installed is malicious?

It runs as uid 65534 with zero capabilities in a bubblewrap sandbox: private namespaces, no host filesystem, cleared environment, an application-level seccomp filter that kills namespace-escape and privilege-escalation attempts (unshare, setns, clone(CLONE_NEWUSER), mount syscalls, ptrace, bpf, module loading, …), and a network namespace whose only route is the proxy. It can't read your keys (it only ever saw a placeholder), can't reach domains outside its allowlist, and every egress request is audit-logged with (user, server, domain, method, timestamp).

Honest residual risks, documented in the design record: an entrusted-tier server holds its real secret and could exfiltrate it through an allowed domain (the tier label exists to surface exactly this); and isolation is shared-kernel — a kernel 0-day breaks tenant separation, which is accepted for self-host with a curated catalog (gVisor/microVMs are a noted future option for truly hostile workloads). See Security model.

SQLite or Postgres?

SQLite is the zero-config default and what ships today. The storage layer is a repository interface designed for both SQLite and Postgres drivers, with a hard rule of no Postgres-only features in core — but only the SQLite driver exists in the codebase right now.

Why AGPL?

The gateway is unmodified AGPL-3.0 to keep the project genuinely open while preventing a closed-source hosted fork from free-riding: anyone offering it as a network service must share their changes. The design record pairs this with a trademark policy (rather than license edits) to protect the name, DCO for contributions, and concentrated copyright to preserve the option of dual-licensing a hosted product. The registry's manifest schema is Apache-2.0 so other tools can adopt it freely.

How is this different from just running MCP servers directly?

Run an MCP server directly and it holds your raw API keys and has unrestricted network and filesystem access — every server you install is a standing liability, multiplied by per-client config sprawl. Gig'MCP inverts that: one endpoint per profile instead of N client configs, and each server kernel-sandboxed with credentials kept outside it. One compromised tool can no longer expose your keys.

How is this different from Composio?

Composio doesn't run third-party code at all. Its catalog is first-party declarative connectors — a "tool" is a schema mapping to an HTTP call executed by their shared backend, which injects your OAuth token from their managed store. Isolation is logical, not physical; that's defensible only because no untrusted code executes, and it's closed-source, so your credentials live with them.

Gig'MCP's bet is the opposite: make untrusted code safe to run (sandbox + proxy), so anyone's server can be in the catalog, and let credentials stay entirely on your own hardware via self-hosting — something a closed hosted product can't offer. The toolpack engine covers the declarative-connector model too, as a subset. See the competitive note in the gateway's DESIGN.md for the full analysis.

What's the current project status?

Per the gateway README: the egress proxy and credential vault are complete — bubblewrap sandboxing, per-sandbox network namespaces, proxy-only routing, placeholder-token injection, XChaCha20-Poly1305 envelope encryption, SQLite, bearer auth, and one bundled echo server. The REST control plane, OIDC multi-user auth, and registry install path exist in the codebase; the registry, multi-user auth, and dashboard are landing per the design record's scope.

Be aware of what is not shipped yet:

• The registry's 221 cataloged manifests are planned entries with placeholder digests — not installable until CI builds their images and the digests are pinned. See Catalog.
• The node and python builders are prepared but not installable; they await the gateway's rootfs sandbox extension. See Builders.
• Docker-level seccomp=unconfined is still required (bubblewrap needs it for unprivileged user namespaces); a custom Docker seccomp profile is a planned hardening item. The application-level seccomp filter inside each sandbox already closes the user-namespace escape vectors.

Do I need privileged Docker?

No. The gateway container needs cap_add: NET_ADMIN (for veth pairs and moving them into sandbox network namespaces) plus seccomp=unconfined/apparmor=unconfined/systempaths=unconfined until the custom seccomp profile ships. No SYS_ADMIN, no --privileged, no Docker socket mount — the gateway spawns sandboxes as its own child processes, never via the Docker daemon.

Which env vars do I need to get started?

Two are required: GIG_BEARER_TOKEN (MCP client auth) and GIG_MASTER_KEY (32-byte hex vault KEK, openssl rand -hex 32). Everything else — OIDC, registry index URL and pubkey, demo credentials — is optional. See Configuration for the full table and Quickstart to get running.