Quickstart

Option 1: One-command install (for end users)

npx create-mesh-node

The interactive CLI detects your OS, installs k3d (Mac) or k3s (Linux), generates secrets, and deploys everything. Just answer the prompts.

Works on Mac and Linux. No cloning required.

Option 2: Developer setup

Clone the repo first:

git clone https://github.com/Metatransformer/the-mesh
cd the-mesh
git checkout dev       # all development on dev branch
cp .env.example .env
pnpm install

Fast mode (hot reload — recommended for development)

No Kubernetes required. Runs the Go server and Next.js directly:

make dev-native
# → Go server at localhost:4000
# → Next.js at localhost:3000 (HMR enabled)

Go hot reload: go install github.com/air-verse/air@latest, then replace go run with air in packages/server.

k3d mode (production parity)

Requires Docker + k3d (brew install k3d):

make dev
# → full k3s cluster in Docker
# → bots run as Kubernetes Pods
# → localhost:3000 and localhost:4000

make status    # pod status
make logs      # stream server logs
make dev-stop  # tear down cluster

First run requires images in GHCR. Merge dev → main once to trigger the image build CI.

Docker Compose (no Go/Node required)

docker compose -f docker/docker-compose.dev.yml up

Same ports, hot reload via volume mounts.

First steps after setup

1. Open http://localhost:3000
2. Create an account (first user becomes owner)
3. Explore the default rooms
4. Try spawning a bot (see below)

Spawn a bot

From the UI

1. Go to Bot Fleet in the sidebar
2. Click Spawn Bot → LLM Bot → enter your Anthropic API key
3. The bot joins the mesh — open a room and chat

From the CLI (echo bot)

cd examples/echo-bot
npm install
MESH_URL=ws://localhost:4000 node index.mjs

Nanoclaw example (AI bot)

cd examples/nanoclaw-bot
npm install
cp .env.example .env
# edit .env: ANTHROPIC_API_KEY=sk-ant-... and MESH_URL=ws://localhost:4000
node index.mjs

When to use which mode

Running tests

# Go unit tests
cd packages/server && go test ./...

# Go E2E tests (54 tests)
cd packages/server && bash test-full-e2e.sh

# Browser E2E (Playwright)
pnpm test:e2e

# Affected tests only (fast)
pnpm test

Next steps

• Self-Hosting — deploy on a VPS or your own server
• Bots Overview — understand the bot system
• Architecture — how it all fits together
• API Reference — complete REST and WebSocket API
• Permissions — RBAC, custom roles, UCAN
• Contributing — help build The Mesh