aviary

module

v0.6.2 Latest Latest Go to latest Published: Aug 6, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/lsegal/aviary

Links

Open Source Insights

README ¶

Aviary: the AI Agent Nest

Aviary is a full AI assistant platform. Connect your AI models to Slack, Signal, Discord, and more. Have conversations, set up scheduled tasks, and let your agents work for you, all managed from a CLI or a web-based control panel.

Website | Docs: Getting Started · Configuration · CLI Reference · MCP Tools

Install

macOS / Linux

Homebrew

brew tap lsegal/aviary https://github.com/lsegal/aviary
brew install aviary

This tap works with Homebrew on macOS and Linux.

Manual (cURL)

curl -fsSL https://aviary.bot/install.sh | sh

The install script downloads the latest release binary to ~/.local/bin/ and adds it to your PATH.

Windows

Scoop

scoop bucket add aviary https://github.com/lsegal/aviary
scoop install aviary/aviary

Scoop installs Aviary into Scoop's managed package directory and shims aviary.exe onto your PATH.

Manual (PowerShell)

iwr https://aviary.bot/install.ps1 | iex

The install script downloads the latest release binary to ~/.local/bin/ and adds it to your PATH.

Docker

mkdir -p ~/.config/aviary
docker run --rm -it \
  -p 16677:16677 \
  -p 1455:1455 \
  -p 45289:45289 \
  -v ~/.config/aviary:/home/bot/.config/aviary \
  ghcr.io/lsegal/aviary:latest

The image runs aviary serve by default. With the bind mount above, Aviary stores its config, TLS certs, and login token in your host ~/.config/aviary/ directory.

The Docker image also includes a working Chrome/Chromium browser, so browser tasks run in headless mode out of the box without extra setup.

Tip: -p 1455:1455 is only needed for OpenAI Codex OAuth, and -p 45289:45289 is only needed for Gemini OAuth. If you are using API keys or other providers, you can omit those extra port mappings.

Binary Release

Download the latest release for your platform from the Releases page, place the binary in your $PATH, and make it executable.

Go Install

go install github.com/lsegal/aviary/cmd/aviary@latest

Quick Start

# Start the server
aviary serve

# Set up a provider credential and create your first agent
aviary configure

# Chat with an agent
aviary agent run assistant "Hello!"

Open the web control panel at https://localhost:16677 and log in with the token from ~/.config/aviary/token.

Using Docker, run one-off CLI commands against the same mounted config directory by overriding the container command:

docker run --rm -it \
  -v ~/.config/aviary:/home/bot/.config/aviary \
  ghcr.io/lsegal/aviary:latest \
  aviary configure

For a full walkthrough see the Getting Started guide.

Documentation


Getting Started	Install, first agent, first chat
Configuration	`aviary.yaml` walkthrough — providers, agents, channels, tasks
Scheduled Tasks	Cron and file-watch tasks
Control Panel	Web UI overview
CLI Reference	All commands and flags
Config Reference	Full `aviary.yaml` schema
MCP Tools	All available MCP tools

Contributing

See CONTRIBUTING.md.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
aviary command Package main is the entry point for the aviary CLI.	Package main is the entry point for the aviary CLI.
aviary/cmd Package cmd implements the aviary CLI subcommands.	Package cmd implements the aviary CLI subcommands.
internal
agent Package agent manages agent lifecycle, sessions, and LLM prompting.	Package agent manages agent lifecycle, sessions, and LLM prompting.
auth Package auth manages credential storage for Aviary.	Package auth manages credential storage for Aviary.
browser Package browser provides browser automation via Chrome DevTools Protocol.	Package browser provides browser automation via Chrome DevTools Protocol.
buildinfo Package buildinfo holds build-time metadata injected by release builds.	Package buildinfo holds build-time metadata injected by release builds.
channels Package channels implements messaging channel integrations.	Package channels implements messaging channel integrations.
commandpolicy Package commandpolicy evaluates allow/deny command rules for agents.	Package commandpolicy evaluates allow/deny command rules for agents.
config Package config handles loading, validation, and watching of aviary.yaml.	Package config handles loading, validation, and watching of aviary.yaml.
cronutil Package cronutil centralizes Aviary's accepted cron parsing rules.	Package cronutil centralizes Aviary's accepted cron parsing rules.
domain Package domain defines the core domain entities for Aviary.	Package domain defines the core domain entities for Aviary.
filesystem Package filesystem resolves paths and enforces filesystem allowlists.	Package filesystem resolves paths and enforces filesystem allowlists.
llm Package llm provides adapters for language model providers.	Package llm provides adapters for language model providers.
logging Package logging provides structured logging utilities for Aviary.	Package logging provides structured logging utilities for Aviary.
mcp Package mcp implements the MCP server and client dispatch for Aviary.	Package mcp implements the MCP server and client dispatch for Aviary.
memory Package memory manages per-agent memory notes stored as markdown files.	Package memory manages per-agent memory notes stored as markdown files.
models Package models exposes the embedded catalog of supported model identifiers.	Package models exposes the embedded catalog of supported model identifiers.
scheduler Package scheduler drives task execution via cron, file-watch, and job queue.	Package scheduler drives task execution via cron, file-watch, and job queue.
scriptruntime Package scriptruntime executes sandboxed embedded scripts.	Package scriptruntime executes sandboxed embedded scripts.
server Package server implements the Aviary HTTPS server.	Package server implements the Aviary HTTPS server.
sessiontarget Package sessiontarget manages persisted session delivery targets.	Package sessiontarget manages persisted session delivery targets.
store Package store manages Aviary's file-based data directory.	Package store manages Aviary's file-based data directory.
testenv Package testenv provides process-wide helpers for isolating Go tests from the user's real Aviary config and data directories.	Package testenv provides process-wide helpers for isolating Go tests from the user's real Aviary config and data directories.
update Package update implements Aviary version checks and binary upgrades.	Package update implements Aviary version checks and binary upgrades.
skills Package skills provides discovery and loading for builtin and installed skills.	Package skills provides discovery and loading for builtin and installed skills.
support
templates Package templates exposes embedded filesystem templates used to initialize runtime artifacts.	Package templates exposes embedded filesystem templates used to initialize runtime artifacts.