Skip to content

Quickstart

From a fresh clone to a working agentic run, offline, in about a minute.

1. Set up

git clone https://github.com/akaion-ai/annona.git
cd annona
make setup

Creates a virtual environment, installs runtime and development dependencies, and installs the annona command. Python 3.10+ is the only prerequisite.

Not building from source? pip install annona gives you the same CLI, and Install covers the desktop builds.

2. See it run

make demo

This is a real agentic loop — real tool execution against real files, real policy checks — driven by a scripted backend, so it needs no API key and opens no socket. It shows one task the policy permits and one it refuses:

1 · a task the policy permits
  1. ok      explorer         {'operation': 'map', 'path': '…/documents'}
  2. ok      document_reader  {'path': '…/reports/q1_report.txt'}
  answer     Q1 2026: 142 open matters, 98 closed, EUR 412,000 …

2 · a task the policy refuses
  1. denied  filesystem       {'operation': 'read', 'path': '~/.ssh/id_rsa'}
     → {'error': 'Permission denied for tool: filesystem'}

Nothing left the process. That is the product in one screen.

3. Start the runner

make run          # or: ./start.sh

Open http://127.0.0.1:7070. No account is required — pick Open my vault and you are in local-only mode. Notes live under ~/akaion-brain/ as plain markdown.

4. Configure

annona setup      # the policy and the configuration, in three questions
annona doctor     # check the install can actually run a step
annona status     # config, vault stats, connection state

annona setup is the one command a new install needs. It writes both files the kernel reads — ~/.akaion/config.yaml and ~/.annona/policy.yaml — and then checks that the model the policy names is really on this machine. See Install for what it asks and why.

The default configuration is local-first: cloud.enabled: false, so the runner never contacts a remote host until you ask it to. See Configuration for every key, and read the warning about allow-lists before relying on the policy.

5. Connect to the cloud — optional

annona login        # opens a browser for Google sign-in
annona cloud enable
annona sync push --all-pending

Sync is push-only, per note, on your command. Cloud content is never written back into your vault.

To point at your own backend instead of Akaion's, set AKAION_API_BASE and implement three endpoints — see Self-hosting in the README.

Commands

annona login / logout           # cloud credentials
annona setup                    # create the configuration
annona run                      # start the daemon and local UI
annona run --once --task "…"    # execute a single task
annona run --no-cloud           # force local-only for this run
annona run --port 7171          # serve the local API elsewhere
annona status                   # config, vault, connection
annona logs -f                  # follow the log
annona config                   # show, edit or reset the configuration
annona dashboard                # interactive terminal dashboard
annona version

annona note add "title"         # create a note ($EDITOR, --stdin or --from-file)
annona note list                # list notes, filterable by sync status
annona note show <id|prefix>    # metadata and content
annona note edit <id|prefix>    # edit; a synced note returns to pending
annona note delete <id|prefix>
annona note search "query"      # full-text search

annona sync status              # what is local, pending, synced or failed
annona sync push --all-pending  # push every pending note
annona sync push --id <id>      # push specific notes
annona sync push --dry-run      # show what would happen

annona cloud enable / disable   # turn cloud sync on or off
annona cloud status

Every command takes --help. dogana and akaion are aliases for annona, kept so older scripts keep working.

annona run --once tells a script how the step ended, not only whether it raised:

exit the step
0 completed
1 failed: an error, printed
2 was not started: a usage error (--once without --task)
3 was held by the perimeter. Nothing ran and nothing left; annona audit --held says why
4 was queued: a permitted substrate is down and the rule waits for it

A held step is the product working, but it is not finished work: a cron job that treats 3 as success has been told no and not noticed.

Running the tests

make check        # lint · types · architectural contracts · tests
make test         # tests only
make test-cov     # with a coverage report

make check is exactly what CI runs. No credentials, no network.

Building the desktop app

The desktop app is a Tauri 2 shell wrapping the Python daemon as a PyInstaller sidecar.

./scripts/build-sidecar.sh          # PyInstaller → ui/src-tauri/binaries/
cd ui && npm install && npm run tauri:build
#   → src-tauri/target/release/bundle/dmg/Akaion Runner_<ver>_<arch>.dmg

Prerequisites: the Rust toolchain, Node 18+, and a venv created by make setup.

For UI development with hot reload against the real sidecar:

./start.sh --tauri-dev

Windows and Linux bundles are produced by CI rather than locally — see Releasing.

6. Take work from Agents Studio — optional

To let people in your organisation send jobs from Agents Studio to this machine, which runs them under its own policy and sends back only what the policy allows, see Link a machine to Agents Studio. Nothing talks to Studio until you enroll.

Where to go next