Getting started

This chapter tells you how to build aphid, how to give it a key, and how to run it for the first time.

What you need

• A Rust toolchain of the 2024 edition or later. Aphid is built with rustc 1.94.
• An API key for a model. The models that aphid supplies are DeepSeek models, and they read DEEPSEEK_API_KEY. To use a different provider, refer to Add a model.
• A system with Unix sockets, if you want the resident agent. aphid alate does not work on Windows. The coding agent does.

Install

The installer gets the binary of the last release and puts it in ~/.local/bin. It is the fastest way, because it compiles nothing:

$ curl --proto '=https' --tlsv1.2 -LsSf https://github.com/tncardoso/aphid/releases/latest/download/aphid-ai-installer.sh | sh

The releases hold binaries for Linux and macOS. On other systems, and on a different processor, cargo compiles it from the registry:

$ cargo install aphid-ai

Build from the source

$ git clone https://github.com/tncardoso/aphid
$ cd aphid
$ cargo build --release

The binary is then target/release/aphid. To put it on your path:

$ cargo install --path crates/aphid-cli

There is one optional feature, telegram, which adds a Telegram bot to the resident agent and an HTTP client to the build. It is not on by default, because a build with no bot does not need the HTTP client.

$ cargo install --path crates/aphid-cli --features telegram

Give it a key

$ export DEEPSEEK_API_KEY=sk-...

Put this line in the file that your shell reads at start, so that each terminal has it.

Each model gives the name of the variable that holds its key, and aphid reads the variable of the model that you selected. Thus a model from a different provider reads a different variable, and a key that is absent is reported by name:

$ aphid --model glm-5 -p "hello"
aphid: ZHIPU_API_KEY is not set, and glm-5 needs it

The first run

Go to a repository and start the terminal user interface:

$ cd ~/projects/my-project
$ aphid

Type a question and press Enter. Type /help to see the commands.

To run one prompt and print the result, give the prompt on the command line:

$ aphid -p "what does this crate do?"

Aphid records each session, and it records the headless runs also. aphid --sessions lists them, and aphid --resume continues the most recent one.

Add a model

The catalogue is the models that aphid supplies, and then your own models in ~/.aphid/models.json. The descriptions come from models.dev, so you do not write out a context window and a price by hand.

$ aphid model search glm --limit 3
$ aphid model add zhipuai/glm-5
$ aphid --model glm-5 -p "hello"

Aphid describes each model subcommand, and Core describes the file that they write.

Tell it about your project

Aphid reads each AGENTS.md file from the root of the workspace down to the current directory, and the most specific file has the final word. Put the conventions of the project in one:

# AGENTS.md

- Run `cargo clippy` and `cargo fmt` after each change.
- The tests are in `tests/`, and each one is a file.

A file at ~/.aphid/AGENTS.md is applied in each workspace.

For instructions that are only needed sometimes, write a skill instead. A skill costs almost nothing until the model opens it.

Start a resident agent

The coding agent starts in a repository and forgets everything when you close the terminal. An alate has a home of its own, a memory, and a clock that wakes it.

$ aphid alate run --name work
aphid: work is awake in /home/you/.aphid/alate/work
aphid: attach with `aphid alate attach --name work`

Attach a terminal to it from somewhere else, and detach again with Ctrl-C. The alate continues to run. Alate describes the home, the memory, the heartbeat and the crontab.

Where things are kept

APHID_HOME replaces ~/.aphid. Use it to keep a separate configuration.

Build and test the source

$ cargo build
$ cargo test
$ cargo clippy
$ cargo fmt

$ cargo build --features telegram
$ cargo test -p aphid-alate --features telegram

aphid raw and aphid agent can be fully scripted. Their tests run the full encode, stream and commit path against a model that is not on the network.