Quick Start

First success is three steps. Everything else on this page is a branch — take it only after the node answers and one session is recorded.

1. Have a supported coding tool installed (Claude Code is the reference).
2. curl -fsSL https://get.rivethub.io/local.sh | bash
3. Start a new session in that tool so MCP recall loads (restart the tool, or on Grok run /mcps reload). Open RivetHub (Linux AppImage, or https://localhost:5174) and use the tool. Success = this new-session turn appears in Hub and a memory_search from the tool returns it. An already-open session will not see the new MCP server.

Do not start with Docker, Proxmox, rivetos init, mesh enroll, or a Postgres URL. Those are day-2. Windows downloads the desktop app and talks to a Linux/mac node. Android pairs after the laptop is up (Settings → Devices QR). Developers clone this repo and run npx rivetos local, not npx rivetos init.

---

Laptop (supported)

Stable first-install lives on the production server, not on GitHub Releases:

curl -fsSL https://get.rivethub.io/local.sh | bash

That clones the pinned local_ref from get.rivethub.io/pins/stable.json, stands up embedded PGlite + den on https://localhost:5174, wires harness memory plugins, and (on Linux) installs the desktop AppImage. Desktop and Android first downloads are on rivethub.io. Dev / nightly app builds live on the mesh update share your deployment publishes for in-app Updates (Settings → Updates). GitHub tags are source pins only.

Day-2: rivetos local status, rivetos local backup, rivetos local reset. Full contract: LOCAL-MODE.md.

Prerequisites (source / mesh)

Requirement	Version	Check
Node.js	≥ 22 for npm install / rivetos local; ≥ 24 for rivetos init (24 used in CI/containers)	node --version
npm	≥ 10	npm --version
Git	any	git --version
Docker (optional)	≥ 24	docker --version

Note: npm install automatically builds all packages via postinstall. No separate build step needed.

Option A: interactive setup (source checkout)

Cloning main is the development path. GitHub Releases are not the supported install pin.

The rivetos init wizard walks you through deployment target, agent configuration, and API keys, then generates your config automatically. Human UX is RivetHub; the wizard no longer collects social-bot tokens.

git clone https://github.com/philbert440/rivetOS.git
# production: git checkout <tag>
cd rivetOS
npm install
npx rivetos init

The wizard will:

1. Detect your environment: Docker available? Proxmox? How much memory?
2. Choose deployment target: Docker (recommended), Proxmox, or manual
3. Configure agents: pick a provider, enter your API key, choose a model
4. Join a RivetHub mesh (optional): datahub SSH target, node name, optional advertise host — enrolls via the same path as rivetos mesh enroll
5. Owner user id for a single-owner users.json seed at $RIVETOS_SHARED_DIR/rivetos/users.json (default owner; existing file is left in place). First init on an install that has no users.json writes unmappedIsOwner: false (fail closed) — a missing file used to be treated as permissive (unmapped devices resolve as the owner). This file is the only per-user routing source (rivetos user add writes it; override the path with RIVETOS_USERS_FILE). den loads the registry once at boot (no watcher) — restart den / the rivetos node after rivetos user add for routing to take effect.
6. Review and deploy: summary of your choices, then one-click deploy

Social bots (Discord, Telegram, Voice) were removed in Phase 5; human UX is RivetHub.

For non-interactive / distro installs, pass a JSON answers file:

npx rivetos init --answers-file /path/to/answers.json

Every prompt that would fire on this run must be present as a key. A missing key is a hard error that names the key (no silent defaults). A value of { "default": true } opts into that prompt’s interactive default.

{
  "deployment": "manual",
  "agents": [
    {
      "name": { "default": true },
      "provider": "xai",
      "apiKey": "xai-...",
      "model": { "default": true },
      "thinking": { "default": true }
    }
  ],
  "postgresUrl": "postgres://rivetos:...@datahub:5432/rivetos",
  "joinMesh": true,
  "meshHub": "rivet@192.0.2.10",
  "meshName": "node-a",
  "meshAdvertise": "192.0.2.11",
  "ownerId": { "default": true },
  "confirm": true
}

Key	Required when	Notes
existingConfig	A config already exists	deploy | reconfigure | validate | overwrite | cancel
overwriteConfirm	existingConfig is overwrite	boolean ({ "default": true } → false)
deployment	wizard runs	docker | proxmox | manual (no default)
dockerContinue	deployment is docker and Docker was not detected	boolean
agents	wizard runs	non-empty array; each entry is one agent (no add-another loop)
agents[].name	each agent	{ "default": true } → rivet on the first agent
agents[].provider	each agent	no default
agents[].apiKey	providers that need a key	{ "default": true } uses $ANTHROPIC_API_KEY / $XAI_API_KEY / $GOOGLE_API_KEY when set. Optional for vllm / llama-server (omit or empty = unauthenticated server; ignored when blank). Not collected for claude-cli or codex-cli.
agents[].baseUrl	ollama / vllm / llama-server	interactive URL defaults
agents[].model	each agent, including claude-cli	provider default model
agents[].thinking	each agent	{ "default": true } → medium
postgresUrl	deployment is manual	postgres://…
joinMesh	wizard runs	boolean ({ "default": true } → false)
meshHub	joinMesh is true	user@host
meshName	joinMesh is true	DNS-label node name. { "default": true } is rejected — the interactive hostname-derived default is not a silent answers default
meshAdvertise	optional when joining	omit or { "default": true } to auto-detect
ownerId	wizard runs	{ "default": true } → owner
confirm	wizard runs	{ "default": true } → true
deployNow	deployment is docker, or existingConfig is deploy	{ "default": true } → true

After the wizard completes, your agent is running.

---

Option B: Docker (manual)

1. Clone and install

git clone https://github.com/philbert440/rivetOS.git
cd rivetOS
npm install

2. Create your config

mkdir -p ~/.rivetos
cp config.example.yaml ~/.rivetos/config.yaml

The CLI, rivetos doctor, and Docker Compose bind-mount ~/.rivetos/config.yaml (not a repo-root config.yaml). Edit that file:

runtime:
  workspace: ~/.rivetos/workspace
  default_agent: myagent

agents:
  myagent:
    provider: anthropic

providers:
  anthropic:
    model: claude-sonnet-4-6
    max_tokens: 8192

# channels: social bots removed in Phase 5 — use RivetHub
# optional agent mesh: channels.agent: { port: 3100, agent_id: opus }


memory:
  postgres:
    # Connection string is set via RIVETOS_PG_URL env var

3. Set up secrets

cp .env.example ~/.rivetos/.env

Edit ~/.rivetos/.env. Compose’s datahub currently hardcodes user/password rivetos/rivetos and publishes host 5433 → container 5432. A repo-root .env is not what the agent container reads.

ANTHROPIC_API_KEY=sk-ant-...
# Inside Compose: host is `datahub`, port 5432. From the host machine: localhost:5433.
RIVETOS_PG_URL=postgresql://rivetos:rivetos@datahub:5432/rivetos

Security: Never put API keys in config.yaml. Always use .env or environment variables.

4. Build and run with Docker

The unified Compose stack lives at infra/docker/rivetos/docker-compose.yml. You can either pass -f every time, or set COMPOSE_FILE once:

# (optional) so plain `docker compose ...` finds the unified stack
export COMPOSE_FILE=infra/docker/rivetos/docker-compose.yml

# Build container images from source
npx rivetos build

# Start everything (datahub + agent)
docker compose -f infra/docker/rivetos/docker-compose.yml up -d

# Check status
npx rivetos status

# View logs
npx rivetos logs --follow

5. Verify

# Run diagnostics
npx rivetos doctor

# Run smoke tests
npx rivetos test

---

Option C: bare-metal (no Docker)

Run RivetOS directly on your machine. You’ll need PostgreSQL running separately.

1. Clone and install

git clone https://github.com/philbert440/rivetOS.git
cd rivetOS
npm install

2. Set up PostgreSQL

RivetOS needs PostgreSQL 16+ with the pgvector extension.

# Ubuntu/Debian
sudo apt install postgresql-16 postgresql-16-pgvector

# macOS (Homebrew)
brew install postgresql@16
brew install pgvector

# Create a login that matches the URL in step 3. `createdb rivetos` alone
# does not create user/password `rivetos` / `rivetos`.
# Ubuntu/Debian
sudo -u postgres psql -v ON_ERROR_STOP=1 <<'SQL'
CREATE USER rivetos WITH PASSWORD 'rivetos';
CREATE DATABASE rivetos OWNER rivetos;
SQL
sudo -u postgres psql -d rivetos -c "CREATE EXTENSION IF NOT EXISTS vector;"

# macOS (Homebrew) — your account is the superuser
psql postgres -v ON_ERROR_STOP=1 <<'SQL'
CREATE USER rivetos WITH PASSWORD 'rivetos';
CREATE DATABASE rivetos OWNER rivetos;
SQL
psql -d rivetos -c "CREATE EXTENSION IF NOT EXISTS vector;"

3. Create config and secrets

mkdir -p ~/.rivetos
cp config.example.yaml ~/.rivetos/config.yaml
cp .env.example ~/.rivetos/.env

Edit ~/.rivetos/config.yaml as in Option B, step 2. Do not copy Option B’s RIVETOS_PG_URL. datahub only resolves inside Compose. Use the localhost login created above:

RIVETOS_PG_URL=postgresql://rivetos:rivetos@localhost:5432/rivetos

rivetos start reads ~/.rivetos/config.yaml by default.

4. Create workspace

mkdir -p ~/.rivetos/workspace/memory

Add your workspace files (templates ship under workspace-templates/ in the repo; rivetos init / rivetos local copy them in for you):

File	Purpose	Required?
~/.rivetos/workspace/AGENT.md	Agent identity and personality	Yes (rivetos doctor fails without it)
~/.rivetos/workspace/MEMORY.md	Context index for the memory system	Yes
~/.rivetos/workspace/users/	Per-user notes (optional)	Optional

Legacy CORE.md / USER.md / WORKSPACE.md names are migration hints only — do not create those as the required trio.

See the Workspace Files section below for details.

5. Start

npx rivetos start

6. Install as a system service (optional)

# Generate a systemd unit
npx rivetos service init

# Start it
npx rivetos service start

---

Workspace files

The loader (packages/core/src/domain/workspace.ts) injects two files into the system prompt. rivetos doctor fails if either is missing. Full templates ship in workspace-templates/.

Required files

AGENT.md: agent identity, operating contract, and owner / routed-user gate.

# AGENT.md — Rivet

You are Rivet, an engineering partner. Search memory before you re-derive a solved problem.

MEMORY.md: a short index of where to look (search vs browse vs wiki).

# MEMORY.md — where answers live

Use `memory_search` for decisions. Use `memory_browse` when you know the day.
If memory and a workspace file disagree, memory wins. Update the file.

Legacy CORE.md / USER.md / WORKSPACE.md at the workspace root are not loaded. Doctor treats them as migration hints into AGENT.md.

Optional files

users/<profile>.md: per-user notes. A matching profile is appended as ## USER.md (<profile>). The owner identity lives in AGENT.md.

HEARTBEAT.md: periodic background-task checklist. Injected on heartbeat turns only.

memory/YYYY-MM-DD.md: daily notes. The agent searches these through memory tools. They are not pinned into the system prompt.

---

First conversation

Once your agent is running, talk to it through RivetHub:

Hub: Open RivetHub pointed at this node’s gateway and start a harness session.

The agent HTTP channel (POST /api/message) is an mTLS-authenticated endpoint for inter-agent / mesh delegation, not a casual chat API; it expects a { fromAgent, message } envelope over HTTPS with client certs. See Mesh Networking.

Useful commands

In any channel, you can use slash commands:

Command	What it does
/stop	Stop the current turn
/interrupt [message]	Stop the current turn and send a new message
/steer [message]	Inject guidance into the active turn
/new	Start a fresh session (clears conversation history)
/status	Show runtime status
/model [provider] [model]	Show or switch the current model
/think [level]	Set thinking depth: off, low, medium, high
/reasoning	Toggle reasoning (thinking) visibility
/tools	Toggle tool-call visibility
/context	Show context-window stats
/memory	Show memory system health and stats
/clear	Clear queued messages
/help	List available commands

---

CLI reference (quick)

# Setup
rivetos init                          # Interactive setup wizard
rivetos init --answers-file FILE      # Non-interactive (JSON answers)
rivetos update                        # Pull latest, rebuild, re-symlink (add --mesh or --bare-metal)
rivetos doctor                        # Health check (config, providers, connectivity)

# Runtime
rivetos start [--config <path>]       # Start the runtime
rivetos stop                          # Stop the running instance
rivetos status                        # Show runtime status and metrics

# Configuration
rivetos config show|validate|edit|path
rivetos config init                   # Same as rivetos init — setup wizard

# Agents & models
rivetos agent list|add|remove
rivetos model                         # Show providers + current models
rivetos model <provider> <model>      # Switch default model (persistent)

# Providers
rivetos <provider> status             # codex-cli | anthropic | xai | google | ollama
rivetos ollama models                 # List local Ollama models

# Mesh (multi-node)
rivetos mesh list|ping|status
rivetos mesh enroll <user@host> --name <node>   # Join a RivetHub mesh
rivetos mesh join --manual <host>               # Legacy seed-node YAML only
rivetos keys rotate|list|status       # Manage mesh keys

# Memory & database
rivetos memory queue-status           # Show graphile-worker job queue
rivetos memory backfill-tool-synth    # Enqueue historical tool calls for synthesis
rivetos memory retry-failed --task extract-wiki --dry-run  # Plan reset of dead jobs
rivetos db migrate|status             # Run / inspect schema migrations

# Containers & service
rivetos build                         # Build container images from source
rivetos service init|start|stop|restart|status|logs

# Introspection
rivetos logs [--lines --follow --since --grep]
rivetos test [--quick]                # Smoke tests (config, provider, memory, tools)
rivetos plugins list
rivetos skills list

---

Next steps

• Provider Setup — API, local, and harness CLI providers
• Channels — RivetHub is the human UX. The agent channel is mesh only
• Hub Setup — Run RivetHub clients against a node
• Mesh Networking — Multi-node fleets with mTLS delegation
• Configuration Reference — Every config option explained
• Architecture — How the system works
• Plugins — How to write your own channel, provider, or tool
• Skills — How to write and share skills
• Deployment — Docker, Proxmox, multi-agent, networking
• Troubleshooting — Common issues and fixes

---

Quick troubleshooting

Agent doesn’t respond?

• Run npx rivetos doctor to check connectivity
• Check npx rivetos logs for errors
• Verify your API key is set in .env

Docker containers won’t start?

• Run docker compose -f infra/docker/rivetos/docker-compose.yml logs datahub to check PostgreSQL
• Ensure host port 5433 (Compose maps 5433→5432) isn’t already in use
• Try npx rivetos build to rebuild images

Memory search returns nothing?

• Check PostgreSQL connection: npx rivetos test --quick
• Embeddings may still be processing: check npx rivetos status for queue depth

Can’t find config?

• Default location: ./config.yaml or ~/.rivetos/config.yaml
• Override with: npx rivetos start --config /path/to/config.yaml