Agelos

Containerized AI coding agent runner. Zero host dependencies — only needs Podman or Docker.

Runs AI agents (OpenCode, Aider) in minimal, dynamically-built containers. Auto-detects project runtimes from config files and builds the right environment on demand. Includes interactive model management for local llama-server.

Features

• Auto-detection — scans .csproj, package.json, pyproject.toml, go.mod, Cargo.toml for runtime requirements
• Dynamic containers — generates minimal Dockerfiles on-the-fly per project
• Multi-runtime — run .NET, Node, Python, Go, Rust side-by-side
• Podman first — rootless by default, falls back to Docker
• Single binary — Native AOT, no .NET runtime required on host
• Agent runtime requests — agents can request new runtimes mid-session; Agelos prompts for approval and rebuilds
• Local model management — download GGUF models, manage per-project llama-server config
• Open WebUI — one-command browser chat UI backed by llama-server; optional CUDA GPU acceleration

Requirements

• Podman or Docker
• .NET 10 SDK (only to build from source)

llama-server is optional. model commands start a llama-server automatically — natively if llama-server is in your PATH, or as a container via Podman/Docker otherwise. The container image is auto-selected based on your GPU: CUDA (server-cuda) for NVIDIA, Vulkan (server-vulkan) for AMD/Intel, or CPU-only (server) as a fallback. No manual install or configuration required.

Install

Download binary (recommended)

Grab the latest release from GitHub Releases:

# Linux/macOS
chmod +x Agelos-linux-x64
sudo mv Agelos-linux-x64 /usr/local/bin/Agelos

curl installer (Linux/macOS)

curl -fsSL https://raw.githubusercontent.com/locheed/Agelos/main/scripts/install.sh | bash

PowerShell installer (Windows)

irm https://raw.githubusercontent.com/locheed/Agelos/main/scripts/install.ps1 | iex

Installs to %USERPROFILE%\.local\bin\agelos.exe and adds that directory to your user PATH automatically. Restart your terminal after installing.

Commands

Agelos run <agent>

Run an AI coding agent in a container.

Agelos run opencode
Agelos run aider
Agelos run gemini

# Options
Agelos run opencode --runtimes dotnet:10,node:20   # explicit runtimes
Agelos run opencode --addon llama-cpp               # add llama-cpp layer
Agelos run opencode --rebuild                       # force image rebuild
Agelos run opencode --minimal                       # skip runtime detection

Container is built from project runtimes (auto-detected or from .Agelos.yml). Workspace is mounted at /workspace. If .Agelos/opencode.json exists, it is synced to ~/.config/opencode/config.json before launch so each project can have its own model set.

Gemini CLI authentication: Set GEMINI_API_KEY in your host environment before running Agelos run gemini. The variable is automatically forwarded into the container. Alternatively, run gemini auth inside the container the first time — credentials are persisted in ~/.gemini/ which is mounted from your host.

Agelos model add

Interactive download and registration of a GGUF model.

1. Pick model family  (Qwen3 / Llama 3 / Other)
2. Pick model         (with context size shown)
3. Pick quantization  (Q2_K → Q8_0, with approx size)
4. Confirm download
5. Downloads to ~/.Agelos/models/
6. Writes to .Agelos/opencode.json
7. Restarts llama-server on port 8033

Agelos model add

Agelos model list

Show downloaded models and project config status.

Agelos model list

╭──────────────────────────────────────┬──────────┬───────────╮
│ File                                  │ Size     │ In config │
├──────────────────────────────────────┼──────────┼───────────┤
│ Qwen_Qwen3-8B-Q4_K_M.gguf            │ 5.0 GB   │ yes       │
│ Llama-3.2-3B-Instruct-Q4_K_M.gguf   │ 2.0 GB   │ no        │
╰──────────────────────────────────────┴──────────┴───────────╯

Agelos model remove

Interactively delete a downloaded model and unregister it from project config.

Agelos model remove

Agelos webui start

Spin up Open WebUI as a local browser chat interface backed by llama-server. The container is pulled automatically on first use.

Agelos webui start           # CPU image, opens browser when ready
Agelos webui start --cuda    # CUDA-accelerated image (requires NVIDIA GPU + nvidia-container-toolkit)

• Checks llama-server health on port 8033 and warns if it isn't running (non-blocking — UI still launches)
• Auto-selects the next free port starting from 3000 if 3000 is already in use
• Opens your default browser automatically once Open WebUI is ready
• If OPENAI_API_KEY is set in your environment it is forwarded into the container; otherwise a placeholder is used (llama-server does not validate API keys)

GPU note for Open WebUI (--cuda): The --cuda flag controls the Open WebUI container image only. llama-server's container image is auto-selected separately by agelos model add — no flag needed there. See the GPU auto-detection table below.

llama-server GPU auto-detection

agelos model add (and any restart) probes the host and picks the right llama.cpp container image automatically:

If an NVIDIA GPU is found but the toolkit is not installed, Agelos warns and falls back to Vulkan on Linux/WSL2, or CPU on Windows. No manual intervention required in any case.

Best performance tip: Install llama-server natively on your host. Agelos always prefers the native binary over a container — it talks to your GPU directly via CUDA/Vulkan/Metal drivers with no container overhead and no toolkit requirement. Vulkan container mode works on Linux and WSL2 but not on Windows Docker Desktop (no /dev/dri passthrough).

Agelos webui stop

Stop the running Open WebUI container.

Agelos webui stop

Agelos webui status

Show whether Open WebUI is running and at which URL, plus llama-server health.

Agelos webui status

Agelos list

List available agents, add-ons, and supported runtimes.

Agelos list
Agelos list --agents
Agelos list --runtimes

Agelos init

Detect runtimes from existing project files and write .Agelos.yml.

cd my-project
Agelos init

Agelos new <template> <name>

Create a new project from a template.

Agelos new dotnet-api MyApi

Agelos add-runtime <spec>

Add a runtime to an existing .Agelos.yml.

Agelos add-runtime node:20

Agelos prebuild

Build the container image without starting an agent. Useful for CI or slow networks.

Agelos prebuild

Configuration

.Agelos.yml — project runtime config

Auto-generated by Agelos init or Agelos new. Defines runtimes and agent.

version: "1.0"
agent: opencode
runtimes:
  dotnet:
    - "10"
  node: "20"

.Agelos/opencode.json — project model config

Created and managed by Agelos model add. Defines which local models are available to OpenCode in this project. Committed to source control — different projects can use different models.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "llama-local": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "llama-server (local)",
      "options": {
        "baseURL": "http://127.0.0.1:8033/v1"
      },
      "models": {
        "Qwen_Qwen3-8B-Q4_K_M.gguf": {
          "name": "Qwen3 8B (Q4_K_M)",
          "limit": { "context": 131072, "output": 32768 }
        }
      }
    }
  }
}

Supported runtimes

Curated models (Agelos model add)

All models sourced from bartowski on HuggingFace. Sizes in GB.

Model files download to ~/.Agelos/models/ (shared across projects, not in repo).

---

Development

Prerequisites

• .NET 10 SDK
• Podman or Docker (for end-to-end testing)

Run without building binary

# Run a command directly (-- separates dotnet args from Agelos args)
dotnet run --project src/Agelos.Cli -- run opencode
dotnet run --project src/Agelos.Cli -- model list
dotnet run --project src/Agelos.Cli -- model add
dotnet run --project src/Agelos.Cli -- webui start
dotnet run --project src/Agelos.Cli -- webui start --cuda
dotnet run --project src/Agelos.Cli -- webui stop
dotnet run --project src/Agelos.Cli -- webui status
dotnet run --project src/Agelos.Cli -- --help

Hot reload (watch mode)

# Rebuilds and relaunches on any source change
dotnet watch run --project src/Agelos.Cli -- list

Watch mode doesn't work well for interactive commands (TUI prompts). For those, use dotnet run directly.

Build check (fast)

dotnet build src/Agelos.Cli --nologo

Run tests

dotnet test tests/Agelos.Tests

# Verbose output
dotnet test tests/Agelos.Tests -v normal

# Single test class
dotnet test tests/Agelos.Tests --filter "FullyQualifiedName~RuntimeParserTests"

Build native binary

Native AOT produces a single self-contained executable with no .NET runtime requirement.

# Current platform
dotnet publish src/Agelos.Cli -c Release

# Cross-compile (requires cross-compilation toolchain on Linux/macOS)
dotnet publish src/Agelos.Cli -c Release -r linux-x64   --self-contained
dotnet publish src/Agelos.Cli -c Release -r linux-arm64 --self-contained
dotnet publish src/Agelos.Cli -c Release -r osx-x64     --self-contained
dotnet publish src/Agelos.Cli -c Release -r osx-arm64   --self-contained
dotnet publish src/Agelos.Cli -c Release -r win-x64     --self-contained

Output: src/Agelos.Cli/bin/Release/net10.0/<rid>/publish/Agelos[.exe]

Note: Native AOT cross-compilation is platform-restricted. The GitHub Actions release workflow builds each target on its native OS. For local dev, build for the current platform only.

Project structure

src/
  Agelos.Cli/
    Commands/    # CLI commands: run, init, list, new, add-runtime, prebuild, model, webui
    Core/        # Runtime detection, container building, container running
    Services/    # File, process, config, model download, llama-server, opencode config, open-webui
    Models/      # Data structures: config, container options, runtime requirements, model catalog
    Prompts/     # Interactive Spectre.Console prompts (greenfield setup, model selection)
tests/
  Agelos.Tests/  # xUnit unit tests
assets/
  agents/
    opencode/    # entrypoint.sh — runtime request bridge; COPY-ed into the OpenCode image at build time
scripts/
  install.sh     # curl-pipe installer for Linux/macOS
containers/      # ← runtime-generated; gitignored — Agelos writes per-project build artefacts here

Known issues / AOT warnings

Stack

• .NET 10 / C# 12 / Native AOT
• System.CommandLine — CLI parsing
• Spectre.Console — terminal UI
• YamlDotNet — YAML config
• System.Text.Json — JSON (opencode config)
• xUnit + Moq + FluentAssertions — testing

License

MIT