Docs/Resonant/Getting Started

Getting Started

On this page

There’s no setup wizard. You clone the repo, copy three template files, edit them by hand, and run it. About 15 minutes.

Prerequisites

  • Node.js 20–24 (LTS recommended). Node 25+ is refused at boot — a native database component crashes on it, and the app tells you so. Check with node --version.
  • A Claude account — either a Claude Pro/Max subscription or an Anthropic API key.
  • Git, to clone the repository.

Step 1 — Connect Claude

Do this first.

Recommended (Claude Pro/Max subscription):

npm install -g @anthropic-ai/claude-code
claude

Inside claude, run /login — it opens a browser, you log in and approve, then /exit or Ctrl+C. The login persists on the machine and Resonant reuses it. Leave ANTHROPIC_API_KEY blank — if both are set, the API key wins and you’re billed per token instead of using your plan.

Alternative (API key): go to console.anthropic.com → API Keys → create a key (sk-ant-...). You’ll paste it into .env in Step 3. Skip the Claude Code install in this path. You need exactly one of the two, not both.

Step 2 — Get the code

git clone https://github.com/codependentai/resonant.git
cd resonant
npm install

Step 3 — Set it up

There’s no interactive wizard — copy the templates and edit them by hand.

cp resonant.example.yaml resonant.yaml
cp .env.example .env
cp examples/CLAUDE.md CLAUDE.md

PowerShell equivalent: Copy-Item resonant.example.yaml resonant.yaml, and so on for the other two.

Then open resonant.yaml and edit:

identity:
  companion_name: "Echo"        # change to your companion's name
  user_name: "Alex"             # change to your name
  timezone: "Europe/London"     # change to your IANA timezone

Then open .env and set APP_PASSWORD=<something>. This is required — an empty password makes the app refuse to serve (503, “Auth not configured”). If you’re using the API-key route, also set ANTHROPIC_API_KEY= here; leave it blank on the subscription route.

None of this is a program running — resonant.yaml and .env are just text files the app reads on start. resonant.yaml holds the everyday settings (your AI’s name, your name, timezone). .env holds secrets (your password, your API key if you’re using one). Both are gitignored, so nothing you write in them gets committed or shared.

Step 4 — Build and run

npm run build
npm start

You’ll see Server running at http://127.0.0.1:3099. Open that URL and log in with the password you set in .env.

Optional — build the search index

If you’re bringing history from an older install, build the full-text search index once:

node scripts/setup-fts.mjs

New messages are indexed automatically after that.

Dev mode

npm run dev runs the backend with hot reload. Run the frontend’s Vite dev server alongside it separately.

First hello

The login screen greets you with “come home.” You land in a chat view with a daily thread ready. Replies stream token-by-token, and a collapsible “thinking” pill may appear above the answer.

Where things live

PathWhat it holds
resonant.yamlEveryday settings
.envSecrets
CLAUDE.mdPersonality — hot-reloads, no restart needed
data/Everything remembered — the SQLite database, files, daily notes

Backup = copy data/ plus the three config files. Moving to a new machine = copy the project, npm install, npm run build, drop data/ and your configs back in.

Troubleshooting

  • 503, “Auth not configured” — APP_PASSWORD isn’t set. Fix .env and restart.
  • Login bounces — HTTP/HTTPS cookie mismatch. Use plain http:// for local installs.
  • “Resonant requires Node 20-24” — wrong Node version installed.
  • Port already in use — another instance is running, or change port: in resonant.yaml.
  • “Error saving” in Settings — the server isn’t running.
  • “Disconnected. Retrying…” — check the server is up and read the terminal logs.
  • Can’t think / errors on reply — the Claude connection from Step 1 hasn’t completed.

Next Steps

arrow_back
Previous Overview
Next Architecture
arrow_forward