Core loop first.
Turn, memory, tools, paths, scanner. The surface comes after. 30+ tools → ~17. No legacy code, no silent migrations.
constraint breeds coherencealpi lives in your terminal. Inline-learning memory, live skills, your choice of model, reachable from the messengers you already use — and ALP, a closed agent-to-agent protocol that links your agents across profiles and machines without a hub. No telemetry. No account. No mandatory cloud.
Third-party agents typically aim at a broad audience: 28 skill categories, sync hub, sub-agent mesh, SQLite state. alpi drops all of that. 17 tools, 3 memory files, 1 research sub-agent. Every feature earns its keep or doesn't ship.
Turn, memory, tools, paths, scanner. The surface comes after. 30+ tools → ~17. No legacy code, no silent migrations.
constraint breeds coherenceThree-tier approval system: safe / caution / dangerous. The dangerous ones never get an override — no flag, no config knob.
approval gateThree markdown files — USER.md, MEMORY.md, PERSONALITY.md. Updated inline during conversations via the memory tool.
3 filesTried in v0.1, removed in v0.2. The security scanner plus OSV check on install are the real gate. Auto-injected into the system prompt.
skillsresearch(brief, depth) spawns a read-only worker with its own context. Returns a synthesised report — main agent never sees the trace.
quick · normal · deepZero reversed OAuth against any vendor's first-party subscription client. You use your own API keys — the cost is honest, per-token, and visible.
no subscription routingInstall. Pick a model. Pin a workspace. Send a message. Connect a gateway if you want 24/7 messaging. Add a profile if you want isolation. Link machines over ALP if you want a mesh. All of it lives behind alpi setup.
uv tool install alpi. Python ≥ 3.10. Optional: playwright install chromium (~200 MB) for the browser tool.
alpi setup → Model / Provider. Fresh profiles ship with no default — you choose the provider, paste the key, pick the model. See MODELS.md for tiered guidance.
Same wizard, Workspace. Point it at the dir alpi may read/write. Fallback is cwd at launch, with a warning — fine for trying, not for real use.
Run alpi. Type hola. Useful first slash commands: /help · /memory · /skills · /status · /new · /model.
alpi -c rehydrates the last session. To make it implicit, flip tui.auto_resume in config.yaml.
alpi setup → Gateways then Gateway service → Install. alpi now answers Telegram / IMAP / Gmail 24/7, with per-chat session threading.
alpi profile create work · alpi -p work setup. Different API key, different memory, different bot, different identity. Fully isolated under ~/.alpi/profiles/work/.
alpi setup → ALP service → Install then → Peers to exchange pubkeys. See deployments for the six topologies.
alpi doctor. Live checks: model reachable, gateways logged in, MCP handshaking, services alive, ALP socket listening, peers reachable. Exits 1 on any failure — cron-friendly.
Not a framework. Not a harness. A terminal companion that remembers you, executes, and — with ALP — talks to your other machines without a hub in the middle.
you › my partner's birthday is march 14th alpi › noted. added to MEMORY.md. … # three weeks later, fresh session you › anything coming up this month worth planning? alpi › yes — her birthday on the 14th. want me to draft a plan?
~/.alpi/skills/ finance/ SKILL.md # when to invoke scripts/fetch.py references/ledger.md you › how much did i spend on groceries last month? alpi › → skill(finance) → fetch.py → €412.80 across 23 tx
# on the laptop you › ask nas to pull the latest logs and tell me what's odd alpi › → link.ask(peer=nas, brief=…) ← 3 auth failures from 185.220.x at 03:14 UTC. consistent with a credential-stuffing probe.
# from your phone, 400km away you › did the backup run tonight? alpi › ✓ 02:11 UTC, 184GB, ok. previous 7 days also clean. # fail-closed allowlist; unknown senders drop silently
alpi is designed to scale from one laptop to an enterprise "army of alpis", without ever needing a central server. Each shape is a reference you can adapt — profiles provide identity, ALP provides the wire.
One profile, one machine, TUI for chat. Optional gateway daemon for 24/7 Telegram / IMAP / Gmail. Zero ALP. The baseline — 90% of individual users stop here.
free · BSL personal use
Heavy work (schedules, long research, cron) on the home server; interactive chat on the laptop. Linked via ALP.2 over Tailscale. Each pins the other's pubkey; capabilities narrow per peer.
free · BSL personal use
The "army of alpis" starter kit on a single host. assistant (daily driver) + researcher (deep-research role) + cron (scheduled jobs). Intra-machine ALP = Unix-domain sockets, mode 0600.
free · BSL personal use
Your alpis follow you across devices — laptop, desktop, phone (Termux / iSH) — over a Tailscale mesh. Every device pins every other. Losing a device means dropping its pubkey from every peers.yaml.
free · BSL personal use
One profile per human, plus a home-server hub. ALP.3 rooms: the hub holds the group key + transcript, members post via room.post. Agents inside the room act within their per-member budget. Ships in ALP.3 (v0.4).
free · BSL personal use
Per-employee profiles, mesh linked over corporate Tailscale. Shared services (research-bot, tools-bot) as pinned peers with narrow capabilities. Central log + approval audit hub. Company policy pushes sandbox on.
commercial licence from Satoshi Ltd.
topology · 06 · enterprise mesh ┌──────────────────────────────────────────────────────────────┐ │ corporate Tailscale network │ │ │ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │ │ │Jane │ │Raj │ │Mia │ │Léa │ │… N │ │ │ │alpi │ │alpi │ │alpi │ │alpi │ │ │ │ │ └──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘ │ │ └─────────┴─────────┴─────────┴─────────┘ │ │ │ │ │ ┌────────┴─────────┐ │ │ ┌─────────▼──────┐ ┌──────▼─────────┐ │ │ │ research-bot │ │ tools-bot │ │ │ │ (shared, RO) │ │ (HR, calendar, │ │ │ │ │ │ narrow budget)│ │ │ └────────────────┘ └────────────────┘ │ │ │ │ ┌───────────────────┐ │ │ │ audit + log hub │ agent.log + approval.log │ │ (SIEM forwarder) │ shipped to your SIEM │ └───────────────────┘ │ └──────────────────────────────────────────────────────────────┘ out of scope, deliberately — · SSO / SAML / OIDC for human access (belongs at Tailscale / OS) · centralised secret management (wire Vault via MCP) · federation with non-alpi agents (ALP is closed — use MCP)
Licence boundary. Topologies 1–5 are personal / non-production use by individuals and are free under BSL 1.1. Topology 6 — production deployment inside a legal entity — requires a commercial licence from Satoshi Ltd. (info@satoshi-ltd.com). Full text in §license.
ALP (Alpi Link Protocol) connects alpi instances — same machine, different machines, or a shared room — without a hub, a registry, or a discovery service. End-to-end encrypted, pinned pubkeys, fail-closed capabilities. Purpose-built, not open-federation.
Every envelope is signed. Peer lists pin a pubkey — not a hostname, not a trust-on-first-use cert. Unknown peer, dropped at the transport layer before the payload is parsed.
Intra-machine: alp.sock mode 0600. Inter-machine: Noise_XK handshake + ChaCha20-Poly1305. Forward-secret session keys. No TLS, no PKI, no CA to trust.
link.ping — liveness. link.ask — runs a full agent turn on the target peer, using its memory, skills, and tools. link.cancel — interrupt. No introspection. No federation.
Every peer lists an allow: array of methods it may invoke. Not listed, not allowed. Daily budgets in tokens or USD. Rate limits per minute.
N agents share a workspace with a stable group key. One hub holds the transcript. No replication, no consensus re-election — host the hub on an always-on machine.
A second link.ask on an already-running session returns -32007 target-busy. The caller retries with jittered backoff. No deadlock class.
peer A (laptop) peer B (home-server) ┌──────────────────────────────────┐ ┌─────────────────────────────────┐ │ alpi profile=personal │ │ alpi profile=nas │ │ key: ed25519 (pinned → B) │ │ key: ed25519 (pinned → A) │ └─────────────┬─────────────────┘ └─────────────┬─────────────────┘ │ │ └─── Noise_XK ─── ChaCha20-Poly1305 ───┘ TCP :7423 envelope { jsonrpc, id, method, params, alp: { v, from, to, ts, nonce, sig } } verbs link.ping · liveness + version link.ask · run full agent turn on peer link.cancel · interrupt session
What ALP is not. It's not an open federation protocol. It does not aim to interoperate with third-party agents. It does not anonymise traffic. It does not defend against a compromised endpoint. Scope is deliberately narrow — that's what keeps the attack surface narrow and the spec auditable end to end.
alpi is published by Satoshi Ltd. and inherits its six operating principles. They aren't aspirational copy — every non-obvious design choice in the repo traces back to one of these.
No discovery. No registry. No telemetry. LiteLLM's default telemetry is audited off at release — regression-tested. ALP is a closed protocol by construction: every exposed knob is a potential attack vector.
Per-profile isolation under ~/.alpi/profiles/<name>/. Fresh profiles ship with no default model — you pick your provider, your model, your memory. Skills and memory live on your disk, not ours.
Threat-modeled from the spec. Ed25519 signing on every ALP envelope, fail-closed capability model, reject-fast reentrancy, approval gate on shell, OSV check before installing skills or MCPs, pip-audit in the release checklist.
Source-available under BSL 1.1. Reproducible via uv.lock. No hidden binaries. Converts to Apache 2.0 on the Change Date (2030-04-23). Free for individuals and non-production use.
No trust-on-first-use. Peers exchange pubkeys out of band and pin them. ALP.2's Noise_XK handshake produces forward-secret session keys — losing a long-term key doesn't unlock past traffic.
Ollama is a first-class provider. Skills and sub-agents run locally. Wire alpi up on a laptop, a home server, and a remote box, link them via ALP, and never depend on a centralised service.
The design heuristic that pulls these together — borrowed from Satoshi's Clonara — is “constraint breeds coherence”. Closed scope, small verb set, one transport per environment, no generic framework.
Source-available under BSL 1.1 by Satoshi Ltd., converting to Apache 2.0 on 2030-04-23. Individuals, research, and non-production use are free. Companies deploying to production need a commercial licence. The Alpi Link Protocol itself ships under Apache-2.0 so third parties can implement interoperable nodes.
BSL 1.1 split, Change Date, individuals vs companies, the Alpi Link Protocol exception.
Production deployment by a company, or offering alpi as a hosted / embedded service — info@satoshi-ltd.com
# 1. install from PyPI (uv recommended, pip also works) $ uv tool install alpi # 2. configure the default profile (model + .env + workspace) $ alpi setup # 3. chat $ alpi # 4. check health $ alpi doctor # later — add a second profile, fully isolated $ alpi profile create work $ alpi -p work setup
alpi needs Python ≥ 3.10. The default profile lives in ~/.alpi/. Additional profiles in ~/.alpi/profiles/<name>/. No account, no central server, no telemetry — your .env is the single source of truth for secrets. Source-available under BSL 1.1; converts to Apache 2.0 on 2030-04-23. Commercial production deployment → §license.
Each doc is a reference of something that already ships — historical decisions live in commits, planned work in the ROADMAP.
Start here. What alpi is, who it's for, how it differs.
read → 02 · guideInstall, set a key, first chat, first skill. 5 minutes from zero to a working agent.
read → 03 · guideSwitchable agent personalities: personal / coder / ops / research. How to define your own.
read → 04 · guideDirectory contract. 13 closed categories. Frontmatter. Where secrets live.
read → 05 · guideTiers A/B/C. Usage signals + hands-on testing. What @soyjavi uses day to day.
read → 06 · referenceAlpi Link Protocol. Noise-encrypted inter-machine transport. Rooms, rate limits, budgets.
read → 07 · referenceCode structure, turn loop, memory, sessions, gateway, scheduler, MCP, logging.
read → 08 · referenceEvery YAML knob, its default, what it controls.
read → 09 · referenceTwo-layer security model. Approval system, SSRF, prompt-injection, sensitive paths. Sandbox.
read → 10 · opslaunchd on macOS, systemd on Linux. Gateway daemon, schedule daemon, keep-alive, logs.
read → 11 · opsDay-2 runbook. Doctor, diagnostics, log rotation, backup, recovery, upgrade.
read → 12 · legalBSL 1.1 for the agent core; Apache-2.0 for the Alpi Link Protocol.
read → 13 · planningWhat's in progress, what's coming in v0.3, decisions discarded with rationale.
read → 14 · logVersion-by-version log of user-visible changes since v0.1.
read →