Sona Quickstart

• macOS, Linux, or WSL on x64 or aarch64
• An LLM API key — Anthropic, OpenAI, Google, or a local Ollama
• A Telegram account (the bot is free; no card on file)

You do not need Java pre-installed — the installer bundles a JRE if you don't already have Java 21+ on your PATH.

1. Install (30 seconds)

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, writes a config template, and puts sona on your PATH.

Verify:

sona --version

You should see the current version + the JRE path.

2. Get a Telegram bot token (90 seconds)

In Telegram, open a chat with @BotFather:

1. /newbot
2. Pick a display name (e.g. My Sona)
3. Pick a username — must end in _bot (e.g. my_sona_bot)
4. Copy the token BotFather sends back. It looks like 123456:ABC-DEF....

3. Run sona init (90 seconds)

sona init

The wizard asks for, in order:

The wizard writes ~/.sona/sona.yml, then runs a health check (LLM ping + Telegram getMe). If both pass you're ready.

4. Start the daemon (30 seconds)

sona

The first time you run it, the daemon will log a banner like:

TnsAI Sona v0.3.0
Workspaces: 1
Channels:   1

The process stays running in the foreground. Open another terminal for the rest of this guide; sona stop shuts it down.

5. Send your first message (60 seconds)

Open your bot's chat in Telegram (t.me/<your_bot_username>) and send anything — hi.

Sona replies with a pairing code because it doesn't know you yet:

You: hi
Bot: Hi! I don't recognize you yet. Please share this pairing code
     with my owner to get access: 483921

You are the owner, so approve yourself from another terminal:

sona pair list           # show pending requests
sona pair approve 483921 # by code

(sona pair approve telegram:<your_telegram_user_id> also works if you'd rather skip the code.)

Send another message:

You: Summarize what TnsAI is in one paragraph.
Bot: TnsAI is a modular Java framework for building AI agents…

That's it — your daemon is processing a message, dispatching to an LLM, and replying through the Telegram adapter.

What just happened

Three TnsAI modules carried the round-trip:

1. tnsai-channels — The TelegramAdapter translated an incoming Telegram update into a UnifiedMessage.
2. tnsai-core — The session's Agent ran one BDI cycle: pulled belief state from the session, picked an action, called the LLM through tnsai-llm, streamed the reply back.
3. tnsai-channels again — The adapter rendered the agent's UnifiedResponse as a Telegram message.

Sona's only job is the routing in the middle: workspace selection, session lookup, pairing-policy enforcement, audit log. See How It Works for the full picture.

Next steps

• Talk to it from a terminal instead — sona chat opens a local REPL (JLine, streaming, slash commands). Add --json for newline-delimited JSON suitable for piping.
• Tail the logs — sona logs -f follows ~/.sona/sona.log in real time. sona logs --grep ERROR -i for case-insensitive filtering.
• Add tools — Sona ships with all 62 tnsai-tools POJO toolkits available. Toggle a per-user allowlist in ~/.sona/sona.yml under workspaces.<name>.tools.
• Add MCP servers — Drop a mcp_servers: block in sona.yml and Sona will register them through tnsai-mcp at start-up.
• Point a workspace at a project — Set project_dir on a workspace and Sona auto-loads AGENTS.md (falling back to CLAUDE.md / README.md) from that directory into the agent's system prompt at session boot. See Project context below.
• Drive Sona from a script — Every command takes --json and emits the same envelope. See the machine-readable mode reference.
• Stop — sona stop (SIGTERM) or sona stop --force (SIGKILL).
• Uninstall — sona uninstall --yes removes ~/.sona/ and the sona 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 augments the workspace's system_prompt with the parsed intro + sections. The operator's prompt always leads; the project context is appended, never substituted.

# ~/.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 (with lowercase + dot-prefixed variants). If none exist, the system prompt is unchanged — session boot never fails because of a missing or malformed context file. Project context is opt-in: a workspace without project_dir boots byte-for-byte the same as before (same role body, same agent principal id).

Troubleshooting

For deeper digging, see the Sona repo's README — it's the authoritative reference and tracks command changes as they ship.