Neo

Appearance

Quickstart ​

You've installed Neo (see docs/user/install.md if not). This walks through the first-run wizard, your first chat, and turning on the pieces that make Neo more than a chatbot: a channel and the always-on daemon.

1. neo onboard ​

bash
neo onboard

If you start neo with no provider credentials configured at all, it offers to run this automatically. neo onboard --defaults runs it headlessly (no prompts — anything that needs an interactive answer is skipped and reported, not blocked on) for a fresh machine with no TTY.

The wizard sequences six steps, each of which reads existing state first and only prompts for what's actually missing — safe to re-run any time, and resumable if you Ctrl-C partway through:

  1. Provider auth — reports which providers (Anthropic, OpenAI, Gemini) already have working credentials. If none do, it points you at neo login and stops there; re-run neo onboard once you've logged in.
  2. Channel connect — offers to set up Telegram (bot token) and/or WhatsApp. WhatsApp is labeled and gated as experimental (unofficial protocol, account-ban risk) with a separate explicit confirmation before it asks for anything — see Honest labels in the README and channels.md.
  3. Allowlist / contacts — lets you add people Neo is allowed to proactively message, in a loop until you decline.
  4. Daemon install — offers to install the always-on Matrix daemon (the same consent-first flow as neo daemon install/neo login), so Neo keeps running, supervising channels and background jobs, between sessions.
  5. Doctor — runs the same diagnostics as neo doctor and prints anything that isn't OK.
  6. Tour — a short recap of what got configured, plus a few commands to try next.

2. Your first chat ​

Interactive:

bash
neo

Starts the TUI. Pass an initial message to seed the first turn:

bash
neo "what can you help me with?"

One-shot — print the response and exit, no TUI (good for scripting or piping):

bash
neo -p "summarize this file" < notes.txt

Programmatic — neo --json speaks a line-delimited JSON control protocol on stdio, for driving Neo from another program. See docs/user/agent-cli.md for the full protocol.

3. Add a channel ​

Telegram is the primary, production-ready channel:

bash
neo channels login telegram

You'll be asked for a bot token (from @BotFather). Once saved, the daemon (see below) supervises the connector; check its state with neo channels status.

WhatsApp is available but experimental — see channels.md before pairing a number.

4. Turn on the daemon ​

Channels, scheduled work, and background memory maintenance need the always-on daemon. It's opt-in:

bash
NEO_DAEMON=on neo daemon install   # register an OS autostart service (systemd/launchd/Task Scheduler)
neo daemon status                  # check it's running

Or run it in the foreground without installing autostart:

bash
NEO_DAEMON=on neo daemon run

By default the daemon runs at a conservative capability tier (memory maintenance and read-only tools); see daemon.md for tiers, what the daemon does, and how autostart works per platform.

5. The web dashboard ​

bash
neo ui

If a daemon is already running, this just prints the dashboard URL and opens your browser — the daemon's control plane is already listening. With no daemon, it starts a standalone control plane (default port 7777, override with --port) and keeps running until you stop it. The dashboard shows status, sessions, and agent activity, and is itself customizable — see ui-customization.md.

Where your data lives ​

Everything Neo stores — sessions, memory, config, logs, keychain fallback — lives under ~/.neo (override with NEO_HOME). Nothing here is uploaded anywhere; see privacy.md. neo export --all bundles the non-secret parts into a portable snapshot; neo uninstall removes Neo's OS-level footprint but never touches ~/.neo itself — see uninstall.md.

Next steps ​

  • routing.md — how Neo decides what handles a message (direct answer vs. delegation vs. a specialist team).
  • mechanisms.md — how Neo works under the hood: memory, reflection, skills.
  • cli.md — the full command reference (flags, exit codes, --json shapes).
  • env-vars.md — every environment variable Neo reads.
  • neo doctor — re-run diagnostics any time something feels off.