Docs

Run the server

avni-core with Docker, systemd, or from source.

Pick one of the three routes. They all run the same program, avni-core, and all end with it listening on port 7444. Keep that port off the public internet: reach it through Tailscale (next page).

Best for a VPS or any machine with Docker. The container runs as a normal user, with a read-only filesystem and no extra privileges.

  1. Copy the two config files

    They are git-ignored, so your secrets stay out of the repository.

    bash
    cd deploy
cp avni.example.toml avni.toml
cp avni.env.example avni.env

  2. Fill them in

    In avni.toml, replace the two <verify: ...> model ids with current ones from your provider. In avni.env, set GROQ_API_KEY. Core refuses to start while a placeholder is left, on purpose.

  3. Start it

    bash
    docker compose up -d --build
docker compose logs -f avni-core

    The first build compiles the server and takes a few minutes. After that it is cached.

  4. Check it is alive

    bash
    curl -fsS http://127.0.0.1:7444/healthz     # prints: ok
docker compose ps                           # should say (healthy)

To publish the port on your Tailscale address only, set AVNI_BIND=100.x.y.z in deploy/.env before step 3. The default is loopback.

Upgrade with git pull && docker compose up -d --build. The ledger, memory and paired devices live in a volume and survive.