Daemion docs

How do I set up Daemion fully?

~15–20 minutes
Prerequisites: Completed quickstart, daemion CLI installed

The quickstart gets you running locally. This guide covers the optional operational pieces: Tailscale for phone access from anywhere, a background service so the gateway survives reboots, and environment configuration.

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.

What powers memory now?

Daemion’s current memory stack is built in:

  • compiled wiki pages
  • agent-specific wiki spaces
  • raw captured sources
  • searchable conversation history

You do not need Neo4j or a separate graph store to get useful persistent memory in the current product.

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?

VariableDefaultWhat it does
DAEMION_PORT3001Port the gateway listens on
DAEMION_DB_PATH~/.daemion/daemion.dbPath to the SQLite database file
DAEMION_TOKEN_PATH~/.daemion/.gateway-tokenPath to the stored bearer token
NODE_ENVdevelopmentSet 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 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

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?