Astrum Agent Runtime

A powerhouse Ubuntu 24.04 Docker image meticulously optimized for AI agents, developers, and automation workflows. It provides a "batteries-included" environment for the Hermes Agent and other Docker-based agent backends.

🚀 Quick Start

1. Pull the Image

docker pull ghcr.io/nyrest/astrum-agent-runtime:latest

Available image flavors:

• ghcr.io/nyrest/astrum-agent-runtime:latest → full image (same toolset as before)
• ghcr.io/nyrest/astrum-agent-runtime:full → explicit full tag
• ghcr.io/nyrest/astrum-agent-runtime:lite → slimmer image without giant document/font toolchains like LibreOffice, LaTeX, and the extra font packs

2. Configure Hermes Agent

Run the setup TUI to configure your environment:

hermes setup terminal

• Select Docker as the backend.
• Use ghcr.io/nyrest/astrum-agent-runtime:latest as the Docker image.

3. Manual Entry (Optional)

To mirror the production environment manually:

docker run --rm -it \
  -v "$HOME/.hermes/sandboxes/docker/default/home:/root" \
  -v "$HOME/.hermes/sandboxes/docker/default/workspace:/workspace" \
  ghcr.io/nyrest/astrum-agent-runtime:latest

On Windows (PowerShell):

docker run --rm -it `
  -v "${HOME}/.hermes/sandboxes/docker/default/home:/root" `
  -v "${HOME}/.hermes/sandboxes/docker/default/workspace:/workspace" `
  ghcr.io/nyrest/astrum-agent-runtime:latest

🔐 Supply-Chain Hardening

This repository now keeps the runtime's fast-moving package versions in checked-in manifests:

• versions/tool-versions.env — pinned versions and SHA-256 digests for curl-downloaded tools
• versions/bun-global-packages.txt — exact Bun-installed global npm packages
• versions/npm-global-packages.txt — exact npm-installed global packages
• versions/python-requirements.txt — exact Python package pins for uv pip install

The Docker build uses only pinned release URLs or SHA-verified downloads for Bun, uv, AWS CLI, cloudflared, DuckDB, yt-dlp, hadolint, websocat, and oxipng. The publish workflow also emits SBOM + provenance attestations and signs pushed images with Cosign.

📦 Pre-installed Packages

Two image flavors are published from the same Dockerfile:

• full — the original batteries-included image with document suites, large font packs, and LaTeX tooling
• lite — keeps the core agent/dev/runtime stack but omits the heaviest document/font packages to reduce image size

The first table below describes the shared baseline available in both image flavors.

Category	Key Tools & Packages
Runtimes	Node.js 24, Python 3.13 (uv), Bun, Go SDK
Package Managers	npm, pnpm, yarn, bun, uv, pip, pipx
Web & API CLIs	vercel, wrangler (Cloudflare), gemini (Google), gws (Google Workspace), lark-cli (Feishu), mermaid-cli (mmdc)
Python Libraries	requests, httpx, pydantic, pandas, numpy, beautifulsoup4, ruff, duckdb
Document Processing	pandoc, officecli, pypdf, pdfplumber, python-docx, openpyxl, python-pptx
Database Clients	PostgreSQL, MySQL, Redis, SQLite, DuckDB, Neon (neonctl)
Network Tools	curl, wget, aria2, nmap, cloudflared, HTTPie (http), websocat, socat, sshpass
Cloud & DevOps	aws-cli, gh (GitHub CLI), git-lfs, rclone, hadolint, shellcheck
Multimedia	ffmpeg, yt-dlp, ImageMagick, exiftool, oxipng
Text & Data Utils	jq, yq, rg (ripgrep), fd, mlr (miller), csvkit, tmux
Build Essentials	gcc, g++, clang, cmake, ninja, make, gdb, lldb, strace
Compression	zip, unzip, 7z, tar, zstd, unrar
Data Science & Viz	JupyterLab, Notebook, matplotlib, seaborn, scipy, pillow, imageio

Full-only packages:

Category	Key Tools & Packages
Office Suite	LibreOffice (Headless), libreoffice-writer, libreoffice-calc, libreoffice-impress
Java Runtime	Java (JRE Headless), libreoffice-java-common
Fonts	Noto CJK, Noto CJK Extra, Noto Color Emoji, Noto Core, Liberation, DejaVu, CMU, STIX, TeX Gyre
LaTeX & Academic	latexmk, biber, chktex, lacheck, pygmentize, lualatex, xelatex, pdflatex

🤖 Hermes Agent Configuration

Optimized for the Hermes Agent Docker backend.

terminal:
  backend: docker
  docker_image: ghcr.io/nyrest/astrum-agent-runtime:latest
  docker_forward_env:
    - TZ
    - GITHUB_TOKEN
    - GEMINI_API_KEY
    - OPENAI_API_KEY
    - ANTHROPIC_API_KEY

Use :latest/:full for the current batteries-included environment, or switch docker_image to ghcr.io/nyrest/astrum-agent-runtime:lite for a smaller base image.

🔑 Environment Variables

Common variables to forward for specific use cases:

Service	Variables
GitHub	GITHUB_TOKEN, GH_TOKEN
AI Providers	GEMINI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, HF_TOKEN
Cloud	VERCEL_TOKEN, CLOUDFLARE_API_TOKEN, AWS_ACCESS_KEY_ID
Databases	DATABASE_URL, PGPASSWORD, MYSQL_PWD

🛠 Technical Details

• Base Image: ubuntu:24.04
• Locales: en_US.UTF-8
• Workdir: /workspace
• Browsers: Playwright is installed, but browser binaries (Chromium/Firefox) are not pre-included to keep image size manageable. Use playwright install if needed at runtime.
• License: MIT

---

🏗 Development & Contribution

Building Locally

docker build -t astrum-agent-runtime:full --build-arg RUNTIME_FLAVOR=full .
docker build -t astrum-agent-runtime:lite --build-arg RUNTIME_FLAVOR=lite .

Verification

Run the built-in verification script to ensure all critical tools are operational:

docker run --rm astrum-agent-runtime:full verify-runtime
docker run --rm astrum-agent-runtime:lite verify-runtime

Continuous Integration

Every push to main (excluding README changes) triggers a GitHub Actions workflow that builds and pushes both image flavors:

• ghcr.io/nyrest/astrum-agent-runtime:latest and ghcr.io/nyrest/astrum-agent-runtime:full
• ghcr.io/nyrest/astrum-agent-runtime:lite
• ghcr.io/nyrest/astrum-agent-runtime:full-YYYYMMDD-shortsha
• ghcr.io/nyrest/astrum-agent-runtime:lite-YYYYMMDD-shortsha

The published images are signed with Cosign and ship with BuildKit-generated provenance + SBOM attestations.