README.md
Rama main · réplica de lectura del repositorio original.
# Aivyx PA
[](https://github.com/Aivyx-Agent/aivyx-pa/actions/workflows/ci.yml)
[](LICENSE)
> A personal autonomous agent platform that runs on your hardware,
> talks to cloud LLMs under your own API key, and never compromises
> privacy or auditability for the sake of a feature.
Aivyx PA is a Rust-built agent framework whose load-bearing
properties are **capability-based security**, **HMAC-chained
auditability**, and **encryption at rest**. It does not run as a
hosted service. There is no Aivyx-the-company server in your
agent's request path; your API key talks directly to the LLM
provider, your data stays on your hardware, your audit chain is
verifiable offline.
> **Where Aivyx is headed:** [`VISION.md`](VISION.md) — the mission
> (*Build It Right First*), what Aivyx is, the architecture's
> destination (local teams becoming a network of agents), and the
> discipline every chapter is held against.
## Status (v0.19.2 — source-available, BUSL-1.1, 2026-10-25)
| | |
|---|---|
| Phases shipped | Phase 0 → the complete Studio, plus every chapter since (the per-chapter list is in [`CHANGELOG.md`](CHANGELOG.md) and [`docs/ROADMAP.md`](docs/ROADMAP.md)) |
| Forward-commitment ledger | **Closed** — all 14 PRODUCT.md commitments (P1–P14) and all 7 goal commitments (G1–G7) shipped; subsequent chapters extend the platform within the locked contract |
| Release pipeline | **Active** — on each version tag, cargo-dist builds the CLI (Linux x86_64/aarch64 musl + macOS x86_64/aarch64) and a separate workflow builds the **desktop app** (`.deb` + macOS `.app`); both attach to the GitHub Release. Latest is **`v0.20.1`** (a Matrix encryption security update; v0.20.0: a clearer first run and Studio: a grouped sidebar, readable text, empty screens that say how to start, routines that wait for the model, `/help` and `/quit` in the terminal chat, a Studio link only when the Studio really runs, and a spreadsheet-reader security update; v0.19.4: security: approvals bound to the exact call, the file tools cannot write pa's config or dotfiles, a sandboxed loop gate, destructive shell commands confirm, and the rest of the 2026-10-28 audit; v0.19.3: security: a repository can no longer steer the checkpoint git outside the sandbox, and invisible characters no longer hide injection phrases; v0.19.2: a checkpoint is no longer skipped after a failed one, and a Slack dependency security update; v0.19.1: a killed assistant no longer leaves its shell commands running, and Ctrl-C stops a running command at once; v0.19.0: three private chat channels in preview — Matrix, Proton Mail and Signal — and a sandbox that keeps your home folder's secrets and login files out of reach at access `home`/`full`; v0.18.2: pack and network safety fixes — packs can't write outside their folder or change your access, Studio or programs, and `web.fetch` blocks Tailscale addresses — and a terminal that says why a turn stopped; v0.18.1: a TLS dependency security update; v0.18.0: config packs: `aivyx-pa pack install` turns a signed, configuration-only pack into a ready-made new assistant — its profile, team, skills and routines — and `pack inspect`/`pack check` show and check a pack first; v0.17.0: supervised batching: at `supervised`, a routine, webhook, the loop or a team mission parks a step that needs your approval for you to review together in the Command Center or with `aivyx-pa review`, instead of refusing it; v0.16.0: different autonomy levels per area — say manual for email, unleashed for files — and two safety fixes: switching access level no longer turns off delete/overwrite confirmation, and emails and other outbound actions ask at every autonomy level; v0.15.0: named instances: run several fully separate agents as one user with `--instance <name>` and `aivyx-pa instances`; v0.14.8: a dependency security update; v0.14.7: a hardened sandbox for shell and git: no reaching local daemons, escaping through symlinks or renames, or outliving the call, and git hooks no longer see the daemon's secrets; routing decides local vs cloud by address; v0.14.6: a more accurate prompt-injection check that also reads whole web pages and files; v0.14.5: checkpointing recovers after a cancelled snapshot and keeps denied files out of snapshots; skill files are read safely; v0.14.4: checkpoints never run a git filter or hook a project planted; v0.14.3: no tool can write inside a `.git` folder, so a planted git setting can't run code; v0.14.2: a lighter Command Center that says when spend is incomplete and counts digests once; v0.14.0: a Studio home that reads like a logbook: what needs you, what your assistant did since you were last here, and what's next — and the `manual` autonomy level now asks before every change; v0.13.0: approve or deny an irreversible action in the terminal or the Studio and the reply carries on; Ctrl-C works through the daemon; v0.12.2: integrations act from chat once you reply, and budget/rate caps hold everywhere; v0.12.1: deleting or overwriting a file always asks you first; v0.12.0: a first run that just works: config found from any directory, the passphrase set up in `init` — keyring or an owner-only file — the daemon and Studio starting on their own, a chat that remembers the conversation, and a welcoming Studio; plus a desktop app that ships its daemon) via the [shell installer](docs/INSTALL.md#shell-installer-recommended), the [desktop app](docs/INSTALL.md#desktop-app), or the [WSL distro](docs/INSTALL.md#windows-wsl2-or-docker) |
| Studio (web GUI) | **Complete** — all 24 screens live (see below); offline, local-first, served on `:7843` |
| Workspace crates | 44 |
| Rust tests | 7,290 passing |
| Python conformance tests | 24 passing |
| Clippy warnings | 0 |
| Capability scope bases | 95 |
| Encrypted storage domains | 28 |
## Five-minute setup
**1. Install** — the one-line installer drops a prebuilt `aivyx-pa`
binary into `~/.cargo/bin` (no Rust toolchain needed):
```sh
curl --proto '=https' --tlsv1.2 -LsSf \
https://github.com/Aivyx-Agent/aivyx-pa/releases/latest/download/aivyx-cli-installer.sh | sh
```
**2. Have a model to talk to.** Either a local model server —
[Lemonade](https://lemonade-server.ai), [Ollama](https://ollama.com),
llama.cpp's `llama-server`, Jan, or `aivyx-broker` — running with a
tool-capable model, or an Anthropic / OpenAI API key.
**3. Set it up:**
```sh
aivyx-pa init
```
`init` finds the model server you have running (or asks for a key),
lets you pick a model, asks a few questions about you and your
assistant, sets a passphrase for the encrypted store (kept in your OS
keyring, or — with no keyring — in a file only you can read), offers
the default background routines, and finishes by checking that your
model answers. The config lands in
`~/.config/aivyx-pa/aivyx-pa.toml`, so `aivyx-pa` works from any
directory. (`AIVYX_PA_CONFIG_PATH` points at a config elsewhere; a
`./aivyx-pa.toml` in the current directory is not read.) Want a head start?
`aivyx-pa init --template coder` (or `researcher` / `personal`) pre-fills
the wizard — see [`docs/TEMPLATES.md`](docs/TEMPLATES.md).
**4. Use it:**
```sh
aivyx-pa # chat in the terminal
aivyx-pa studio # prints your sign-in link to the Studio (the web GUI)
aivyx-pa doctor # re-check the whole setup any time
```
The **Studio** opens on the **Command Center**; **Chat** is where you
talk to the agent, **Memory** shows what it has learned, **Documents**
reads and edits files in scope, **Settings** adjusts access, autonomy
and budgets, and **Audit** holds the HMAC-chained log (with offline
**Verify chain**). The **Guide** screen is the in-app user guide.
To keep it running for days (scheduled routines firing, the loop
available), install it as a background service:
`aivyx-pa daemon install` (Linux/macOS; survives logout + reboot). See
[`docs/INSTALL.md`](docs/INSTALL.md#running-as-a-service--runs-for-days-chapter-anchor).
**Prefer to compile?**
```sh
git clone https://github.com/Aivyx-Agent/aivyx-pa
cd aivyx-pa
cargo build --release --bin aivyx-pa
./target/release/aivyx-pa init
```
**Want an always-on server instead of a local binary?** `docker
compose up` runs Aivyx PA as a homelab/VPS **appliance** (daemon +
Studio in a container) — a different, deliberately-scoped profile
from the local-first install. See
[`docs/INSTALL.md`](docs/INSTALL.md#docker--the-server-appliance)
and [`docs/DOCKER.md`](docs/DOCKER.md).
**Want a native app instead of the CLI?** Aivyx PA ships **`aivyx-desktop`** —
the Studio in a native window with a system tray, approval notifications, and a
summon hotkey. Grab the `.deb` (Linux) or `.app` (macOS) from the
[latest release](https://github.com/Aivyx-Agent/aivyx-pa/releases/latest), or see
[`docs/INSTALL.md`](docs/INSTALL.md#desktop-app).
**On Windows?** There's no native Windows binary yet (the daemon's
Unix-socket IPC + `0600` secret-at-rest model are Unix-specific).
Run the same Linux binary under **WSL2**, or use the **Docker**
appliance above — both fully supported. See
[`docs/INSTALL.md`](docs/INSTALL.md#windows-wsl2-or-docker).
**Terminal UI and multi-agent teams:**
```sh
aivyx-pa tui # the terminal UI
aivyx-pa team roster # the default 9-role Nonagon team
aivyx-pa team run "research the latest on X and draft a summary"
aivyx-pa team roster --config crates/verticals/aivyx-kitchen/assets/kitchen-boh.toml # from a source checkout
```
`aivyx-pa team run` hands the mission to a **lead** agent that decomposes it
into a DAG, delegates to least-privileged specialists, verifies, and
synthesizes — every step on the one HMAC chain. A **vertical pack** swaps in
a domain crew via `--config <pack.toml>` (the kitchen Back-of-House Nonagon
is the worked example). See [`docs/NONAGON.md`](docs/NONAGON.md).
For a hand-written config (every section, commented), see
[`examples/aivyx-pa.toml`](examples/aivyx-pa.toml). For a Telegram
adapter, see [`examples/aivyx-semitrusted.toml`](examples/aivyx-semitrusted.toml).
For the full install matrix, see [`docs/INSTALL.md`](docs/INSTALL.md).
**The manual** — [`docs/manual/`](docs/manual/README.md): the user guide
(also built into the Studio), a reference for every command, config key,
tool and file, and a developer part.
## Highlights
- **Runs on your hardware, no API key.** The headline path is local inference —
`aivyx-pa init` detects a running Lemonade, Ollama, llama.cpp, Jan or
`aivyx-broker` server, and `aivyx-pa doctor` confirms the path end to end.
Anthropic / OpenAI are optional, under *your* key, talking directly to the
provider.
- **Secure by construction.** Capability-based scopes + trust tiers bound
exactly what the agent can reach; every action lands on an **HMAC-chained,
offline-verifiable audit log**; storage is encrypted at rest
(Argon2id → HKDF → ChaCha20-Poly1305).
- **Operator-chosen reach.** *You* pick how far the agent reaches —
**sandbox** / **workspace** / **home** / **full** — as an audited setting
(`aivyx-pa access`); irreversible filesystem ops are confirm-first.
- **Operator-chosen autonomy.** *You* pick how autonomous the agent is —
**manual** / **assisted** / **supervised** / **autonomous** / **unleashed** —
one dial (`aivyx-pa autonomy`, or the Studio) that composes the safety knobs and
arms the autonomous loop. Autonomy is a choice you make, never one the agent
grows into: it cannot widen its own reach or rewrite its own identity.
- **A self-learning identity.** A user-defined **Profile** plus a
reflection-written **Persona/Soul**, seedable at first launch (by hand or
*"describe it and the model drafts it"*) and governed through approve / edit
/ reject proposals. **Skills sharpen — and grow — through use**: the agent
measures how each saved skill performs and proposes a refined version of an
underperforming one, *and* authors brand-new specialized skills from its own
consolidated knowledge (the wiki + graph) — all governed the same way.
- **Memory that compounds.** Encrypted, topic-keyed memory with
**graph-augmented recall** — meaning (vectors), words (BM25), and association
(a multi-hop co-occurrence walk) fused on one ranking — an opt-in
**knowledge-wiki layer** that consolidates each topic into a browsable,
backlinked page, and a **typed knowledge graph** of directed
`(subject)-[predicate]->(object)` relations the agent extracts from memory
and can **query** (`graph.query` — "what depends on X?") or fuse back into
recall. Each layer is derived, opt-in, and off by default — turn the whole
coherent stack on with one line, **`[memory] profile = "smart"`**.
- **Multi-agent teams (Nonagon).** A lead convenes up to **9** least-privileged
specialists, decomposes a mission into a DAG, delegates, verifies, and
synthesizes — durable, resumable, on the one HMAC chain; **vertical packs**
swap in a domain crew. Build your own team from the GUI (no TOML by hand) via
the Studio's Teams screen, and watch/steer a running one live via **Mission
Control** — a LEAD/specialist graph with drill-in and abort/pause/resume.
- **The Studio — a local-first web GUI.** Twenty-four offline, Stitch-styled
screens served on `:7843`: Command (the dashboard), Chat, Missions, Mission
Control (a live team mission's LEAD/specialist graph, drill-in, and
abort/pause/resume controls), Schedules (cron routines), Memory (+
co-occurrence graph), Wiki (synthesized knowledge pages), Graph (typed
knowledge graph), Create (guided agent onboarding), Agents, Skills (the
skill library + effectiveness), Teams, Documents (browse + edit), Audit,
Sessions, Gallery (ComfyUI images), Notifications, Loop (autonomous-loop
control), Reminders, MCP (server health), Tools (the tool catalog), Voice,
Settings, Guide (the in-app end-user guide).
- **One onboarding, two surfaces.** A guided "create your agent" flow (Profile →
Persona seed → access) drives the **same** drafters and config writers from
both `aivyx-pa init` (CLI cold-start) and the Studio (live daemon).
- **More frontends, one daemon.** A terminal TUI (`aivyx-pa tui`), the CLI, and
channel adapters — Telegram, Discord, Slack, voice.
- **Productivity integrations.** Gmail, Calendar, Drive, Contacts, Notion,
Obsidian, n8n, plus a web/task/health toolkit — each a sandboxed,
operator-OAuth tool process.
- **Autonomy with brakes.** An autonomous, self-re-arming loop and a
non-interactive **headless mode** (refuses-and-aborts at gates, never
auto-approving), with **cost governance** (per-turn dollar pricing and
`[budget]` caps) and **tool-call rate limits** (`[rate_limit]` per-turn /
per-tool / sliding-window quotas that alert or deny).
- **Model routing (opt-in).** Off by default. A `[routing]` section lets the
daemon pick a model per call — by tool/vision needs, context size and task
tier — across your `[agent]` model and other local models or servers, with
cooldown + fallback when one fails. See `[routing]` in
[`examples/aivyx-pa.toml`](examples/aivyx-pa.toml).
The full phase-by-phase arc lives in [`docs/ROADMAP.md`](docs/ROADMAP.md); the
recent-release narrative in [`CHANGELOG.md`](CHANGELOG.md).
### What's next
The v0.6.0 arc (the toolbox release) **widened what the agent can do**:
a pure-compute utilities pack (Chapter Abacus), structured-data readers over
`fs.read` (Chapter Sheaf), and the wiring that turns the whole MCP server
ecosystem into an operator-config story — secrets, headers, and `aivyx-pa mcp
status` (Chapter Conduit). That last one reframes "new integrations": GitHub,
weather, Google Tasks and the rest are now a few lines of `[[mcp_server]]`
config, not in-tree builds. From here:
- **GPU-accelerated local inference.** The in-process mistral.rs path runs on
CPU today; a CUDA backend is a build-flag away once the upstream
`cudarc`/`mistralrs` stack supports newer CUDA toolkits — the one tracked
blocker on a fast local on-ramp.
- **Verticals as packs.** The free PA core stays the substrate; domain crews
ship as **vertical packs** (a Nonagon team + tools over a `TeamConfig`), with
the Kitchen BOH pack as the working template.
Direction is set per-arc as the running core demands it — never built ahead of a
real need.
## Release pipeline status
The release pipeline is **active** on the public repo. The latest
release is `v0.19.2` (see the CHANGELOG for what shipped):
- `.github/workflows/release.yml` (cargo-dist-generated) cross-compiles
the CLI for x86_64/aarch64 Linux musl + x86_64/aarch64 macOS on every
`v*.*.*` tag push, then publishes a GitHub Release with the
binaries, checksums, and the one-line shell installer.
- `.github/workflows/desktop-release.yml` builds the **desktop app**
bundles (a `.deb` on Linux, a `.app` on macOS) and uploads them to that
same release — it waits for cargo-dist to create the release first, so
the two never race on creation.
- `.github/workflows/docker-publish.yml` builds + pushes the **server
appliance image** to GHCR on the same tag.
- `.github/workflows/wsl-release.yml` reuses that appliance image to export
a **WSL distribution** (`Aivyx-PA.wsl`) — the daemon pre-installed for
Windows/WSL2 users — and attaches it to the release. This is the
cheapest real "Aivyx PA on Windows" path: it sidesteps the deferred native
Windows port (the daemon's Unix-socket IPC just works inside WSL2's Linux
kernel). See [docs/INSTALL.md](docs/INSTALL.md#windows-wsl2-or-docker).
- `.github/workflows/ci.yml` runs `cargo clippy --workspace --all-targets
-- -D warnings` and `cargo test --workspace` on every push to
main and every PR.
- `.github/workflows/quality-gate.yml` is the shared reusable
workflow both CI and release pipelines call — the release
short-circuits if the gate fails, and it also confirms every
workspace git dependency is anonymously cloneable before running
tests/clippy (the exact check that would have caught the bug behind
`v0.9.0`'s failed release; see
[docs/archive/phases/PHASE_192.md](docs/archive/phases/PHASE_192.md)).
Cutting a release is a single step: `git tag vX.Y.Z && git push
origin vX.Y.Z`, and the workflow publishes the binaries + installer.
## Architecture at a glance
```
operator
│
▼
channel adapter (CLI / Telegram / Web UI / third-party)
│
│ Unix-socket IPC (mode 0600)
▼
aivyx-pa daemon
├── turn loop (capability check → audit → execute → audit)
├── HMAC-chained audit log (offline-verifiable)
├── encrypted redb store (Argon2id → HKDF → ChaCha20-Poly1305)
├── 15 substrate tools + role-gated infrastructure tools
└── tool process bridge (third-party + productivity tools as subprocesses)
```
Forty crates in the workspace. The substrate core:
| Crate | What it owns |
|---|---|
| `aivyx-core` | `Agent` / `Tool` traits, turn loop, the 15 substrate tools (incl. `web.extract`, `git.commit`) |
| `aivyx-capability` | `Scope`, `CapabilitySet`, `TrustTier`, the active scope bases |
| `aivyx-crypto` | Argon2id, HKDF-SHA256, ChaCha20-Poly1305 |
| `aivyx-storage` | redb-backed encrypted store, 28 key domains |
| `aivyx-audit` | HMAC-chained audit log, offline verification |
| `aivyx-config` | TOML + env loader with source provenance |
| `aivyx-llm` | `LlmProvider` trait + Anthropic / OpenAI / Ollama impls |
| `aivyx-memory` | `memory.{read,write,forget,gc}` + redb-backed substrate |
| `aivyx-channel` | Daemon, CLI/Local channel, Web UI, mission/schedule/reflection/loop machinery |
| `aivyx-ipc` | wasm-clean wire protocol shared by the daemon and the Dioxus web client |
| `aivyx-mcp` | MCP client adapter (stdio + SSE) |
| `aivyx-tool` | Tool process IPC bridge + sandbox wrapper layer |
Channel adapters — `aivyx-telegram`, `aivyx-discord`,
`aivyx-slack`, `aivyx-voice`.
Productivity integrations (Chapter F/G — each a sandboxed
operator-OAuth tool process) — `aivyx-gmail`, `aivyx-calendar`,
`aivyx-drive`, `aivyx-contacts` (Google People API),
`aivyx-notion`, `aivyx-obsidian`, `aivyx-n8n`,
`aivyx-toolkit` (web.search + task.* + health.check.*), with
`aivyx-google-oauth` + `aivyx-auth-cli` providing the shared
OAuth substrate.
## Where to look next
**For operators** wanting to use Aivyx PA:
- [`docs/manual/`](docs/manual/README.md) — the manual: guide,
reference, developer.
- [`docs/ONBOARDING.md`](docs/ONBOARDING.md) — creating your agent:
the guided Profile → Persona → access flow, shared by `aivyx-pa init`
and the Studio's **Create** screen.
- [`docs/COMPATIBILITY.md`](docs/COMPATIBILITY.md) — the 1.0 stability
promise: what stays stable, what does not, and how changes are made.
- [`docs/THREAT_MODEL.md`](docs/THREAT_MODEL.md) — what Aivyx PA
defends against, what it doesn't. Read this before deploying.
- [`examples/`](examples/) — worked TOML configs for Ollama,
Anthropic, and the SemiTrusted (Telegram) tier.
**For users & operators** wanting to know what the agent can do:
- [`docs/TOOLS.md`](docs/TOOLS.md) — the **tool catalog**: every tool, its
capability scope, minimum trust tier, and how it's delivered (the agent can
also enumerate its own tools at runtime via the `tools.list` tool).
**For contributors** adding channels, tools, or capabilities:
- [`docs/CHANNEL_SDK.md`](docs/CHANNEL_SDK.md) — v0 contract for
writing a channel adapter (in any language; see
[`examples/python-channel/`](examples/python-channel/)).
- [`docs/TOOL_SDK.md`](docs/TOOL_SDK.md) — v0 contract for
writing a tool process (in any language; see
[`examples/python-tool/`](examples/python-tool/)); for the catalog of tools
that *already exist*, see [`docs/TOOLS.md`](docs/TOOLS.md).
- [`docs/ADAPTER_PATTERN.md`](docs/ADAPTER_PATTERN.md) — checklist
for in-tree adapters.
- [`docs/DAEMON_IPC.md`](docs/DAEMON_IPC.md) — wire format for
the daemon's IPC protocol.
**For architects** wanting to understand the design:
- [`DESIGN.md`](DESIGN.md) — locked technical contract (14 amendments)
- [`PRODUCT.md`](PRODUCT.md) — locked product contract (P1–P14)
- [`docs/ROADMAP.md`](docs/ROADMAP.md) — phase-by-phase narrative
- [`docs/PRODUCT_ROADMAP.md`](docs/PRODUCT_ROADMAP.md) — product-shape milestone narrative
- [`docs/`](docs/) — living reference docs + roadmaps (per-phase journals are archived under [`docs/archive/`](docs/archive/))
## Building & testing
```sh
# Pre-commit hook (recommended once per clone)
./scripts/install-hooks.sh
# Full sweep
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
# Python conformance suites (no daemon required)
python3 -m unittest discover examples/python-channel/tests
python3 -m unittest discover examples/python-tool/tests
```
The pre-commit hook runs `cargo clippy --workspace --all-targets
-- -D warnings` before every commit — the workspace has held at
zero warnings since the Phase 9 hook was wired.
## Contributing
This is a single-operator personal-agent platform by design
(PRODUCT.md P1 + P6). Contributions are welcome via the usual
channels: file an issue, discuss the shape, send a PR. New
channels, new tools, new provider adapters fit cleanly into the
existing SDK surfaces. Before your first PR, read
[CONTRIBUTING.md](CONTRIBUTING.md) — Aivyx PA is source-available
under BUSL-1.1, so a short [CLA](CLA.md) (accepted via a
`git commit -s` sign-off) is required.
Architectural changes that touch DESIGN.md or PRODUCT.md require
a formal amendment under `docs/amendments/` — fourteen have been
filed across the arc; the process is established. (The two
contracts have otherwise held untouched for many phases — a
tracked stability discipline.)
## License & trademark
The code is **source-available under [BUSL-1.1](LICENSE)** — free
for personal and non-commercial use, with a paid
[commercial license](COMMERCIAL.md) for any business or
production use, **auto-reverting to [MIT](LICENSES/MIT.txt) four
years after each release.** BUSL-1.1 is source-available, *not*
OSI "open source." See [docs/LICENSING.md](docs/LICENSING.md) for
the model and the licensing FAQ. (v0.2.0 and prior remain MIT in
perpetuity.)
The "Aivyx" and "Aivyx PA" names and associated branding are
trademarked — see [TRADEMARK.md](TRADEMARK.md) for the brand usage
rule (BUSL + branded: fork the code for non-commercial use; don't
call the fork "Aivyx" or "Aivyx PA").