QUICKSTART

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

03 / 16·guide·v0.9.26

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, gateways, 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 4.6 (anthropic/claude-sonnet-4-6) 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: connect a gateway

If you want alpi to answer you on Telegram / IMAP / Gmail / Matrix, run the wizard again:

alpi setup → Gateways

Pick the channel, follow the prompts, then make sure the unified daemon is running so alpi answers 24/7:

alpi daemon status
alpi daemon start

Gateways are compatibility bridges for 24/7 reach. The primary surfaces are the terminal, desktop app, and mobile app talking to the daemon directly. The single alpi daemon process supervises every profile on the machine and hosts gateways, scheduler ticks, ALP listeners, workgroup pollers, 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 Telegram bot):

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, gateways logged in, MCP servers handshaking, services alive, ALP socket listening, peers reachable. Green = you're done.

Next steps

theme