Deploy GBrain Agentic Memory

Deploy and Host GBrain on Railway

Your AI agent forgets everything the moment the conversation ends. GBrain is the memory it has been missing: a knowledge base your agent can search, write to and reason over, at a URL any MCP client can reach.

About Hosting GBrain

Most search tools hand back a list of pages and leave the reading to you. GBrain reads them and writes the answer, with citations, and tells you what it doesn't know yet. Every page it stores is wired into a knowledge graph as you go.

GBrain was built by Garry Tan to run his own agents, on his own infrastructure. This template is the shortest path to that. One Railway service with the database built in. No second service, no connection string, nothing that phones home.

Common Use Cases

• Give your coding agent real memory. Claude Code, Cursor, Windsurf and Codex recall past decisions and project context instead of starting cold every session.
• Keep a personal brain that answers back. Capture notes from any device, then ask a question and get a written answer with sources.
• Share what your team knows. Point everyone's agents at one brain, with scoped access per client.

Dependencies for GBrain Hosting

• An embedding API key. OpenAI, Voyage or Google. This is the only value you provide, and the service will not start without one.

Deployment Dependencies

• GBrain, the brain and MCP server
• Model Context Protocol, how AI clients talk to it
• Railway Volumes, where the brain lives
• Railway Infrastructure as Code, the same service as code in .railway/railway.ts

Implementation Details

Four steps, all written out below. You do not need to read anything on GitHub. The image runs GBrain v0.60 on Bun 1.4 and Debian 13. Prefer infrastructure as code? The repository describes the same setup in .railway/railway.ts for railway config apply.

Step 1: Deploy

Railway shows a short form first. Only one field needs you: paste your embedding API key into EMBEDDING_API_KEY. Leave everything else alone, including the optional variables at the bottom.

Click deploy. The volume and the public domain come with the template, so there is nothing to attach or generate. The first build takes a few minutes.

Using a provider other than OpenAI? Set EMBEDDING_MODEL to match your key:

Pick your provider before you add anything. GBrain fixes the vector size when it creates the brain, so switching later means re-embedding everything.

Step 2: Collect Three Values

Open your new project on railway.com and click the gbrain service. All three are on that screen.

Your domain. Settings tab, scroll to Networking. It looks like gbrain-production-a1b2.up.railway.app. That gives you two addresses: /mcp for your agent, and /admin/ for you. Every example below says your-app.up.railway.app, so swap in yours.

Your token. Deployments tab, open the latest deploy and read the log. The first successful boot prints a block containing gbrain_a1b2c3.... Copy that value. It is printed once, so save it. If you lost it, make a new one in the dashboard (Step 4): Agents > + API Key.

Your admin password. Variables tab, find GBRAIN_ADMIN_BOOTSTRAP_TOKEN and click the eye icon to reveal it. This is a different value from the token above, and it is the one people mix up.

Step 3: Connect Your Agent

Find yours. Each section stands alone.

Claude Code

claude mcp add --transport http gbrain https://your-app.up.railway.app/mcp \
  --header "Authorization: Bearer gbrain_a1b2c3..."

Check it with claude mcp list.

Cursor

Put this in ~/.cursor/mcp.json, set GBRAIN_TOKEN in your environment, then turn the server on under Customize in the sidebar.

{
  "mcpServers": {
    "gbrain": {
      "url": "https://your-app.up.railway.app/mcp",
      "headers": { "Authorization": "Bearer ${env:GBRAIN_TOKEN}" }
    }
  }
}

Windsurf

Put this in ~/.codeium/windsurf/mcp_config.json, set GBRAIN_TOKEN, then restart Windsurf.

{
  "mcpServers": {
    "gbrain": {
      "serverUrl": "https://your-app.up.railway.app/mcp",
      "headers": { "Authorization": "Bearer ${env:GBRAIN_TOKEN}" }
    }
  }
}

Codex

Put this in ~/.codex/config.toml, export GBRAIN_TOKEN, then restart Codex. Check it with codex mcp list.

[mcp_servers.gbrain]
url = "https://your-app.up.railway.app/mcp"
bearer_token_env_var = "GBRAIN_TOKEN"

Claude Desktop

Settings > Integrations, add an integration with your /mcp URL, set authentication to bearer token and paste your token.

Claude Cowork

An Organization Owner does this once: Organization Settings > Connectors, create a connector with your /mcp URL, then set bearer token authentication under Advanced Settings.

ChatGPT

ChatGPT signs in through OAuth, so register a client first.

1. Sign in to the dashboard (Step 4), open Agents and click + OAuth Client.
2. Name it chatgpt. Set Connection type to Browser sign-in: public client with PKCE and leave Permission profile on memory-writer.
3. Under Exact redirect URIs, paste the redirect URI ChatGPT shows on its connector setup screen.
4. Click Preview permissions, then Register with reviewed permissions, and copy the client_id. There is no client secret for this type.
5. In ChatGPT: Settings > Connectors > Add connector. Enter your /mcp URL and the client ID, click Connect, then approve the consent screen.

Perplexity

Needs Pro, and a client registered first.

1. Sign in to the dashboard (Step 4), open Agents and click + OAuth Client.
2. Name it perplexity. Set Connection type to Machine credentials and leave Permission profile on memory-writer.
3. Click Preview permissions, then Register with reviewed permissions, and copy both the client_id and client_secret. They show once.
4. In Perplexity: Settings > Connectors. Add a remote connector with your /mcp URL, choose OAuth client credentials, paste both values and save.

Check it worked

Ask your agent to remember something. Start a new chat and ask for it back.

Step 4: Use the Dashboard

The dashboard is a page served by your own deployment, not by Railway. Open https://your-app.up.railway.app/admin/ in any browser.

You get a screen titled GBrain owner login. Click Sign in with the owner bootstrap credential, paste your GBRAIN_ADMIN_BOOTSTRAP_TOKEN into the box and click Sign in as owner.

Inside, Agents is where you create API keys (+ API Key) and OAuth clients (+ OAuth Client) with the access you choose, and revoke them. You can also watch a live feed of what your agents are doing and read request logs. Parameters are redacted by default.

If Something Goes Wrong

Deploy fails with "No embedding provider configured". EMBEDDING_API_KEY is empty. Set it in Variables and redeploy.

Your agent gets a 401. The token was revoked or the brain was recreated. Make a new one in the dashboard: Agents > + API Key.

The dashboard rejects your token. You are pasting the connect token from the logs. The sign-in box wants GBRAIN_ADMIN_BOOTSTRAP_TOKEN, which does not start with gbrain_.

Claude Desktop, Cowork, ChatGPT or Perplexity will not connect. These sign in through a browser, so their origin must be allowed. GBRAIN_HTTP_CORS_ORIGIN ships set to https://claude.ai,https://chatgpt.com. Add to that list rather than replacing it, and never use *.

Search returns nothing after an import. The embedding key is wrong. Check that EMBEDDING_API_KEY belongs to the provider in EMBEDDING_MODEL, then redeploy.

Why Deploy GBrain on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying GBrain on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.

_{A community-maintained template, not affiliated with or officially supported by the GBrain project. GBrain is built by Garry Tan and licensed MIT.}