Quickstart

This guide gets a local Subspace running with a seeded demo graph so you can click around real pages, mail, and agents. Everything runs on your machine; no external account is required for the fake-provider path.

Note

Subspace bundles its own PostgreSQL 17 + pgvector binaries for macOS and Linux (arm64 / x64). There is nothing to install or configure for the database, it boots as a supervised child process on a unix socket.

Prerequisites

Node.js 22 LTS

The whole system is one Node process. Corepack ships with Node and manages pnpm.

pnpm 9

Enable it with corepack enable. The repo is a pnpm workspace.

Run it

1. Install dependencies

   corepack pnpm install

   Host-filtered optional packages pull in the right PostgreSQL + pgvector binaries for your platform.

2. Build the web SPA

   corepack pnpm --filter @subspace/web build

   The server serves the built SPA statically, so a production-style run needs the build once. For live reload during development, use pnpm dev instead (below).

3. Start the server

   corepack pnpm --filter @subspace/server start

   First boot runs initdb for an embedded Postgres under $SUBSPACE_HOME (default ~/Subspace) and applies migrations transactionally. The server listens on 127.0.0.1:4780.

4. Open the app

   open http://127.0.0.1:4780

   You now have an empty graph. To explore a populated one, seed the demo (next).

Explore the seeded demo graph

The fastest way to see what Subspace does is the mock world: a self-consistent seed with a user (Jan Novak), CRM contacts (Rachel Kim / Acme, Marcus Feld / Vertex), projects, a pipeline table with formulas, mail threads, a meeting, and agents.

Sandbox dev loop

# throwaway home in /tmp, fake providers, mock-world seed, web HMR
pnpm dev:sandbox

Manual seed

SUBSPACE_SEED=mock-world PROVIDERS=fake \
  corepack pnpm --filter @subspace/server start

Caution

~/Subspace is your real data. Only use pnpm dev:sandbox or an explicit throwaway SUBSPACE_HOME for seeding and wiping, never against a home that holds work you care about.

Development loop

Dev (real home)

# server (tsx watch, :4780) + web (vite HMR, :5180), one Ctrl-C
pnpm dev

Dev (sandbox)

# same, throwaway /tmp home + fake providers + mock-world seed
pnpm dev:sandbox

Quality gates

# typecheck + lint + unit tests
pnpm check

Your first agent run

1. Type an instruction on a bullet

   On any page, type a plain instruction on a bullet, for example Summarize the Project X page and list open questions.

2. Send it to the default agent

   Press ⌘↵. The bullet’s text is handed to the default agent as an instruction; a violet run chip appears under the bullet.

3. Watch the run tree

   Each step (LLM calls, tool calls, output nodes) streams into a run tree beneath the bullet. Any outbound or irreversible action pauses with an approval card in the task queue.

4. Approve or steer

   Approve to let a gated tool run, or inject a steering message mid-run. When the run finishes, its output nodes are ordinary bullets you can edit and link.

Go deeper on agentsHow definitions, tools, approvals, skills, MCP servers, and orchestration fit together.

Connecting real providers

By default PROVIDERS=fake uses deterministic stand-ins for the Jupyter kernel and the search embedder, and the mock connectors for mail and IM. To connect real services:

Gmail & CalendarConnect a Google account through the OAuth flow to sync mail and calendar into the graph.

Slack & TelegramAdd IM connectors so messages become events, triage, and CRM history.

LLM providersAgents run on the Vercel AI SDK; point it at your model provider of choice.

Environment referenceEvery environment variable, default, and what it turns on.