AgeOS MVP

AgeOS is a Linux-first local agent runtime for sandboxed agents, local LLM routing, GPU/RAM-aware scheduling, and Python integration shims.

Install From Source

./scripts/install-deps.sh
./scripts/build.sh
ageos --help

./scripts/build.sh performs a system-wide source install: native binaries go under /usr/local, the managed Python runtime goes under /opt/ageos, and global launchers are linked into /usr/local/bin. This avoids Ubuntu's system Python pip restrictions while still making ageos available on PATH for every shell. The MVP expects llama-server on PATH for the default local backend. vLLM is optional and installed with:

sudo /opt/ageos/bin/python -m pip install ".[vllm]"

Commands

ageos poc --speciality default-instruct
ageos prompt --speciality code-review --structure example.json --text "Review this diff"
ageos run --binary ./agent.py --niceness 10
ageos ps
ageos queue --watch
ageos dashboard

--niceness is an AgeOS resource priority only. It controls GPU admission, RAM/VRAM budgets, model eviction, and memory-pressure behavior. It does not call Linux nice, setpriority, or ionice.

Examples

Run the basic Python shim agent through the AgeOS sandbox:

ageos run --binary ./examples/basic_agent.py --speciality default-instruct --memory 16G

The agent prints its AgeOS environment, calls the OpenAI-style Python shim, and prints the local model response.

RAM States

AgeOS tracks three memory pressure states:

• available: jobs admit normally; niceness controls tie-breaks and preload order.
• low: lower niceness agents receive RAM/VRAM first; background jobs wait.
• no_ram: low-priority work is queued or rejected; only highest-priority jobs can run after idle models are freed.

Sandbox

ageos run is Linux-only. The native sandbox uses namespaces, read-only mounts, dropped capabilities, no-new-privs, seccomp when available, Landlock hook points, and cgroups v2. Agents do not receive direct GPU device access and must request inference through AgeOS.

For local development on non-Linux platforms only:

ageos run --binary ./agent.py --unsafe-no-sandbox

Python Shims

from ageos.integrations.openai_shim import AgeosOpenAI

client = AgeosOpenAI(speciality="code-review", niceness=5)
response = client.chat.completions.create(
    model="ignored",
    messages=[{"role": "user", "content": "hello"}],
)
print(response.choices[0].message.content)

Packaging Targets

• Snap Store: ageos and optional ageos-vllm
• APT/PPA: ageos, ageos-vllm
• PyPI: ageos

Release automation lives in .github/workflows/release.yml. Push a v* tag to build Python, Debian, and Snap artifacts, attach them to a GitHub Release, and publish to configured stores. TestPyPI publishing requires the TEST_PYPI_API_TOKEN repository secret. PyPI publishing requires the PYPI_API_TOKEN repository secret. Snap Store publishing requires the SNAPCRAFT_STORE_CREDENTIALS repository secret and currently releases the devel snap to the edge channel.