Quickstart

1. A first session, local console

The fastest way to see the runtime work is the local chat surface; no channel and no bot token needed:

ka-agent chat

You get a console conversation over the same runtime the daemon uses: streaming text, notes, approval prompts (/y to approve, /n to deny), and a per-turn cost line. Type a request and watch the session state machine work.

2. Configure

ka agent reads ~/.config/ka-agent/ka-agent.toml (strict TOML: unknown keys are errors). A minimal file:

workspace = "~/projects/ka-agent-workspace"
mode = "guarded"
approval_ttl_secs = 900

workspace is the single directory every engine runs in (the MVP boundary).
mode is the permission mode for new sessions: guarded, accept_edits, free or plan. The worker re-asserts it after every attach.
approval_ttl_secs is how long an approval card waits before it denies.

A fully commented copy ships in examples/config/ka-agent.toml; the schema lives in crates/ka-agent-core/src/config.rs. See the config reference.

3. Run the daemon

ka-agent run

The daemon starts the runtime, binds the admin unix socket (ka-agent status talks to it), and idles until a channel delivers a message. Stop it with Ctrl-C: it shuts down gracefully on SIGINT and SIGTERM.

4. Add the Telegram channel

Create a bot with @BotFather, then:

Store the token in the secret store. Either the environment:
Terminal window
```
export KA_AGENT_SECRET_TELEGRAM_BOT_TOKEN="123456:ABC…"
```
or a 0600 file, single line, at <data>/secrets/telegram.bot_token. Secrets never go in ka-agent.toml; the config only names them.
Allow your numeric Telegram user id (usernames are never trusted; private chats only). Message @userinfobot to get your id, then:
```
[telegram]
enabled = true
token_secret = "telegram.bot_token"
allow_user_ids = [123456789]
```
Restart the daemon and message your bot:
```
/help     what the bot can do
/status   session, strand, budgets, queue
/new      start a fresh session
/stop     abort the running turn
```
Plain text goes to the engine. While a turn runs you see a typing indicator and an editable progress message; when the engine raises a permission ask, you get an approval card with Allow / Deny buttons and an expiry countdown. Unanswered cards deny when the TTL lapses.

What to expect next

The memory tiers, /history search, plugins and the scheduler arrive in the next milestones (see the roadmap). Everything above is behavior verified by the workspace test suite, including an end-to-end Telegram flow against a fake Bot API.