Skip to content

Frequently asked questions

Answers to common SpecsGraph questions about open source, MCP agents, Git repositories, free self-hosting and the plans for SpecsGraph Cloud.

Product

Is SpecsGraph open source?

Yes, the whole product. The source is on GitHub (opens in a new tab), and today you run it by hosting it yourself. SpecsGraph Cloud, which is coming soon, will run the same open-source code.

Who is SpecsGraph for?

Engineering teams that build software with AI agents and want one source of truth that people and agents both work from. A single developer can use it as well, reviewing their own agent's proposals.

How is this different from a wiki?

A wiki stores pages of prose. SpecsGraph stores a typed, linked model of your system: contexts, requirements with IDs, scenarios and glossary terms that tools can query and reason about. Core concepts lists the building blocks.

Do I have to write every spec by hand?

No. Agents draft proposals from your prompts and your codebase, and your team edits, questions and approves them. You can also make changes yourself in the web app, and they go through the same proposal and review flow. See How the spec workflow works, and Start from an existing codebase for software that already runs.

Agents

Which agents work with SpecsGraph?

Any agent that supports MCP. There are setup guides for Claude Code, Cursor and GitHub Copilot, and other MCP clients connect the same way. You choose the agent; SpecsGraph supplies the graph it works on.

Can an agent change the spec without a person approving it?

No. An agent's write tools only open or extend proposals, and approval is a web app action for people with the Editor role or above. Nothing reaches the spec or your repository before that. How the spec workflow works explains the guarantee.

Do connected agents count as seats?

No. The self-hosted edition does not count seats at all. On SpecsGraph Cloud, which is coming soon, a seat will be any person who can sign in, and agents, which use a member's personal access token, will not count. Cloud plans has the details.

How does an agent authenticate?

With a personal access token that you create in SpecsGraph and give to your MCP client. Tokens start with sgp_, so you can add a secret-scanning pattern that catches a leaked one, and you can revoke a token whenever you need to.

Git and repositories

How does the spec stay in step with the code?

Approved changes are committed into your repository, so the spec evolves in the same history as the code and goes through the same pull request review. See Spec files in your repository.

What does SpecsGraph write to my repository?

Only the specsgraph/ folder: a generated README.md index, Markdown for contexts, requirements, the glossary, actors, decisions and workstreams, plus graph.json for tools. By default, changes arrive as pull requests from branches under spec/; a project can switch to direct commits, as described in Branches and pull requests. Everything goes through a GitHub App you install on the repositories you pick. See Connect GitHub.

Does SpecsGraph work with GitLab, Bitbucket or GitHub Enterprise Server?

SpecsGraph publishes through a GitHub App, so the repository has to be on GitHub, and these docs describe GitHub.com. There is no GitLab or Bitbucket integration. For GitHub Enterprise Server, talk to us.

Can I undo a change to the spec?

Yes. Every revision is a Git commit you can diff and review. To roll one back, restore the earlier version in SpecsGraph: that opens a proposal, and once it is approved and merged, the rollback is a new revision. Reverting the files with Git alone leaves the graph out of step. History and versions shows how.

Hosting

How do I run SpecsGraph today?

Host it yourself. The self-hosted edition is the complete product, free and open source, and it is the way to run SpecsGraph today. Install with Docker Compose sets up a server, and the Quickstart goes from install to a first published requirement.

Is SpecsGraph Cloud available?

Not yet. SpecsGraph Cloud, where we run SpecsGraph for you, is coming soon, and we have not set a launch date. It will run the same code with the same features; the difference will be who runs the servers, applies upgrades and keeps the backups. The self-host page compares the two.

What do I take on when I self-host?

Hosting and network security, upgrades and security patches, backups and uptime, and your own GitHub App, which you create, configure and rotate credentials for. Start with the self-hosting overview.

Will I be able to move to Cloud later?

That is the plan. Your specs already live in your repository, and once Cloud launches you will be able to export a self-hosted workspace and import it there, or move back the same way. Move between Cloud and self-hosted describes how it will work.

Where are the release notes?

On the releases page (opens in a new tab) of the GitHub repository. Your install runs the version you pin, as described in Upgrades and backups.

Pricing and support

Is SpecsGraph free?

Yes. The self-hosted edition is free, with no seat limits. There is no trial and nothing to pay; you cover only your own infrastructure. The pricing page also shows the planned Cloud plans.

When will SpecsGraph Cloud launch?

We have not set a date. None of the Cloud plans is available yet, so there is nothing to sign up for or pay today. Watch the GitHub repository (opens in a new tab) or join the community on Discord (opens in a new tab) to hear when Cloud opens.

Can I get paid support?

Not yet. Paid support plans, including support for self-hosted installs, are coming soon. Today, help comes from the community on Discord and from GitHub issues; see Get help.

What happens to my data if I stop using SpecsGraph?

Your specs already live in your repository, so they stay with your code. Everything else, such as proposals, review threads and history, is in your install's database, which you control and back up. You can also export the whole workspace from Workspace settings, then Export.

Help

Where do I get help?

Troubleshooting covers common problems with sign-in, GitHub, publishing, agents and self-hosted installs, and lists where to ask: the community on Discord and GitHub issues for bugs.

Next steps