Skip to content

Self-hosting overview

Run the open-source SpecsGraph stack on your own servers, which is how you use SpecsGraph today: architecture, minimum requirements and what you operate.

The complete product, on your servers

SpecsGraph is open source from top to bottom, and self-hosting is how you run it today. The self-hosted edition is the complete product, with the system graph, glossary, workstreams, review threads, decision log and MCP tools. SpecsGraph Cloud, which is coming soon, will run the same code with nothing held back.

When you self-host, the operations are yours: servers, updates and backups. In return, the database that holds your graph, proposals, review threads and members runs on servers you control. Published spec files still go to the GitHub repositories you connect, and your agents send what they read to whichever model provider they use. Once Cloud launches, you will be able to move your workspace to it if you would rather hand the operations over.

Architecture

A self-hosted install is a small set of containers behind a reverse proxy. The proxy terminates TLS and routes requests by path.

ComponentImagePortWhat it does
Web appghcr.io/specsgraph/specsgraph-web3000The browser app people sign in to, where they explore the graph and review proposals.
APIghcr.io/specsgraph/specsgraph-api8080Stores the graph, handles sign-in with GitHub, receives GitHub webhooks and commits approved changes. Served under /api.
MCP serverghcr.io/specsgraph/specsgraph-mcp8090The endpoint agents connect to. Served under /mcp.
Postgres 16postgres:165432The system of record: the graph, proposals, review threads, members and personal access token records.
Redis 7redis:76379Queues and caches, including live updates in the browser.
Reverse proxyCaddy in the example, or your own80, 443Terminates TLS and routes traffic to the three SpecsGraph services.

Only the proxy is exposed to the network. Postgres and Redis stay on the internal Docker network. For Northwind Commerce, people open https://specsgraph.example.com, agents connect to https://specsgraph.example.com/mcp, and GitHub delivers webhooks to https://specsgraph.example.com/api/github/webhooks.

Minimum requirements

These figures are a starting point for a single server running the whole stack for a small team. Add memory and disk as your graph, history and team grow.

ResourceMinimum
CPU2 vCPU
Memory4 GB RAM
Disk20 GB free, on SSD storage
Container runtimeDocker Engine with the Compose v2 plugin (docker compose)
Domain and TLSA domain name pointing at the server, with ports 80 and 443 open so the proxy can get a certificate

The server also needs outbound HTTPS to GitHub and to ghcr.io to pull images, plus your mail server if you set SMTP_URL. GitHub needs inbound HTTPS to your webhook URL. If you filter inbound traffic, GitHub publishes its webhook source addresses under the hooks key of its meta API (opens in a new tab).

What you take on

  • Hosting and network security. You provision the servers, keep the operating system patched, terminate TLS and decide who can reach the install. GitHub must be able to reach the webhook URL, and the install must reach GitHub and the container registry.
  • Upgrades and security patches. You follow releases (opens in a new tab), read the notes and roll new versions out when it suits you. Security fixes reach you only when you upgrade.
  • Backups and uptime. You back up Postgres, test restores and watch that the service stays reachable for people and agents.
  • Your GitHub App. You create the App in your GitHub organization, give its credentials to the install and rotate them when needed.

Self-hosted and Cloud compared

SpecsGraph Cloud is not available yet. This is how the two editions will compare once it launches:

Self-hosted, available todaySpecsGraph Cloud, coming soon
Product and featuresThe same open-source codeThe same open-source code
Servers, network and TLSYouRun for you
Updates and security patchesYou, on your scheduleApplied for you
Backups and uptimeYouAutomatic backups
GitHub AppYou create and maintain your ownReady on day one
Agents over MCPThe full tool set at your own URL, such as https://specsgraph.example.com/mcpThe same tools at a Cloud URL
CostFree forever, plus your infrastructurePaid plans, not available yet; see pricing

License and source code

The full source, including the compose file and the container build files, is on GitHub (opens in a new tab). The terms are in the LICENSE file (opens in a new tab) of the repository. Release notes for every version are on the releases page (opens in a new tab).

Next steps