alpi
Your private agent network.
alpi starts as the agent in your terminal, then grows with you: profiles for work, cron, home servers, research, and workgroups with other alpis. Each profile owns its memory, keys, model, skills, approvals, and trust boundary. ALP links them across machines without a registry, central account, or mandatory cloud.
Bring any model. Keep every key. Run one alpi, or a network that stays yours.
Why alpi exists
Most useful agents eventually become infrastructure: they hold memory, touch files, run commands, answer from a phone, wake up on schedules, and coordinate work across machines. alpi treats the profile as the unit of that infrastructure, not the chat.
The design goal is sovereignty:
- Local-first by default. State lives under
~/.alpi/or a named profile. Memory, sessions, skills, keys, logs, and peer lists are files on your machine. - User-owned models. Fresh profiles ship with no default model. You pick the provider, model, API key, or Ollama server per profile.
- Security as product shape. Shell commands pass a three-tier approval system. Dangerous commands are blocked with no override. Web and email content is treated as hostile data. Skills and MCPs are scanned before install.
- Operational UX. One setup wizard, a live
doctor, a single per-machinealpi daemonsupervisor for every profile (scheduler + ALP + workgroups + host plane), merged logs, backup, and cleanup. - Private coordination. ALP.1 links local profiles, ALP.2 links machines over Noise_XK, and ALP.3 adds shared workgroups. Peers are pinned by Ed25519 identity and governed by fail-closed capabilities. No discovery service, no shared account, no central broker.
- Honest provider boundaries. alpi does not reverse-engineer ChatGPT Plus, Claude Pro, Claude Code, or other first-party subscription clients. If a vendor publishes an official third-party OAuth flow, alpi can adopt it. Until then, users pay per-token API access through their own keys.
What ships today
- Chat surfaces. A Textual TUI with streaming replies, slash commands, live tool cards, interrupt and session resume; a desktop app and a mobile app that pair with your own daemon over the host plane.
- Attachments and knowledge. Attach images, PDFs and source files to a turn. Ask alpi to learn a document and it synthesises durable Markdown knowledge in your workspace instead of storing the raw file. Semantic recall over past sessions and workgroup history is opt-in and forgettable.
- Memory. Three plain-Markdown files —
USER.md,MEMORY.md,AGENT.md— updated inline during conversations. - Skills. Reusable recipes under the profile's own
skills/, scanner-gated and injected into the system prompt. - Models. Any provider through LiteLLM, first-class Ollama, per-profile fast / deep tiers and fallbacks, and a daily USD cap enforced on every turn.
- Sub-agents. Read-only
researchwith three depth tiers, write-capabledelegate, and bounded tool workflows. - Automation. Cron and one-shot schedules hosted by the daemon; an on-demand email tool (IMAP or Gmail) the agent reads and sends through — not an inbound channel; a client for local MCP servers.
- ALP. Same-machine links over Unix sockets, inter-machine links over Noise_XK with per-peer rate limits and budgets, and hub-anchored workgroups for teams of agents — see docs/ALP.md and docs/WORKGROUPS.md.
- Operations.
alpi doctor,alpi audit, merged logs, an administrative audit trail, encrypted backups, one launchd / systemd unit per machine, and an official Docker image (satoshiltd/alpi) for always-on hosts.
Quickstart
uv tool install alpi-agent
alpi setup
alpi
alpi doctor
During setup, pick a model, paste the relevant key, and pin a
workspace. For local-only inference, install Ollama first and add it in
alpi setup -> Model.
The browser tool downloads the Chromium headless shell (~340 MB) on first use, cached under your platform's Playwright directory. No manual step.
Common commands:
alpi # interactive TUI
alpi -c # resume last session
alpi -p work # use named profile
alpi chat --once "status?" # one-shot stdout turn
alpi setup # model, email, MCPs, sandbox, daemon
alpi doctor # live health checks
alpi update # check PyPI and upgrade alpi-agent
alpi logs # merged profile logs
alpi audit-log # administrative activity, never chat content
alpi profile list
alpi profile create work
alpi profile remove work
alpi daemon start|stop|restart|status # unified per-machine supervisor
alpi schedule run-once|fire <job-id> # operational scheduler verbs
alpi peers key
alpi peers list
alpi peers add <id> <pubkey>
alpi peers ping <id>
alpi workgroup list
alpi workgroup create <name> --member <peer-id>
alpi workgroup join <hub-id> <wg_id>
For the first-day walkthrough, see QUICKSTART.md.
Core concepts
Profiles are the isolation primitive. A profile is one directory,
one identity, one model choice, one memory, one skill set, one schedule
surface, and one ALP peer list. The
default profile lives at ~/.alpi/; named profiles live under
~/.alpi/profiles/<name>/.
Memory is plain Markdown. USER.md captures facts about the user,
MEMORY.md captures environment quirks and durable operational facts,
and AGENT.md shapes how alpi should respond. Memory is updated inline
during conversations; there is no post-session reflection loop.
Skills are reusable recipes with a strict directory contract. They
can include instructions, scripts, references, assets, secrets, and
state. Mutations go through validation and a security scanner; secrets
live in either .env or a per-skill secrets/ directory.
Workspace is the default root for relative paths, not a fake security wall. File tools and terminal can use absolute paths except for a sensitive-path denylist. Real workspace-only isolation is the opt-in OS sandbox.
ALP is the Alpi Link Protocol. Each profile owns an Ed25519 keypair.
Peers pin pubkeys out of band and grant explicit capabilities such as
link.ping, link.ask, and workgroup.post. ALP.1 handles same-machine
profiles over Unix sockets. ALP.2 handles inter-machine links with
Noise_XK over TCP plus budgets and rate limits. ALP.3 adds
hub-anchored workgroups.
Host plane is separate from ALP. It is the device-facing control
surface used by paired desktop and mobile clients to talk to their own
daemon (host.* over a local Unix socket or remote WebSocket). Connections
groups one operational identity, its profile access, sessions and usage with
one or more independently revocable device credentials. Peer TCP listener
configures ALP peer traffic.
Security posture
alpi assumes the LLM is powerful, fallible, and sitting next to user credentials. The guardrails are local and layered:
- safe / caution / dangerous command classification;
- dangerous commands blocked with no config escape hatch;
- caution commands require interactive approval or configured allowlist;
- sensitive-path denylist shared across file and terminal posture;
- SSRF protection on web tools;
- prompt-injection warnings on fetched web/email content;
- OSV malware checks before skill or MCP install;
- optional macOS/Linux OS sandbox per profile;
approval.logandagent.logfor audit.
See docs/SECURITY.md for the full model.
Documentation
- QUICKSTART.md — install, model, workspace, first chat, email, profiles, ALP, doctor.
- docs/PROFILES.md — per-profile identity, isolation, state, memory, skills, peers, services, versioning.
- docs/ALP.md — wire protocol, identity, signatures, transports, methods, errors, workgroups.
- docs/WORKGROUPS.md — workgroups in practice: briefings, task markers, recipes, pipelines with gates, human steering.
- docs/SECURITY.md — threat model, approval gate, sandbox, injection/SSRF/path guards, dependency posture.
- docs/ARCHITECTURE.md — implementation reference for contributors and agents reading the codebase.
- docs/CONFIG.md — every YAML key and when it takes effect.
- docs/SKILLS.md — skill directory contract, frontmatter, secrets, scanner, validation.
- docs/MODELS.md — model recommendations for tool-heavy agent use.
- docs/DEPLOYMENTS.md — laptop, home server, Docker/WSS, multi-profile, multi-device, family/team, enterprise shapes.
- docs/INTEGRATIONS.md — talk to a profile or workgroup from your own code (device token, host-plane WebSocket, Node example).
- docs/OPERATIONS.md — services, logs, upgrades, backup/restore, monitoring, disaster recovery.
- docs/ROADMAP.md — open work and rejected ideas.
Tests
uv run --with pytest pytest -q
uv run --with pytest pytest --integration -q
uv run --with pytest pytest --llm
License
alpi is source-available from day one. The agent core is published by Satoshi Ltd. under the Business Source Licence 1.1, with a scheduled conversion to Apache 2.0 on 2030-04-23, or four years after each version's first public release, whichever comes first.
Individuals are free. A natural person running alpi on machines they control may use it in production for any personal, research, or non-commercial purpose. Legal entities are free for evaluation, internal development, and experimentation; production deployment by a company, or offering alpi as a hosted, embedded, or managed service, needs a Satoshi Ltd. commercial licence.
Commercial enquiries: info@satoshi-ltd.com.
1 maintainer
Release files for alpi-agent 0.15.16
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| alpi_agent-0.15.16.tar.gz | 810.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| alpi_agent-0.15.16-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.7 MB
Release files / alpi_agent-0.15.16.tar.gz
| Download URL | alpi_agent-0.15.16.tar.gz |
|---|---|
| Size | 810.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8ba39a38685839dc4932b66ce5628b7aa9b73e2a09acdbba0aedd7f2576a6028
|
|
BLAKE2b-256 checksum How to use checksums |
8ca5965e36d2bbf829e83aea5a22a4bdf7aa0ba91ca2a6369c8989f64663c5de
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 24, 2026.
Transparency logRelease files / alpi_agent-0.15.16-py3-none-any.whl
| Download URL | alpi_agent-0.15.16-py3-none-any.whl |
|---|---|
| Size | 883.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2868974795dc501968f2181b3313feb229cd91e1e976dca9deeb396e6de26810
|
|
BLAKE2b-256 checksum How to use checksums |
350ddfb6a9f304977e681e84e0cb1898dc03161ad83dd431018a8e1b9a69d323
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 24, 2026.
Transparency log
