How do I set up Daemion fully?

~15–20 minutes

Prerequisites: Completed quickstart, daemion CLI installed

The quickstart gets you running locally. This guide layers in the optional (but powerful) pieces: Engram for persistent knowledge, Tailscale for phone access from anywhere, and a background service so the gateway survives reboots.

Prerequisites checklist

Before proceeding, confirm these are in place:

daemion start runs without errors (gateway up on port 3001)
You’re logged into the Claude CLI (claude /login)
Node.js 22+ installed

Everything below is additive — each section is independent. Do them in any order.

How do I add Engram (persistent knowledge graph)?

Engram is an optional Neo4j-backed knowledge store. When enabled, Daemion recalls facts, patterns, and conversation history across sessions using vector + BM25 search.

The gateway runs fine without Engram. If Engram is unreachable at startup, the agent logs a warning and continues — you just get shorter context windows without cross-session memory.

Step 1 — Install Neo4j

bash

brew install neo4j brew services start neo4j

Or use the Neo4j Desktop installer if you prefer a GUI.

Step 2 — Set the connection environment variable

bash

export NEO4J_URI=bolt://localhost:7687 export NEO4J_USER=neo4j export NEO4J_PASSWORD=your-password

Add these to your shell profile (~/.zshrc or ~/.bash_profile) so they persist across sessions.

Step 3 — Verify Engram connects

bash

daemion start

Look for this line in startup output:

text

Engram connected (bolt://localhost:7687)

If you see Engram unavailable — continuing without knowledge graph, the gateway is still functional but memory won’t persist between sessions.

Engram is enabled per-agent. Each agent definition in agents/ has an engramEnabled flag and an engramGroups list that scopes what knowledge it can read and write.

How do I set up Tailscale for remote access?

Tailscale creates a private WireGuard mesh so your phone can reach the gateway without port forwarding or exposing anything to the public internet.

Step 1 — Install Tailscale on your Mac

Download Tailscale for macOS and sign in.

Step 2 — Install Tailscale on your phone

Install from the App Store or Play Store and sign into the same Tailscale account.

Step 3 — Find your Tailscale hostname

bash

tailscale status

You’ll see a hostname like your-macbook-pro.tail9edf5c.ts.net. That’s your gateway’s remote address.

Step 4 — Configure the app to point at your gateway

In the Daemion PWA settings (or via localStorage), set the gateway URL to your Tailscale hostname:

text

https://your-macbook-pro.tail9edf5c.ts.net

Step 5 — Pair your phone

Run daemion start on your Mac. Scan the QR code shown in the terminal with your phone’s camera. The QR encodes your Tailscale gateway URL and a one-time pairing token — your phone will pair automatically.

The bearer token that gets stored in your phone’s browser is a device pairing token, not user authentication. It connects your phone to your local gateway. Your Anthropic account session stays on the Mac via the Claude CLI.

How do I run the gateway as a background service?

Running daemion start in a terminal means the gateway dies when you close the window. A background service keeps it alive across reboots and restarts it automatically on crash.

macOS — launchd

The system/ directory contains a ready-to-use launchd plist. Use the install script:

bash

cd /path/to/daemion bash system/install.sh install

This copies system/daemon.plist to ~/Library/LaunchAgents/, validates it with plutil, and bootstraps it into launchd. The service starts immediately and on every login.

Useful commands:

bash

bash system/install.sh status # check if running bash system/install.sh logs # tail gateway logs bash system/install.sh uninstall # remove the service launchctl list | grep daemion # verify launchd registration

Logs land in ~/.daemion/gateway.log.

Linux — systemd

bash

cp system/daemion.service ~/.config/systemd/user/daemion.service systemctl —user daemon-reload systemctl —user enable daemion systemctl —user start daemion

Useful commands:

bash

systemctl —user status daemion journalctl —user -u daemion -f # follow logs systemctl —user stop daemion systemctl —user disable daemion

The service restarts automatically on failure (Restart=on-failure, 5-second backoff).

The launchd plist in system/daemon.plist has hardcoded paths for node and the project directory. If you cloned the repo to a different location or use a different Node version manager, edit those paths before running the install script.

What environment variables does Daemion use?

Variable	Default	What it does
`DAEMION_PORT`	`3001`	Port the gateway listens on
`DAEMION_DB_PATH`	`~/.daemion/daemion.db`	Path to the SQLite database file
`DAEMION_TOKEN_PATH`	`~/.daemion/.gateway-token`	Path to the stored bearer token
`NEO4J_URI`	—	Engram connection URI (Bolt protocol)
`NEO4J_USER`	`neo4j`	Engram database user
`NEO4J_PASSWORD`	—	Engram database password
`NODE_ENV`	`development`	Set to `production` in service deployments

None of these are required — the gateway starts with defaults. Set only what you need to change.

Common questions

Q Does Engram require a paid Neo4j plan?

No. Neo4j Community Edition (free, open source) is all you need. Install it via Homebrew on macOS or the Neo4j Desktop installer. Engram uses the standard Bolt protocol on port 7687.

Q What happens if the gateway crashes?

launchd (macOS) and systemd (Linux) both have KeepAlive / Restart=on-failure configured. The service restarts automatically. The frontend shows an 'Offline — reconnecting...' banner and auto-reconnects with exponential backoff.

Q Can I run the gateway on a port other than 3001?

Yes. Set DAEMION_PORT=3002 (or any available port) before starting. Also update the gateway URL in the frontend settings to match.

Q Do I need Tailscale if I only use Daemion on localhost?

No. Tailscale is only needed for remote access from other devices (phone, another computer). If you only use the browser on the same machine as the gateway, localhost is fine.

Q The install script has my username hardcoded. Is that a problem?

The plist in system/daemon.plist has paths specific to the original setup. Before running install.sh, open daemon.plist and update the node path, working directory, and log paths to match your machine.

What can go wrong

Common setup issues

Engram shows unavailable at startup — Neo4j isn’t running, or NEO4J_URI / NEO4J_PASSWORD aren’t set. Run brew services list | grep neo4j to check. The gateway continues without Engram — it’s not a fatal error.

launchd shows the service but gateway isn’t responding — Check ~/.daemion/gateway.log for the actual error. The most common cause is a wrong node path in the plist for your Node version manager setup.

Phone can’t reach gateway over Tailscale — Confirm both devices show Connected in the Tailscale app. Verify DAEMION_PORT matches the port in your gateway URL. The gateway binds to 127.0.0.1 by default — Tailscale routes to that correctly when both devices are on the same Tailscale network.

EADDRINUSE :3001 — Another process (or a previous gateway instance) is holding the port. Find it with lsof -i :3001 and kill it, or set DAEMION_PORT to a different port.

What’s next?

How does Daemion work? — understand the gateway model and 6 kernel substrates
Pair a Device — full walkthrough for phone pairing via QR + OTP
Extending Daemion — create jobs, agents, and commands as extensions