Repository layout

This page explains what every top-level file and directory in the Apollia OS repository is for, so a newcomer can orient quickly and a maintainer never has to guess what an unfamiliar root file does. It is descriptive: it says what each entry is, not how to change it.

Apollia OS is a Cargo workspace of Rust crates at its core, wrapped by a Python SDK, generated API clients, example agents, a documentation site, and the usual build, quality, and governance scaffolding. The sections below group the root entries by role.

Source directories

Path	What it is
crates/	The Rust workspace. Each subdirectory is one crate with a single responsibility. Members and their shared dependency versions are declared in the root Cargo.toml.
sdk/	The Python SDK (apollia package, "AgentKit"): the @tool and @workflow decorators, the Ctx type contract, and the describe command that writes the tool and workflow descriptors of a package into its apollia.toml. Packaged with pyproject.toml. This is the kit for authoring the Python of packages that run inside the runtime.
agents/	Bundled packages. agents/system/ holds the packages Apollia ships with (the onboarding agent, the in-app guide, the agent workshop); agents/starters/ holds the declarative agents the application proposes, each an apollia.toml with no code; agents/examples/ holds two small samples, hello (an agent with one Python tool) and word-count (a Python tool with no agent). Treat these as illustrations, not canonical templates.
clients/	Typed API clients a host application uses to drive a running Apollia runtime over its HTTP API (submit tasks, stream results, read the audit trail). TypeScript (clients/ts) and Python (clients/python) clients are generated from clients/openapi.json via clients/regen.sh, so they cannot drift from the wire contract. This is the opposite direction from sdk/.
tests/	The workspace-level integration and end-to-end test crate (apollia-e2e-tests), plus the CLI suite (tests/cli/) that exercises the runtime across crate boundaries. Per-crate unit tests live inside each crate instead.
fuzz/	The cargo-fuzz crate: libFuzzer targets (fuzz/fuzz_targets/) and their corpora (fuzz/seeds/). Built on its own with a nightly toolchain and excluded from the stable workspace, so the normal gates never try to compile it.
packaging/	Scripts and manifests that assemble a self-contained, relocatable Python runtime to bundle with the app (fetch a standalone interpreter, build the universal bundle, pin requirements-bundled.txt), plus platform launchers. Supports the zero-external-dependency principle.
scripts/	Developer and CI helper scripts: the guard corpus (check_*.py), the desktop end-to-end automaton (automation/), the Docker-backed Linux verification (linux-check.sh), and the linked-worktree helpers (worktree-prep.sh, worktree_verdicts.py).
docs/	All documentation (detailed below).

Documentation (docs/)

Path	What it is
docs/site/	The public documentation site (Docusaurus, English + French, Diataxis structure). This page lives here.
docs/agents/	The long-form rulebook for contributors (human and LLM): coding patterns, naming, testing, security, and the forbidden-practices list. English only.
docs/internal/	Release planning and internal notes. Gitignored and never shipped: a public checkout does not hold it.

The Rust workspace (crates/)

The workspace is defined in the root Cargo.toml. The default build excludes apollia-desktop (a heavy Tauri dependency, built explicitly) and two crates built in isolation under special flags (apollia-loom-models and the top-level fuzz crate). The main crates:

Crate	Responsibility
apollia-core	Shared types and the public contract used by every other crate.
apollia-runtime	The event bus, the Tokio actor supervisor, and the axum HTTP API (Unix socket + TCP 7771).
apollia-oria	The ORIA execution engine: classify, plan, gate, execute, verify, with the enforced StepBudget.
apollia-aip	The PyO3 bridge that runs the Python tools and workflows of installed packages in-process (Bound<'py, T>, pyo3-async-runtimes).
apollia-llm	LLM routing: the embedded llama-server (upstream llama.cpp) for local GGUF inference, and remote backends reached through one OpenAI-compatible client. Also the embeddings client, the model cards and the model recommender.
apollia-runner	The out-of-process speech-to-text runner sidecar (whisper). Local LLM inference no longer runs here; it goes through the embedded llama-server.
apollia-stt	Local speech-to-text (whisper).
apollia-mcp	The Model Context Protocol client (stdio / HTTP / SSE transports, untrusted-response caps).
apollia-tools	Built-in tool implementations.
apollia-memory	Agent memory persistence (SQLite + FTS5).
apollia-permissions	What governance decides from: the persisted fine rules, the standing consents by family of action, the organisation policy, and the code-executor guard.
apollia-auth	Authentication and OAuth2 (PKCE), secret storage via the OS keychain.
apollia-connectors	External service connectors.
apollia-triggers	Scheduled and event-driven triggers (cron, filesystem watch).
apollia-notifications	Notification delivery.
apollia-workspace	Workspace context collection: Git state, APOLLIA.md rules, file tree, conventions, with a TTL cache. No sandboxing: path confinement lives in apollia-tools.
apollia-prompts	Centralized prompt templates.
apollia-eval	Agent evaluation harness.
apollia-sources	The sources an agent may consult once checked (folders, files, mailboxes, the profile, memory): the actor that owns their registry in system.db.
apollia-signing	Offline signatures: Ed25519 for agent packages and organisation policies, and the verification of the minisign signatures on distribution metadata.
apollia-cli	The apollia-os command-line binary (clap, noun-verb, exit codes 0-5). apollia, without the suffix, is a different command: the SDK's own Python entry point. The only crate where anyhow and user-facing stdout are allowed.
apollia-desktop	The Tauri v2 + Svelte 5 desktop app (its UI lives in crates/apollia-desktop/ui/).

Governance and community files

File	What it is
README.md	Project overview and entry point.
AGENTS.md	The standard entry point for LLM coding assistants; routes to the docs/agents/ rulebook.
CONTRIBUTING.md	How to contribute (workflow, expectations).
.github/CODE_OF_CONDUCT.md	Community conduct standards. GitHub reads it from .github/ as it would from the root.
GOVERNANCE.md	How decisions are made and who maintains the project.
SECURITY.md	How to report a vulnerability and the supported-versions policy.
CHANGELOG.md	Human-readable record of notable changes per release.
ROADMAP.md	The direction of the project: what shipped, the version in progress, and the versions planned after it.
CITATION.cff	Citation metadata, in the Citation File Format, for anyone who references the project in a publication.

Licensing

Apollia OS is dual-licensed under MIT or Apache-2.0, at your option. This is the de facto standard across the Rust ecosystem (rustc, tokio, serde, axum, Tauri) and maximises downstream compatibility: a consumer picks whichever license fits their needs.

File	What it is
LICENSE-APACHE	The full Apache License 2.0 text.
LICENSE-MIT	The full MIT License text.
NOTICE	The third-party components the release packages redistribute beside the project's own code, each with its license.

Build and quality configuration

Each file below is read by a specific tool. The comments describe what it actually configures in this repository.

File	What it configures
Cargo.toml	The workspace root: crate members, shared dependency versions (each crate uses { workspace = true } rather than inline versions), workspace lints (unsafe_code = "deny", unwrap_used = "deny"), and the release/dev profiles.
Cargo.lock	The exact resolved dependency graph. Committed so every build and CI run compiles the identical versions.
rust-toolchain.toml	Pins the build toolchain to Rust 1.95.0 with rustfmt, clippy, rust-src, and rust-analyzer, so local and CI output match byte for byte. The declared MSRV floor (rust-version = 1.89 in Cargo.toml) is lower and separate.
clippy.toml	Clippy thresholds: MSRV 1.89, type-complexity 250, and at most 5 function arguments.
rustfmt.toml	Formatting: edition 2021, max_width = 100, reordered imports, field-init and try shorthands, Unix newlines.
deny.toml	cargo-deny policy: an allowlist of acceptable licenses, denial of unknown registries, a warning on duplicate dependency versions, and a documented, per-release list of ignored security advisories (each with its lift condition).
Cross.toml	cross-rs cross-compilation: pre-build steps that install the Linux system libraries (ALSA, PulseAudio, JACK, CMake, clang) into the build container for the x86_64 and aarch64 GNU/Linux targets.
justfile	just task recipes: the canonical commands for building, testing, linting, and running the desktop automaton. just alone lists them by group and just doctor checks the toolchain. Its settings are environment variables, listed with their defaults in .env.example; personal recipes go in an untracked justfile.local, after the model of justfile.local.example.
.pre-commit-config.yaml	The hook list, and the file to read for it rather than a copy of it: file hygiene and secret detection, ruff on sdk/, rustfmt and cargo check on the workspace, repository guards under scripts/ (the prose rules among them), and the documentation-site build. Two entries run outside the commit itself: clippy on push, and the commit-message convention at commit-msg. Not to be bypassed.
.editorconfig	Editor-agnostic whitespace rules: LF endings, final newline, and per-language indent sizes (4 for Rust/Python/TOML, 2 for web and Markdown).
.python-version	Pins the local Python interpreter (3.13.13) for tooling like pyenv.
.cargo/	Cargo defaults: config.toml sets build environment (macOS deployment target, an accelerated dev profile) and audit.toml holds the cargo-audit advisory ignores (mirrored from deny.toml).
.github/	GitHub configuration: CI, CodeQL, weekly deep-check, and release workflows (.github/workflows/), plus CODEOWNERS, issue and PR templates, dependabot.yml, and FUNDING.yml.
.gitignore	Paths git does not track (see below).

Local-only entries (gitignored, never shipped)

These appear in a working checkout but are not tracked, so they never reach the public repository or a release artifact. Presence depends on what you have run locally.

Path	What it is
docs/internal/	Release planning and internal notes.
target/	The Cargo build output directory.
.venv/, .venv-agents/	Local Python virtual environments.
.apollia-automation/, .apollia-seed-home/	Throwaway state produced by the desktop end-to-end automaton, which runs the app against a seeded, disposable HOME (see the note below).
.pytest_cache/, .ruff_cache/	Tool caches.
.DS_Store	macOS Finder metadata.

AGENTS.local.md and AGENTS.override.md are also gitignored by convention (per-machine and per-session contributor overrides); they may not exist in a given checkout.

What the seeded HOME covers. The two recipes that build it, automation-seeded and automation-seeded-llama, swap HOME for the throwaway copy before they launch the app, so the app under test reads and writes that copy only, never the real ~/.apollia profile. The recipes still reach into the real home in two places. Both resolve CARGO_HOME and RUSTUP_HOME from it (~/.cargo, ~/.rustup) before the swap, so the build uses the toolchain and the crate cache you already have rather than an empty one under the seed. And the -llama recipe, the one that drives a real model, reads one file from outside the seed, the model GGUF you name as its argument or in APOLLIA_LLAMA_MODEL, because the seed carries placeholder GGUF files rather than a runnable model. Both points are written where the recipes are implemented, in scripts/lib/automation.sh.