Skip to content

Move between Cloud and self-hosted

How a SpecsGraph workspace will move between a self-hosted install and Cloud once Cloud launches: export, import, GitHub, access tokens and agents.

Note

SpecsGraph Cloud is coming soon

Cloud is not available yet, so there is nothing to sign up for or pay for today. The self-hosted edition is available now: the complete product, free, on your own servers. Start with the self-hosting overview.

What will move and what stays

Cloud and self-hosted will run the same product, so a move will change who operates SpecsGraph, not how your team works. It will work in either direction, using the workspace export that self-hosted installs already have. Your specs live in your repository, so starting on a self-hosted install today does not lock you in.

ItemHow it will move
The spec folder in GitNothing to move. specsgraph/ and its history stay in your repository, and the new side keeps publishing to it.
Graphs, revisions, proposals, threads, decisions and workstreamsIn the export.
Members and rolesIn the export. Each person signs in to the new side once to pick up their membership.
Project settings: repository, base branch, spec folderIn the export. You confirm them after you connect GitHub.
GitHub App installationNot moved. A self-hosted install uses your own App; Cloud will use an App run by SpecsGraph.
Personal access tokensNot moved. Everyone creates new tokens on the new side.
Agent configurationUpdated by hand: a new MCP URL and a new token.

Self-hosted to Cloud

Once Cloud launches, a move from your own install is planned to take these steps:

  1. Prepare. Merge the open pull requests from spec/ branches, so every Approved proposal is Published, and upgrade the install to the latest release (opens in a new tab), which Cloud will run.
  2. Export. An Owner exports the workspace from Workspace settings, then Export, as self-hosted installs can today.
  3. Import. When you create the Cloud workspace, you will choose Import workspace and upload the archive.
  4. Connect GitHub. You will install the App run by SpecsGraph on the same repositories and confirm each project's repository, base branch and spec folder.
  5. Reconnect agents. Everyone will create a token on Cloud and point their agent at the Cloud MCP URL, as described below.
  6. Retire the install. Once a first publish from Cloud succeeds, remove your own App from the repositories so only one side can publish. Keep a backup of the old database until you are sure you do not need it.

Cloud to self-hosted

The same export will work in the other direction, for teams that start on Cloud and later want to run SpecsGraph themselves: set up an install with Docker Compose and your own GitHub App, export from Cloud, sign in to the empty install as its first user and choose Import workspace, then install your App on the same repositories and reconnect agents.

Warning

One publisher per repository

Until you remove the old App, two installs will be able to reach the same repository. Approve proposals only on the new side, and remove the old App as soon as the first publish succeeds.

Reconnect agents

Tokens belong to the install that issued them, so each person will create a new one on the new side and put it in SPECSGRAPH_TOKEN. The MCP URL will change too: a self-hosted install answers at your server's MCP URL, such as https://specsgraph.example.com/mcp, and Cloud will have its own. In Claude Code, remove the specsgraph server and add it again with the new URL, as shown in Claude Code.

If your team commits a shared MCP config, such as .mcp.json, change the URL there in one pull request; the file refers to SPECSGRAPH_TOKEN, so it needs no other edit. Old pull request descriptions will still link to proposals on the previous side, and the commits name each proposal's branch, so you can find the same proposal after the move.

Next steps