Agent-libOS

Quick Start

Install dependencies:

uv sync

Run tests:

uv run python -m unittest discover -s tests -v

Run the deterministic local demo:

uv run agent-libos demo

The demo does not call a real model. It exercises process spawn/fork, Object Memory, Deno/TypeScript JIT validation when Deno is available, checkpointing, capability denial before grant, human approval, filesystem write, final report object creation, and audit trace generation.

Run a small deterministic benchmark smoke:

uv run python experiments/run_benchmark.py --suite benchmarks/runtime_safety --runner agent_libos_full --limit 3 --output .benchmark_runs/m1-smoke
uv run python experiments/collect_metrics.py .benchmark_runs/m1-smoke

The benchmark defaults to mock/planned actions and does not spend model tokens. Real-model benchmark smoke is opt-in and must be scoped with `--llm real --limit 1 or a single --task`.

Common CLI Examples

Send ordinary and interrupt messages:

uv run agent-libos --db .agent_libos.sqlite message <pid> "Please inspect the latest result"
uv run agent-libos --db .agent_libos.sqlite interrupt <pid> "Stop current work and read this first"

Run an interactive Codex CLI-style loop:

uv run agent-libos --db .agent_libos.sqlite run --interactive --pid <pid> --max-quanta 20

Manually control process cwd and lifecycle:

uv run agent-libos --db .agent_libos.sqlite cd <pid> src
uv run agent-libos --db .agent_libos.sqlite exec image.yaml "Review README.md" --pid <pid> --run
uv run agent-libos --db .agent_libos.sqlite exit <pid> --payload '{"done":true}'

Register and load the SWE-Agent style Skill:

uv run agent-libos --db .agent_libos.sqlite skills register skills/swe_agent.yaml
uv run agent-libos --db .agent_libos.sqlite skills load <pid> swe-agent:v0

Inspect or change runtime authority:

uv run agent-libos --db .agent_libos.sqlite capabilities list --subject <pid>
uv run agent-libos --db .agent_libos.sqlite capabilities explain <pid> filesystem:workspace:README.md read
uv run agent-libos --db .agent_libos.sqlite capabilities grant <pid> filesystem:workspace:README.md --rights read

Launch a coding agent against another workspace:

uv run python scripts/run_coding_agent.py --workspace /path/to/repo --goal "Implement the requested change"

On Windows PowerShell:

uv run python scripts\run_coding_agent.py --workspace ..\some-repo --goal "Summarize the current project"

See docs/cli.md for the full command reference.

Real LLM Configuration

Create a local .env file for real-model execution:

OPENAI_BASE_URL=https://example-openai-compatible-endpoint/v1
OPENAI_LANGUAGE_MODEL=your-model
OPENAI_API_KEY=...

The client uses the OpenAI Python SDK. It uses the Responses API for OpenAI-hosted models by default and falls back to Chat Completions for custom OpenAI-compatible base_url providers. Set OPENAI_API_MODE=responses or OPENAI_API_MODE=chat to force a mode.

Optional knobs include OPENAI_TIMEOUT, OPENAI_MAX_RETRIES, OPENAI_STORE, OPENAI_REASONING_EFFORT, OPENAI_VERBOSITY, and provider-specific OPENAI_ENABLE_THINKING.