QUICKSTART

Install, pick a model, pin a workspace, send a first message, and check health.

03 / 16·guide·v0.14.4

First-day walkthrough. Takes about 10 minutes end-to-end and leaves you with a working alpi — model selected, workspace pinned, first session running, and alpi doctor green. Profiles, email, apps, and ALP come next.

For concepts behind any step, see ARCHITECTURE.md. For the security posture, see SECURITY.md. Why alpi is built the way it is: see README.md.

1. Install

uv tool install alpi-agent     # install
alpi setup                     # use

PyPI package is alpi-agent; the binary is alpi. Alternatives and update path → INSTALL.md.

Needs Python ≥ 3.10. The browser tool downloads Chromium (~200 MB) the first time it runs — no separate install step.

Check it works:

alpi --version

2. Pick a model

The fresh profile ships without a default model — you choose your provider and your model. Open the setup wizard:

alpi setup

Pick Model / Provider, choose a provider, paste the API key when prompted, pick a model. For recommendations see docs/MODELS.md — if you want a single sensible choice, Claude Sonnet 5 (anthropic/claude-sonnet-5) is the pragmatic daily driver. If you want fully local (no cloud), install Ollama first and pick Ollama in the wizard.

3. Pin a workspace

Same wizard, pick Workspace. Point it at the directory alpi is allowed to read and write — typically the project you're working on. Without a workspace, alpi falls back to the current working directory at launch with a warning; that's fine for trying things, not for real use.

4. Send your first message

alpi

Type hola and press Enter. The TUI streams the model's reply. Useful first commands to try inside the TUI:

And try asking alpi about itself — "how do I configure the TUI theme?", "how does the ALP protocol work?". The alpi_knowledge tool answers from the packaged docs without leaving the terminal.

Leave it with Ctrl-C or /exit.

5. Resume where you left off

alpi -c

-c / --continue rehydrates the last session. To make this the default behaviour without typing -c every time, enable tui.auto_resume in ~/.alpi/config.yaml (or set it via alpi setup).

6. Optional: let your agent work over email

If you want alpi to read, search, send, and reply to mail on your behalf — during a chat or a scheduled job — give it an email account:

alpi setup → Email

Add an IMAP account (host, port, credentials) or connect Gmail via OAuth, then ask alpi to triage your inbox or draft a reply. Email is an on-demand tool the agent uses, not an inbound channel: the daemon never listens for incoming messages, and nothing answers automatically.

You reach alpi itself through its first-party surfaces — the terminal, desktop app, and mobile app talking to the per-machine daemon. The single alpi daemon process supervises every profile and hosts the scheduler, ALP listeners, workgroups, and the host plane.

7. Add a second profile (optional)

If you want a work profile that's completely isolated from your personal one (different API keys, different memory, different email account):

alpi profile create work
alpi -p work setup

Everything is per-profile: home directory, sessions, memory, skills, keys, peers. See docs/PROFILES.md for the full model.

If you plan to link profiles or machines with other alpis, the daemon already exposes the Alpi Link Protocol listener when the profile's ALP subsystem is enabled. Then exchange pubkeys with peers:

alpi daemon status
alpi setup → ALP → Peers

See docs/DEPLOYMENTS.md for topologies (laptop + home server, multi-device, team, enterprise).

9. Check everything is healthy

alpi doctor

Runs live checks: model reachable, email accounts reachable, MCP servers handshaking, services alive, ALP socket listening, peers reachable. Green = you're done.

Next steps

theme