---

A controlled gateway between AI agents and your infrastructure.

Interstellar is an MCP server that an AI agent connects to like any other — but instead of one fixed toolbox, its functionality comes from wormholes: purpose-built plugins that each do one job well (build a Debian package, reach a machine over SSH, bring up a VPN) and compose with each other. The gateway sits in the middle and enforces policy, records an audit log, and keeps the agent away from raw access.

AI agent ──MCP (JSON-RPC)──▶ interstellard ──gRPC──▶ wormhole plugins
                              │ policy │ audit │      (separate processes)

Design stance: wormholes expose specific, typed operations (deb-builder__build_source_package(url)), not generic command runners. Raw execution travels between wormholes over typed ports that agents never see, and tools that accept caller-supplied commands are denied by default policy until a server admin explicitly opts in. See docs/architecture.md.

Status

Early development, but the core is end-to-end. Working today: the MCP gateway (stdio + streamable HTTP), the wormhole plugin system and Go SDK, capability-based policy, the audit log, and composition — the session manager resolves the links a tool needs, chaining wormholes through admin-defined targets (including routing one wormhole's connection through another via via). First-party wormholes:

• exec-endpoint providers: local-exec (gateway host), ssh (remote, with key / password / agent auth, optionally tunnelled)
• network-context providers: wireguard (userspace WireGuard, no-root/no-container) and tailscale (userspace tsnet) live in the separate wormholes repo, where heavy-dependency and third-party wormholes are kept so the core stays lean
• consumers: sysinfo, uname
• echo (self-contained, for trying the gateway out)

Not yet shipped: snap packaging with wormholes as snap components.

Quick start

make            # builds bin/interstellard and bin/wormholes/*
bin/interstellard --wormhole-dir bin/wormholes

The MCP endpoint is now at http://127.0.0.1:8420. Add it to an agent — for Claude Code:

claude mcp add --transport http interstellar http://127.0.0.1:8420

Or run it locally over stdio, no HTTP involved:

claude mcp add interstellar -- /path/to/interstellard --stdio --wormhole-dir /path/to/wormholes

Ask the agent to call interstellar__status to see what's loaded — wormholes, tools (including ones hidden by policy or for lack of a target, and why), and the configured targets.

Docker

The easiest way to self-host is the compose deployment — config, secrets, persistence, and optional wormhole installers all wired up:

cd deploy/interstellar-mcp
cp .env.example .env     # secrets (optional to start)
$EDITOR config.yaml      # define your targets
docker compose up -d     # gateway on http://127.0.0.1:8420

Adding a wormhole like tailscale is just uncommenting its installer service — no building or copying, multi-arch images handle the rest. See the compose README.

For a quick one-off, the published image also runs standalone:

docker run -p 8420:8420 -v interstellar-data:/var/lib/interstellar \
  ghcr.io/talhahavadar/interstellar:latest
# build locally instead: docker build -t interstellar . && docker run ...

The image's audit log and config live under /var/lib/interstellar.

Composition

Wormholes that need to reach a machine declare a typed port; an admin binds that port to a target in config. For example, point the sysinfo wormhole at the gateway host:

# config.yaml
targets:
  localhost:
    wormhole: local-exec
    port: host

bin/interstellard --config config.yaml --wormhole-dir bin/wormholes

Now sysinfo__get_system_info takes a shell_target argument (localhost), and the gateway routes the call through the local-exec wormhole. Swap in the ssh wormhole — optionally with via pointing at a VPN target — and the same tool runs on a remote machine behind a tunnel, without the tool or the agent knowing anything about the path. See config.example.yaml and docs/architecture.md.

Configuration

Copy config.example.yaml and pass it with --config. Flags (--listen, --wormhole-dir, --audit-log) override the file. Policy lives in the config; capability names are validated at startup, so a typo fails loudly instead of silently allowing or hiding tools.

Writing a wormhole

A wormhole is a single Go binary built on pkg/wormhole — about 30 lines for a working one. See docs/creating-a-wormhole.md, or read wormholes/echo, the minimal example.

Development

make test       # unit + end-to-end (spawns real plugin processes)
make gen        # regenerate gRPC code after editing proto/

The wire contract lives in proto/interstellar/wormhole/v1; pkg/wormhole is the public SDK. Everything under internal/ is free to change.