macOS, Linux, or WSL on x64 or aarch64
An LLM API key — Anthropic, OpenAI, Google, or a local Ollama

You do not need Java, Telegram, or BotFather. Telegram is a channel you add later if you want it.

1. Install

curl -fsSL https://tnsai.dev/install/sona.sh | bash

This drops the JAR into ~/.sona/, bundles Eclipse Temurin JRE 21 if your system Java is < 21, and puts sona on your PATH.

Verify:

sona --version

You should see the current version and the JRE path.

2. Configure

sona init

The wizard asks who you are and what this Sona is for. Then you pick an LLM provider by number and type the model id (no default — examples are hints only). Then the API key. Telegram is optional — press Enter to skip. Add a bot later with sona channel add telegram (see Telegram).

The wizard writes ~/.sona/sona.yml. If you skipped the bot, it does not write a channels.telegram block.

3. Talk

sona chat

Type a question. /help lists commands. /exit returns to the shell.

That's the first hour. A daemon (sona with no arguments) is only needed when a messaging channel is configured.

Optional: add Telegram later

When you want the same Sona on your phone:

Create a bot with @BotFather (/newbot) and copy the token.
Run sona channel add telegram and paste the token (or set TELEGRAM_BOT_TOKEN).
Start the daemon: sona.
Open the bot and send hi. A fresh install has no owner — reply YES in that same chat to claim it. Later unknown senders get an 8-character pairing code for sona pair approve <code>.

Do not pass telegram:<userId> to approve. That is not a pairing code.

Full steps: Telegram.

Next steps

Other channels — sona channel add slack|discord|whatsapp|email.
Logs — sona logs -f follows ~/.sona/sona.log.
Project context — set project_dir on a workspace and Sona auto-loads AGENTS.md (falling back to CLAUDE.md / README.md) at session boot. See below.
Scripts — most commands take --json. See machine-readable mode.
Stop / uninstall — sona stop. sona uninstall --yes removes ~/.sona/ and the launcher.

Project context via AGENTS.md

When a workspace's project_dir points at a code repo, Sona reads that repo's AGENTS.md (agents.md spec) at session boot and appends it to the workspace system_prompt. Your prompt always leads.

# ~/.sona/sona.yml
workspaces:
  code:
    system_prompt: "You are a coding assistant."
    project_dir: "/Users/me/repos/my-project"   # opt-in

Fallback order is AGENTS.md → CLAUDE.md → README.md. Missing files do not fail boot. A workspace without project_dir is unchanged.

Troubleshooting

Symptom	Likely cause	Fix
`sona init` says "LLM health check failed"	Wrong key, wrong model, or no network	Re-run `sona init` and check the key
`sona chat` says the API key env var is not set	Wizard wrote `${ANTHROPIC_API_KEY}` (or similar) and the env is empty	Export the key, or paste it when `sona init` asks
`command not found: sona`	Installer couldn't write to your PATH	`source ~/.zshrc` or add `~/.local/bin` to `PATH`
Bot doesn't respond	Daemon isn't running, or another process has the token	`sona status`; only one daemon can poll a token
First Telegram `hi` asks you to reply YES	Fresh install — no owner yet	Reply YES in that chat (not a second terminal)

Docs: sona.tnsai.dev/docs.

Sona Quickstart