Everything you need to install, configure, and use avacli — the free, open-source AI agent.
Add the signing key, source list, and install in one flow:
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://packages.avalynn.ai/key.gpg | sudo gpg --dearmor -o /etc/apt/keyrings/avalynn.gpg
echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/avalynn.gpg] https://packages.avalynn.ai stable main" | sudo tee /etc/apt/sources.list.d/avalynn.list
sudo apt update && sudo apt install avacliDownload the tarball for your architecture from the Download page, then extract and run the installer:
tar xzf avacli-latest-linux-x86_64.tar.gz
cd avacli-*
sudo ./install.shOpen-source avacli talks to the xAI API directly. Add your key once via CLI or the Settings page in the web UI:
avacli --set-api-key xai-YOUR_KEY
Stored under ~/.avacli/config.json. Alternatively set XAI_API_KEY in the environment.
Launch the local agent interface in your browser:
avacli serve
Default bind http://0.0.0.0:8080 (override with --host / --port). Run avacli --generate-master-key once to set the admin password.
Send a one-shot prompt without starting the web UI:
avacli chat "hello"
Sends the message and prints the agent response to stdout (requires API key).
Most settings can also be configured through the built-in web UI at http://localhost:8080 (or your chosen port). Open the Settings page in the sidebar to set your API key, choose a model, configure billing, and change the workspace directory — no CLI flags required.
avacli always uses the xAI API with your own key (CLI, environment, or Settings in the web UI). It does not proxy chat through the Avalynn platform or consume platform tokens.
Ways to provide your xAI key to avacli:
avacli --set-api-key xai-xxxxxxxxxxxx
Saves to ~/.avacli/config.json.
export XAI_API_KEY=xai-xxxxxxxxxxxx
Takes precedence when set.
Settings → API key
Persisted under ~/.avacli/ alongside other preferences.
Point the agent at a specific project directory for file operations and code analysis:
avacli --workspace /home/user/my-project serve
Short form: -d /path. The agent scopes file reads and writes to this directory.
Override the default web UI port (8080):
avacli serve --port 9090
The web UI will be available at http://localhost:9090 (or your host bind).
Choose which xAI model to use for completions:
avacli --model grok-4-1-reasoning serve
Use avacli --list-models to see all available models.
The agent can read, write, and search files within the configured workspace. It respects .gitignore patterns and applies size limits to prevent reading excessively large files.
When pointed at a project directory, the agent indexes the file tree and understands project structure, dependencies, and language-specific patterns. It can navigate codebases, find definitions, and suggest contextual edits.
Responses stream token-by-token in real time. When the model uses extended thinking, the reasoning trace is displayed in a collapsible block above the final answer so you can follow the agent's chain of thought.
The agent follows a tool-use loop: it receives your message, decides which tools to invoke (file read, file write, search, shell commands), executes them, and feeds the results back into the model for the next step. This continues until the task is complete or the model decides no more tool calls are needed.
The agent has access to the following tools. Availability depends on the active mode (see mode table below).
| Tool | Description |
|---|---|
read_file | Read the full contents of a file in the workspace. |
write_file | Write or overwrite a file in the workspace. |
edit_file | Apply targeted edits (search & replace) to a file. |
undo_edit | Revert the last edit made to a file. |
list_directory | List files and directories at a given path. |
glob_files | Find files matching a glob pattern. |
search_files | Search file contents with regex or text patterns. |
read_url | Fetch and read the contents of a URL. |
web_search | Search the web and return summarized results. |
x_search | Search posts on X (Twitter). |
run_shell | Execute a shell command in the workspace. |
run_tests | Run the project's test suite. |
add_memory / search_memory | Store and retrieve agent memories. |
read_todos / create_update_todo | Manage to-do items. |
generate_image / edit_image | Generate or edit images from text prompts. |
generate_video | Generate a video from a text prompt. |
ask_user | Prompt the user for clarification or input. |
Not all tools are available in every mode:
| Mode | Read-only | Write | Shell & tests | Media |
|---|---|---|---|---|
| Question | Yes | — | — | — |
| Plan | Yes | Yes | — | — |
| Agent | Yes | Yes | Yes | Yes |
You need a C++17 compiler, CMake 3.16+, and a few system libraries:
sudo apt install build-essential cmake libcurl4-openssl-dev libssl-dev libjsoncpp-devgit clone https://github.com/iBerry420/acos.git
cd acos
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . -j$(nproc)The resulting avacli binary is in build/. Copy it to /usr/local/bin/ or run it directly.
avacli is MIT-licensed and welcomes contributions. The repository lives at github.com/iBerry420/acos.
main.clang-format if available.cmake --build . -j passes before submitting.