alpi turns the computers you already own into a private network of useful agents. One profile can track your health, meals, calendar, and backups; another can review PRs, watch schedules, and coordinate with a team workgroup. The daemon keeps the memory, keys, skills, approvals, and logs. The terminal, desktop, and mobile apps are just surfaces on top.
A profile is an operating boundary — health, kitchen, work, cron, research, or a home-server peer. It owns identity, memory, model, tools, schedules, logs, approvals, and ALP capabilities. That is how alpi does daily-agent work without collapsing your personal life, professional work, and shared automation into one blurry assistant.
Health, kitchen, work, cron, home-server, research: each profile owns its model, memory, skills, keys, schedules, logs, approvals, and ALP peer list. Crossing the boundary requires capabilities you grant explicitly.
per-profileClaude, OpenAI, OpenRouter, Gemini, Groq, Ollama, or your own endpoint. Fresh profiles start empty so no provider gets chosen for you.
no lock-inNo hidden vector store as the source of truth. USER.md, MEMORY.md, and AGENT.md are updated in the moment and stay readable on disk.
plain filesReusable recipes can carry scripts, references, assets, secrets, and state. Mutations run through validation and a security scanner before they become useful.
scanner-gatedALP.1 links local profiles, ALP.2 links machines over Noise_XK, and ALP.3 adds hub-anchored workgroups. No registry, no discovery layer, no central service deciding who your agents trust.
peer-to-peerOne setup wizard, live doctor checks, launchd/systemd services, merged logs, approval audit, schedule daemon, and gateway daemon. Per-profile daily spend cap (USD or tokens) keeps a runaway agent from quietly burning your API budget.
day-2 readyalpi is not a single bot personality. It is a place to create small, durable alpis around real responsibilities. Keep them separate when context should stay separate; connect them when cooperation is useful.
Sync wearable exports, read training notes, remember constraints, and produce a weekly review. Health data stays in one profile instead of leaking into work conversations.
memory + skills + scheduleTurn fridge inventory, food preferences, budget, and calendar into meal plans and grocery lists. It can ask @doc for constraints without inheriting the whole health memory.
profile-to-profileWatch backups, deliveries, receipts, warranties, and maintenance reminders. This is household operations, not a hardware-specific smart-home integration.
cron + filesReview PRs, run focused tests, write small patches, summarize repo drift, and keep an approval trail around risky terminal actions.
tools + approvalsRun scheduled checks, inspect logs, open incidents, and report only the useful deltas. Put it on an always-on machine and reach it from desktop or mobile.
daemon + TailscaleA hub-held transcript where several profiles coordinate: product, engineering, support, legal. Each member keeps its own memory and budget, but the workgroup has shared state.
ALP.3Install. 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 or workgroups over ALP when you want a private network. All of it lives behind alpi setup.
uv tool install alpi-agent. Python ≥ 3.10. The browser tool downloads Chromium (~200 MB) the first time it runs — no separate install step.
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.
Skip unless you want 24/7 reach through Telegram / IMAP / Gmail. alpi setup → Gateways then Service → Install. The same service also hosts the scheduler and ALP listener. Compatibility bridge, not the primary surface.
alpi profile create work · alpi -p work setup. Different API key, different memory, different bot, different identity. Fully isolated under ~/.alpi/profiles/work/.
The same Service install above also exposes the ALP listener. Pin pubkeys with alpi setup → ALP → Peers. Use ALP.2 for machine links and ALP.3 workgroups when several alpis need a shared workspace.
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.
alpi is not a framework that only makes sense in a README. It is the thing you ask from a terminal, a desktop app, a phone, a schedule, or another machine — with the same memory and the same boundaries each time.
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/ pantry/ SKILL.md # when to invoke scripts/plan.py references/preferences.md you › what should we cook before the spinach goes bad? alpi › → skill(pantry) → plan.py → rice bowl tonight, soup tomorrow
# on the laptop you › ask builder to review the checkout PR alpi › → link.ask(peer=builder, brief=…) ← real issue: retry state survives timeout. patch + regression test are ready.
# caution patterns (recursive rm, sudo, force-push, …) alpi › would like to run: rm -rf build ▲ recursive rm [ allow once / session / always / deny ] you › once alpi › ✓ done. logged to approval.log. # surfaces in terminal, desktop, AND mobile — same prompt
# open the mobile app on the bus, 400km away you › did the backup run tonight? alpi › ✓ 02:11 UTC, 184GB, ok. previous 7 days also clean. # same daemon, same memory, same approvals
alpi is designed to scale from one laptop to a private network 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, terminal or desktop app on top of a local daemon. Zero ALP. Add a gateway later if you want 24/7 messenger reach. The baseline — 90% of individual users stop here.
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.
The multi-profile starter kit on a single host. assistant (daily driver) + researcher (deep-research role) + cron (scheduled jobs). Intra-machine ALP = Unix-domain sockets, mode 0600.
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.
One profile per human, plus a home-server hub. ALP.3 workgroups: the hub holds the group key + transcript, members post via workgroup.post. Agents inside the workgroup act within their per-member budget.
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 path available
These are deployment shapes, not pricing tiers. Personal use and evaluation are free; commercial production has a clear path through §license.
ALP (Alpi Link Protocol) connects alpi instances on the same machine, across different machines, and inside shared workgroups. ALP.1 uses Unix sockets, ALP.2 uses Noise_XK over TCP, and ALP.3 adds workgroup verbs. Pinned pubkeys, fail-closed capabilities, no registry, no discovery service, no generic federation layer. Apache-2.0; trust model is closed-scope, the protocol itself is auditable.
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.
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 has a closed-scope trust model: 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.
Readable core, reproducible via uv.lock, no hidden binaries. The agent core has a time-bound source-available licence; ALP is Apache-2.0.
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.
Personal use, research, evaluation, and non-production deployments are free. Commercial production deployments are covered by a Satoshi Ltd. licence. The agent core is source-available under BUSL-1.1 and converts to Apache-2.0 on 2030-04-23; ALP is Apache-2.0.
Exact grant, Change Date, commercial production terms, and the Alpi Link Protocol exception.
Production, hosted, embedded, or managed deployments — info@satoshi-ltd.com
# 1. install from PyPI (uv recommended; pipx works too) $ uv tool install alpi-agent # package name; binary stays "alpi" # 2. configure the default profile (model + .env + workspace) $ alpi setup # 3. chat $ alpi # 4. check health $ alpi doctor
Full guide → INSTALL.md · alternatives, update path, uninstall, troubleshooting.
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.
The terminal remains the lowest-level surface, but you don't have to live in it. The desktop app is a second client over the same local daemon. The mobile app is a third client — it connects over Tailscale to the daemon you already run on your laptop or home server. Same profiles, same workgroups, same approvals, same logs.
Pair with one or more daemons (local + every remote you own), switch with one click. Tool calls grouped, realistic loading skeletons, native approval modal for caution commands, session resume, profile + model picker. Available now.
Pair your phone with the daemon by scanning a QR. Chat, workgroups, inbox, tasks, approvals — all the host-plane surfaces from the desktop, sized for one hand. Biometric unlock, no telemetry, pairing tokens stay on the device.
Both apps are clients — the agent never leaves the daemon. Read the full feature breakdown on alpi.satoshi-ltd.com/apps.
Each doc is a reference of something that already ships — historical decisions live in commits, planned work in the ROADMAP.
Start here. The public thesis: local-first, user-owned agent infrastructure.
read → 02 · guideInstall methods (uv, pipx, dev), update path, uninstall, troubleshooting, supported platforms.
read → 03 · guideInstall, pick a model, pin a workspace, send a first message, and check health.
read → 04 · guideThe isolation primitive: identity, keys, memory, skills, peers, gateways, and cost.
read → 05 · guideDirectory contract, frontmatter, scanner, validation, secrets, and bundled namespace.
read → 06 · guideModel tiers for tool-heavy agent use: quality, cost/service, and local Ollama.
read → 07 · referenceAlpi Link Protocol: pinned identity, signed envelopes, peer capabilities, workgroups.
read → 08 · referenceCode structure, turn loop, memory, sessions, gateway, scheduler, MCP, logging.
read → 09 · referenceEvery YAML knob, its default, what it controls.
read → 10 · referenceTwo-layer security model. Approval system, SSRF, prompt-injection, sensitive paths. Sandbox.
read → 11 · opslaunchd on macOS, systemd on Linux. Gateway daemon, schedule daemon, keep-alive, logs.
read → 12 · opsDay-2 runbook. Doctor, diagnostics, log rotation, backup, recovery, upgrade.
read → 13 · legalLegal terms for the source-available agent core and Apache-2.0 Alpi Link Protocol.
read → 14 · guide17-agent company scaffold built on ALP: roles, workgroups, 51 skills, and a one-command bootstrap.
read → 15 · planningOpen release gates, ALP launch work, long-term bets, and discarded decisions.
read → 16 · logVersion-by-version log of user-visible changes since v0.1.
read →