Deployment

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

Run the setup command to open the admin panel and configure anna (providers, channels, agents, etc.):

anna --open

This starts a local web UI where you set up API keys, channels, and agent profiles. All configuration is stored in ~/.anna/anna.db -- no manual config files needed.

Start the daemon:

anna

To serve the admin panel alongside the daemon (for runtime config changes):

anna --port 8080
anna --host 0.0.0.0 --port 8080

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)

A ready-to-use unit file is provided at scripts/anna.service.

# Create a dedicated user
sudo useradd --system --no-create-home --shell /bin/false anna
sudo mkdir -p /home/anna/.anna
sudo chown anna:anna /home/anna/.anna

# Install the unit file, substituting the actual anna binary path
sudo sed "s|ANNA_BIN|$(which anna)|g" scripts/anna.service \
  > /etc/systemd/system/anna.service
sudo systemctl daemon-reload
sudo systemctl enable --now anna
sudo journalctl -u anna -f   # follow logs

All configuration (channels, agents, scheduler jobs) is stored in anna.db. Use anna --open or the admin panel to manage it.

boxsh Sandbox Prerequisites (Linux)

On Linux, Anna uses the managed boxsh sandbox by default for the local workspace tools (bash, read, write, edit). boxsh needs user namespaces and subordinate ID mapping support on the host.

Install the user namespace helpers:

# Debian / Ubuntu
sudo apt update
sudo apt install uidmap

# Verify helpers exist
which newuidmap
which newgidmap
ls -l /usr/bin/newuidmap /usr/bin/newgidmap

Make sure the service user has subordinate UID/GID ranges:

grep '^anna:' /etc/subuid
grep '^anna:' /etc/subgid

Expected shape:

anna:100000:65536

If the entries are missing, add them:

sudo usermod --add-subuids 100000-165535 anna
sudo usermod --add-subgids 100000-165535 anna

Verify the kernel allows unprivileged user namespaces:

sysctl kernel.unprivileged_userns_clone
sysctl user.max_user_namespaces

Typical working values are:

kernel.unprivileged_userns_clone = 1
user.max_user_namespaces = 15000

Some Ubuntu hosts also block unprivileged user namespaces through AppArmor even when the kernel settings above are enabled. Check:

sysctl kernel.apparmor_restrict_unprivileged_userns

If boxsh fails with sandbox_apply failed: write uid_map: Operation not permitted, temporarily disable that restriction and retest:

sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0

To persist the Linux prerequisites across reboot:

sudo tee /etc/sysctl.d/99-anna-boxsh.conf >/dev/null <<'EOF'
kernel.unprivileged_userns_clone=1
user.max_user_namespaces=15000
kernel.apparmor_restrict_unprivileged_userns=0
EOF

sudo sysctl --system

Smoke-test boxsh directly as the service user:

$ANNA_HOME/bin/boxsh --version
$ANNA_HOME/bin/boxsh --rpc --sandbox

If the second command exits immediately with a uid_map error, the host is still blocking user namespace setup. If you need Anna working before the host is fixed, configure the agent sandbox backend to docker as a temporary fallback (requires a reachable docker daemon).

LaunchAgent (macOS)

A ready-to-use plist is provided at scripts/com.vaayne.anna.plist.

# Install — substitutes $HOME and anna binary path automatically
sed "s|HOME_DIR|$HOME|g; s|ANNA_BIN|$(which anna)|g" scripts/com.vaayne.anna.plist \
  > ~/Library/LaunchAgents/com.vaayne.anna.plist
mkdir -p ~/Library/Logs/anna

launchctl load ~/Library/LaunchAgents/com.vaayne.anna.plist

# Manage
launchctl start com.vaayne.anna
launchctl stop  com.vaayne.anna

# Uninstall
launchctl unload ~/Library/LaunchAgents/com.vaayne.anna.plist
rm ~/Library/LaunchAgents/com.vaayne.anna.plist

Logs are written to ~/Library/Logs/anna/anna.log. The agent starts automatically on login and restarts on crash. Configure API keys and everything else via anna --open or the admin panel.

Docker

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

Tags

Quick Start

First, run setup to configure anna:

docker run -it --rm \
  --security-opt seccomp=unconfined \
  -v ~/.anna:/home/nonroot/.anna \
  -p 8080:8080 \
  ghcr.io/vaayne/anna:latest \
  anna --open

Then start the daemon:

docker run -d \
  --name anna \
  --security-opt seccomp=unconfined \
  -v ~/.anna:/home/nonroot/.anna \
  -e ANTHROPIC_API_KEY=sk-... \
  ghcr.io/vaayne/anna:latest

The container runs as nonroot user. Mount ~/.anna to persist the database, skills, and cache. You can set ANNA_HOME to change the data directory inside the container. If you want the default boxsh-backed sandbox to work inside Docker, run the container with --security-opt seccomp=unconfined so boxsh can call unshare(2). Without that option, sandboxed core tools fall back to a Docker runtime limitation rather than an anna bug.

Docker Compose

# docker-compose.yml
services:
  anna:
    image: ghcr.io/vaayne/anna:latest
    restart: unless-stopped
    security_opt:
      - seccomp=unconfined
    volumes:
      - ./anna-data:/home/nonroot/.anna
    environment:
      - ANTHROPIC_API_KEY=sk-...
      # - OPENAI_API_KEY=sk-...

docker compose up -d

To run initial setup, use docker compose exec anna anna --open or start the daemon with --port 8080 and configure via the web UI.

Build Locally

# Single platform
docker build -t anna .

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

Docker as a Sandbox Backend

Running anna inside a Docker container (described above) is separate from using Docker as a sandbox backend for agent tool execution. The two can be combined (Docker-in-Docker or a mounted socket), but each is independently useful.

When to prefer the docker sandbox backend

• Windows: boxsh is Linux/macOS only. The docker backend gives Windows users a real isolation boundary via Docker Desktop.
• Custom toolchain: You need a specific Python/Node/Go version or a clean Linux userspace that differs from the host.
• Side-effect isolation: You want reproducible filesystem state and do not want host-level side effects from agent scripts.

Tradeoffs

• Startup latency: ~200ms for a warm container start; ~1–3s on first pull.
• Bind-mount performance: On Docker Desktop for macOS/Windows, bind-mount filesystem operations are 5–20× slower than native disk. Avoid the docker backend for heavy read/write workloads on those platforms.
• No copy-on-write isolation: Unlike boxsh (which uses overlayfs), the docker backend does not provide overlay-based COW. A runaway script can modify or damage the mounted workspace.

See the Configuration guide for sandbox.docker config keys and an example JSON payload.

Volumes & Data

All data lives under the anna home directory (~/.anna by default, configurable via ANNA_HOME).

The anna.db file is the only critical data to back up. It contains all configuration, message history, summaries, and scheduler jobs.

Environment Variables

Configuration is managed through the admin panel (via anna --open or --port). HOST and PORT are supported for binding the admin server, and only a small set of other environment variables is supported:

* At least one provider key is required. API keys can also be configured via the admin panel.

Health Check

The daemon logs to stdout. Verify it is running:

# Binary
anna  # Logs appear in terminal

# Docker
docker logs anna