anna docs

Two deployment methods: binary (direct install) and Docker.

Binary

From Release

Download a pre-built binary from GitHub Releases. Binaries are available for linux, macOS, and Windows on amd64/arm64.

# Example: Linux amd64
curl -LO https://github.com/vaayne/anna/releases/latest/download/anna_linux_amd64.tar.gz
tar xzf anna_linux_amd64.tar.gz
chmod +x anna
sudo mv anna /usr/local/bin/

From Source

go install github.com/vaayne/anna@latest
# or
git clone https://github.com/vaayne/anna.git
cd anna && go build -o anna .

Running

Create a config file at ~/.anna/config.yaml (see configuration.md for full reference):

mkdir -p ~/.anna
cat > ~/.anna/config.yaml <<'EOF'
provider: anthropic
model: claude-sonnet-4-6

providers:
  anthropic:
    api_key: "sk-..."
EOF

Start the gateway daemon:

anna gateway

Or use the interactive CLI:

anna chat

Version And Self-Upgrade

anna version
anna upgrade
anna upgrade --install-dir "$HOME/.local/bin"

anna upgrade fetches the latest stable release from GitHub, downloads the matching archive for the current OS/architecture, and installs the binary into $HOME/.local/bin by default.

Systemd Service (Linux)

# /etc/systemd/system/anna.service
[Unit]
Description=anna gateway
After=network.target

[Service]
Type=simple
User=anna
WorkingDirectory=/home/anna
ExecStart=/usr/local/bin/anna gateway
Restart=on-failure
RestartSec=5

# Environment overrides (alternative to config file)
Environment=ANTHROPIC_API_KEY=sk-...
Environment=ANNA_TELEGRAM_TOKEN=123456:ABC...

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now anna

Docker

Images are published to ghcr.io/vaayne/anna for linux/amd64 and linux/arm64.

Tag	Description
`latest`	Latest stable release
`v1.2.3`	Specific version
`sha-<commit>`	Specific commit

Quick Start

docker run -d \
  --name anna \
  -v $(pwd)/anna-data:/home/nonroot/.anna \
  -e ANTHROPIC_API_KEY=sk-... \
  -e ANNA_TELEGRAM_TOKEN=123456:ABC... \
  ghcr.io/vaayne/anna:latest

The container runs as nonroot user. Mount ~/.anna to persist config, sessions, and cron data. You can set ANNA_HOME to change the workspace path inside the container.

Docker Compose

# docker-compose.yml
services:
  anna:
    image: ghcr.io/vaayne/anna:latest
    restart: unless-stopped
    volumes:
      - ./anna-data:/home/nonroot/.anna
    environment:
      - ANTHROPIC_API_KEY=sk-...
      - ANNA_TELEGRAM_TOKEN=123456:ABC...
      # - ANNA_TELEGRAM_NOTIFY_CHAT=123456789
      # - ANNA_TELEGRAM_GROUP_MODE=mention

docker compose up -d

Build Locally

# Single platform
docker build -t anna .

# Multi-platform
docker buildx build --platform linux/amd64,linux/arm64 -t anna .

Volumes & Data

Path	Purpose
`~/.anna/config.yaml`	Configuration
`~/.anna/workspace/cron/`	Cron job persistence
`~/.anna/workspace/SOUL.md`	Agent identity, personality
`~/.anna/workspace/USER.md`	User preferences, context
`~/.anna/workspace/memory.db`	Memory database (message history, summaries)
`~/.anna/workspace/skills/`	Installed skills
`~/.anna/cache/models.json`	Model cache

All paths are under the workspace root (~/.anna/workspace by default, configurable via ANNA_HOME).

Environment Variables

All config values can be overridden via environment variables. See configuration.md for the full list.

Key variables for deployment:

Variable	Required	Description
`ANNA_HOME`	No	Anna home directory (default `~/.anna`)
`ANTHROPIC_API_KEY`	Yes*	Anthropic provider key
`OPENAI_API_KEY`	Yes*	OpenAI provider key
`ANNA_TELEGRAM_TOKEN`	For Telegram	Bot token from @BotFather
`ANNA_TELEGRAM_NOTIFY_CHAT`	No	Chat ID for proactive notifications

* At least one provider key is required.

Health Check

The gateway logs to stdout. Verify it's running:

# Binary
anna gateway  # Logs appear in terminal

# Docker
docker logs anna

Deployment