Skip to main content

Add a Runtime

Task tracking, handoffs, checks, the dashboard, Chat and workers all work without a LibraOS Runtime. A Runtime adds:

  • knowledge search over AgentD's ledger, such as handoffs and runs (agentd search);
  • answers with citations from that knowledge (agentd ask);
  • model-written daily reports.

Requirements​

  • Docker on an x86_64 machine: the Runtime images are x86_64 only, so an Apple silicon Mac or an Arm Windows PC can run them only under emulation, if at all.

    On macOS, install and start Docker Desktop (brew install --cask docker, then open -a Docker). On Windows, Docker Desktop needs WSL 2: in an administrator PowerShell run wsl --install and restart, then winget install Docker.DockerDesktop, start Docker Desktop and wait until it reports that the engine is running. Open a new terminal and check with docker version. Neither needs the docker group.

    On Linux, add your user to the docker group, so Docker works without sudo. On Ubuntu:

    sudo apt install -y docker.io
    sudo usermod -aG docker "$USER"
    exit                 # sign out and in again (a new SSH session) so the group applies
    docker ps            # works without sudo

    newgrp docker changes the group only in that one shell; services and new terminals still need a new sign-in.

  • A model key. With a LibraOS model API key, use the same key file.

On Windows, set the model variables in PowerShell before agentd runtime up ($env:OPENAI_API_KEY = Get-Content PATH\TO\KEYFILE, and $env:OPENAI_API_BASE and $env:OPENAI_MODEL the same way), or use the gateway settings below.

Start it​

With the gateway settings from Models and billing in the config file:

agentd runtime up --model anthropic/claude-sonnet-5
agentd doctor   # runtime: http://127.0.0.1:8900 is healthy

With no OPENAI_API_KEY or ANTHROPIC_API_KEY in the environment, the command uses the gateway URL as the endpoint and the key in the gateway's key file. It then needs a model name: --model NAME, or OPENAI_MODEL. agentd config models lists the gateway's models.

agentd runtime up:

  • runs Postgres (with pgvector) and LibraOS in Docker, and publishes LibraOS on 127.0.0.1:8900 only;
  • generates the database password and other secrets once into ~/.local/share/agentd/.secrets/, readable only by you;
  • keeps the model settings there too, in .secrets/runtime/libraos.env, the containers' env file, so a later run needs no environment or model flag. That file holds a copy of the model key. With the gateway settings, each run reads the key file again, so after you rotate the key, run agentd runtime up again;
  • adds a runtime table to the config file and creates the knowledge collections.

Run it again any time: running containers are kept and data stays. agentd runtime down stops both containers and keeps the data. --dry-run lists the steps without running them.

Embeddings. LibraOS embeds with Qwen/Qwen3-Embedding-8B on OPENAI_API_BASE by default, which api.libraos.com serves. To use another model, see Model settings: Embeddings.

Use it​

agentd kb-sync                         # copy the ledger into the knowledge collections
agentd search "parser"                 # cited results
agentd ask "which tasks failed and why?"

To run LibraOS yourself instead, see Getting started.