Setting up Stash

Stash is a backend platform: one account holding Postgres databases, one per project, with auth and file storage on top.

Who this page is for

Whoever runs Stash, which today is you, because there is no hosted Stash yet. So "setting up Stash" currently means standing up the whole platform on your own machine, and this page is an operator's guide rather than a customer's.

That distinction matters more than it sounds, because the requirements below are the operator's and not the customer's:

• Somebody who uses Stash needs no other account anywhere. They sign up to Stash, get a Postgres, and that is the whole of it. They never see Supabase, never sign up to it, and never get a bill from it. That is the entire point of the product and it is what the code does.
• Whoever runs Stash needs one Supabase account. Every customer's database is created inside that one organisation, on those credentials. It is the operator's supplier, the way a hosting company has a supplier.

Once Stash is hosted, this page becomes what it says on the tin and almost nobody reads it. Until then, running it and operating it are the same job.

Two ways to use it once it is up, and you probably want both:

• The dashboard, in a browser, at http://127.0.0.1:3010.
• An assistant, through the MCP server, so you can say "make me a database" instead of clicking.

What you need

What	Why
Node 22 or newer	Runs everything.
pnpm 10	The package manager this repo uses. npm install -g pnpm.
Docker Desktop, running	Stash keeps its own records in a Postgres container.
A Supabase account	Where Stash builds the databases it hands out. Yours as the operator, never your customers'. Skip it and Stash still runs, but every project's database sits at Queued forever, because the worker has nothing to build it with.

1. Get it running

git clone https://github.com/Sebastiandeveloper0313/Stash.git

cd Stash

pnpm install

pnpm dev

Leave that running. It starts three things: a Postgres container, the dashboard on port 3010, and a background worker on 3011. The first start takes a minute while Docker pulls Postgres.

You are ready when http://127.0.0.1:3010 loads.

Windows: use separate commands rather than joining them with &&. PowerShell does not accept && as a separator.

Making it build real databases

Without this, Stash works but every project's database sits at "Queued" forever, because the worker has nothing to build it with.

These are the operator's credentials, held once, in one place. Every account on this Stash provisions into the same Supabase organisation, and no customer is ever asked for a token of their own.

Copy .env.example to .env.local and fill in two values from Supabase:

• SUPABASE_ACCESS_TOKEN, from supabase.com/dashboard/account/tokens
• SUPABASE_ORG_SLUG, the last part of your organisation's dashboard URL

.env.local is git-ignored. Never paste these into a chat, an issue, or a commit. Restart pnpm dev after editing it.

2. Make an account

Open http://127.0.0.1:3010, click through to sign up, and give it an account name, an email and a password. The email is not verified and no mail leaves your machine: password-reset and invitation mail is caught in .stash/mail.

You now have an account with no projects. Create one from the dashboard to check it works. If you set up Supabase above, its database goes from Queued to Ready in about fifteen seconds.

3. Connect an assistant

Make a token

Go to API tokens in the sidebar, or http://127.0.0.1:3010/dashboard/tokens. Name it after whatever will use it, and click Create token.

The token is shown once. Stash keeps a hash, so there is no screen that can show it to you again. Copy it now.

Tick Read only if the assistant should be able to look but not touch. A read-only token cannot create projects, and cannot read database passwords. A connection string opens the database with the owner's role, so it is not read-only by any honest reading of the words.

Claude Code

This repository ships an .mcp.json, so Claude Code offers the server automatically when you open the repo. All it needs is the token in your environment:

$env:STASH_TOKEN = "the token you copied"

On macOS or Linux:

export STASH_TOKEN="the token you copied"

Then start Claude Code from the repository directory. It will ask once whether to trust the project's MCP servers; say yes.

To use it from somewhere other than this repository, register it explicitly with an absolute path:

claude mcp add stash --env STASH_TOKEN=your-token --env STASH_URL=http://127.0.0.1:3010 -- node /absolute/path/to/Stash/apps/mcp/dist/main.js

That needs pnpm build to have been run at least once, because it points at compiled output.

Claude Desktop

In claude_desktop_config.json:

{
  "mcpServers": {
    "stash": {
      "command": "node",
      "args": ["/absolute/path/to/Stash/apps/mcp/dist/main.js"],
      "env": {
        "STASH_TOKEN": "the token you copied",
        "STASH_URL": "http://127.0.0.1:3010"
      }
    }
  }
}

Restart Claude Desktop afterwards. MCP servers are read at startup.

4. Talk to it

Ask in plain language:

• "What's in my Stash account?"
• "Create a Stash project called Checkout API."
• "Give me the connection string for Checkout API."

Creating a project provisions a real database that your Supabase account is billed for, and each Stash account has a limit on how many it may have at once. The assistant is told this, so it should ask before creating one. It is your account either way, so it is worth knowing.

When it goes wrong

EADDRINUSE: address already in use 127.0.0.1:3010 Stash is already running. Either use it, or stop the old one. On Windows, Get-NetTCPConnection -LocalPort 3010,3011 -State Listen names the processes.

pnpm dev keeps printing worker logs and Ctrl+C does nothing The worker runs under a file watcher that restarts itself. Close the terminal window, or stop the process by id.

The token '&&' is not a valid statement separator PowerShell. Run the two commands separately.

The assistant says it cannot reach Stash pnpm dev is not running, or STASH_URL is wrong. Check http://127.0.0.1:3010/api/health answers.

The assistant says the token was not accepted It was revoked, or it is from a different Stash. Check the API tokens screen and make a new one if you are unsure.

Server "stash" is defined in multiple scopes You registered it with claude mcp add and have this repository's .mcp.json. Harmless, but claude mcp remove stash clears the duplicate.

A project's database never leaves "Queued" No Supabase credentials. See "Making it build real databases" above.

Where things live

What	Where
Dashboard	http://127.0.0.1:3010
API tokens	http://127.0.0.1:3010/dashboard/tokens
Health check	http://127.0.0.1:3010/api/health
Caught email	.stash/mail
MCP server details	apps/mcp/README.md