Install & quickstart

Crosscode is run entirely on your own machines. The coordination service is not hosted for you today: you host it yourself, backed by a Supabase project (or a plain Postgres instance for local-only testing).

Prerequisites

• Node.js 24 or newer
• pnpm 11
• Git
• A Supabase project, or Docker Desktop/another Docker-compatible runtime for local-only testing against a plain Postgres instance

Install dependencies

pnpm install
pnpm build
pnpm test

Set up Supabase and run the coordination service

The coordination service verifies Supabase-issued JWTs and stores workspace/operation state in Supabase-hosted PostgreSQL. Create a Supabase project (or use an existing one), then from its project settings collect the project URL, the anon public key, the service_role key, and the pooled Postgres connection string (Project Settings → API / Database).

export SUPABASE_URL="https://<project-ref>.supabase.co"
export SUPABASE_SERVICE_ROLE_KEY="<project service_role key>"
export DATABASE_URL="<Supabase pooled connection string>"
export MIGRATION_DATABASE_URL="${DATABASE_URL}"
pnpm service:migrate
pnpm service

Supabase signs access tokens with an asymmetric key (ES256 by default), verified via the project's public JWKS endpoint (<SUPABASE_URL>/auth/v1/.well-known/jwks.json) — there is no shared JWT secret to configure. The service defaults to http://127.0.0.1:8788. Plain HTTP is allowed only on loopback; to bind to another interface, configure both CROSSCODE_TLS_KEY and CROSSCODE_TLS_CERT.

Variable	Purpose	Default
SUPABASE_URL	Supabase project URL, used to verify access tokens	required
DATABASE_URL	Supabase-hosted PostgreSQL connection string	required
SUPABASE_SERVICE_ROLE_KEY	Used only by admin-side service:provision; never distribute to members	required for provisioning
CROSSCODE_SERVICE_HOST	Listen address	127.0.0.1
CROSSCODE_SERVICE_PORT	Listen port	8788
CROSSCODE_TLS_KEY	TLS private-key path	unset
CROSSCODE_TLS_CERT	TLS certificate path	unset

Run pnpm service:migrate with a migration-owner connection before starting a new service version. Migration 004_supabase_auth.sql enables Row Level Security and maps members to Supabase's auth.users; 005_rls_hardening.sql adds the remaining RLS policies. infra/docker-compose.yml is for local/CI testing against a plain Postgres instance only — production points DATABASE_URL at Supabase.

Get an account and connect this checkout

Everything below happens in the repository you actually want to work on, not in the Crosscode checkout. init has to come first — it writes the local state that signup and login both need.

pnpm crosscode init --json

If you don't have an account yet, create one straight from the terminal. This signs you up, logs you in, and provisions a personal workspace, so there is nothing else to join:

pnpm crosscode signup --email alice@example.com --password <password> --service http://127.0.0.1:8788 --json

If the account already exists, sign in instead. In a real terminal, login opens the sign-in page in your browser and the CLI collects the session on a loopback callback:

pnpm crosscode login --web <site-url> --service http://127.0.0.1:8788

For a headless machine or an agent with no browser, pass credentials directly instead. This path needs no --web at all:

pnpm crosscode login --email alice@example.com --password <password> --service http://127.0.0.1:8788 --json

Either way, the CLI authenticates directly against Supabase Auth and stores the resulting session (access token in memory, refresh token in the OS keychain when available, otherwise the local mode-0600 daemon config). Tokens are never printed. This machine then registers itself automatically the first time the daemon starts with a logged-in session and no replicaId yet — there is no separate enrollment step or token to distribute.

Start the daemon:

pnpm daemon

To join someone else's workspace instead of using your personal one:

pnpm crosscode join --workspace <workspaceId>   # or --invite <code>, or --pair <code>

Administrators of a self-hosted deployment can still create or invite a Supabase Auth user by email with pnpm service:provision (using SUPABASE_SERVICE_ROLE_KEY), but it is no longer required for the common case. Use viewer instead of member there to create a read-only member: viewers may download operations but cannot upload them.

Normal workflow

With the daemon running:

# Repository, daemon, outbox, cursor, and service health
pnpm crosscode status --json

# Declare local work
pnpm crosscode task create "Implement checkout API" --path server/routes/checkout --json
pnpm crosscode claim path server/routes/checkout --task <task-id> --json

# Create or inspect safety checkpoints
pnpm crosscode checkpoint --message "before integration" --json
pnpm crosscode checkpoint inspect <checkpoint-ref> --json

# Review remote work
pnpm crosscode proposals list --json
pnpm crosscode proposals inspect <operation-id> --json

# Materialize only after an explicit decision
pnpm crosscode accept <operation-id> --json
pnpm crosscode reject <operation-id> --json

# Run commands from a committed validation profile
pnpm crosscode validate --profile fast --json

The daemon continues capturing work while the service is unavailable. Pending outbound events survive daemon restarts. When connectivity returns, the daemon retries the same immutable event IDs, records acknowledgements, downloads operations after its saved cursor, and stores remote operations as proposals without changing files.

Validation configuration

Validation commands and exclusions come only from committed .crosscode/config.yaml at HEAD:

version: 1
validation:
  profiles:
    fast:
      commands:
        - pnpm build
        - pnpm test
excludedPaths:
  - private/**
  - '**/*.pem'

Arbitrary validation commands are not accepted through HTTP or CLI arguments. A validation result records its command, exit code, duration, bounded/redacted output, and exact checkpoint tree. If the tree changes while validation runs, the result is invalidated.

Development and verification

pnpm build
pnpm test
pnpm audit --audit-level high

The current suite covers protocol boundaries, authenticated daemon HTTP, Git checkpoints, filesystem capture, SQLite restart recovery, outbox identity, stale-base refusal, exclusions, binary safety, crash rollback, Git transitions, MCP-to-daemon mapping, and real daemon child-process restart behavior.