Arawn

A self-hosted personal agentic assistant in a single Rust binary. Runs a local WebSocket server, talks to any OpenAI-compatible LLM (Groq, Ollama Cloud, local Ollama, OpenAI), and exposes a TUI for interactive sessions plus a workflow runtime for scheduled background jobs.

Status: alpha. Breaking changes expected. Suitable for hacking on, not for putting in front of users yet.

30-second quickstart

# 1. Build
cargo build --release

# 2. Scaffold a starter config (~/.arawn/arawn.toml)
./target/release/arawn init --provider groq
# (override the model/key env with --model / --api-key-env; --force overwrites)

# 3. Set the API key (arawn init prints the exact variable to export)
export GROQ_API_KEY=gsk_…

# 4. Run the server
./target/release/arawn serve

# 5. In another terminal, open the TUI
./target/release/arawn tui

Type a message in the TUI and arawn will respond using the configured model. The agent has tools for shell, file editing, web search, and more.

To connect Gmail, Calendar, Drive, Slack, Jira, Confluence or GitHub, run arawn setup. It walks through each provider's console, then writes the credentials into arawn.toml. Restart arawn serve, then run arawn connect --all to approve each one in the browser. arawn doctor shows what is still missing.

For Ollama Cloud (OLLAMA_API_KEY instead, model like gemma4:31b-cloud, provider https://ollama.com/v1) and the full troubleshooting walkthrough, see docs/src/content/docs/tutorials/first-chat.md.

What's in here

• crates/arawn/ — the binary, CLI, server entry points
• crates/arawn-engine/ — agentic loop, tool registry, permissions, plugins
• crates/arawn-llm/ — provider-agnostic LLM client (OpenAICompatibleClient, retry, warmup caching)
• crates/arawn-tui/ — terminal UI client
• crates/arawn-memory/ — persistent knowledge base (global + per-workstream)
• crates/arawn-workflow/ — scheduled DAG pipelines (cron + on-demand)
• crates/arawn-tests/ — integration + UAT (LLM-as-judge) tests
• .metis/ — work tracking (vision, initiatives, tasks). See .metis/vision.md.

CLI

arawn                       # one-shot prompt (uses running server)
arawn init                  # write a starter config (LLM only)
arawn init --profile work   # ... plus a work lens and the standard work feeds
arawn setup                 # set up integrations: Google, Slack, Atlassian, GitHub
arawn connect --all         # approve each set-up integration in the browser
arawn doctor                # check the install
arawn serve                 # start the WebSocket server
arawn tui                   # launch the TUI client
arawn plugin <subcommand>   # plugin management
arawn --list-sessions       # list resumable sessions
arawn --session <uuid>      # resume a specific session

--data-dir <path> (or ARAWN_DATA_DIR) overrides the data directory (default: ~/.arawn).

Development

Tasks are run via angreal:

angreal build workspace        # cargo build
angreal test unit              # workspace lib tests
angreal test integration       # ignored integration tests
angreal test uat               # end-to-end against a real LLM
angreal check all              # fmt + clippy + cargo check
angreal docs serve             # serve docs locally (Starlight)

Code map and semantic summaries live in .metis/code-index.md. Work tracking is in .metis/ — see active initiatives and backlog tasks.

Vision

A lightweight, self-hosted personal agentic assistant that runs scheduled tasks, monitors channels (email, GitHub, etc.), surfaces action items, and provides an interactive chat interface — all from a single Rust binary with a minimal resource footprint.

Full vision: .metis/vision.md.