agent-runtime

README

agent-runtime

Security-first, cloud-agnostic runtime for multi-channel agent operations.

agent-runtime connects chat and tool channels to a shared control plane with routing, approvals, background task execution, workspace memory, and markdown retrieval.

Status

• Current version: 0.1.0
• Stability: early OSS release (pre-1.0)

Key Capabilities

• Multi-channel connectors: Telegram, Discord, Codex/Cline/Gemini pattern, IMAP
• Command + natural-language task routing
• Human approval gates for sensitive actions
• Objective scheduler for recurring/event-driven proactivity
• Workspace-scoped markdown retrieval with qmd
• Fullscreen admin TUI (Overview, Pairings, Objectives, Tasks, Activity)
• Admin HTTP API for operations

Architecture

flowchart LR
    Channels["Telegram / Discord / Codex / IMAP"] --> Gateway["Gateway"]
    Gateway --> Engine["Orchestrator + Workers"]
    Gateway --> Store["SQLite Store"]
    Gateway --> QMD["QMD Retrieval"]
    Scheduler["Objective Scheduler"] --> Engine
    Watcher["Markdown Watcher"] --> Scheduler
    Watcher --> QMD
    API["HTTP API"] --> Gateway
    API --> Store

For more detail: Architecture.

Quickstart (5 Minutes)

1. Prepare env:

cp .env.example .env

1. Run locally:

make run

1. Verify:

curl -fsS http://localhost:8080/healthz
curl -fsS http://localhost:8080/readyz

1. Optional: run TUI:

make tui

The TUI runs in fullscreen with a sidebar/workbench/inspector layout and hybrid auto/manual refresh for operations.

1. Optional: run Compose stack:

make compose-up

First End-to-End Smoke Test

Use a connected channel (or Codex CLI flow) and run:

/status

Then:

/task run a hello-world runtime check and summarize results

Check artifacts under data/workspaces/<workspace-id>/.

Commands at a Glance

Primary operator/admin commands:

• /task <prompt>
• /search <query>
• /open <path-or-docid>
• /status
• /monitor <goal>
• /admin-channel enable
• /pending-actions
• /approve-action <action-id>
• /deny-action <action-id> [reason]
• /route <task-id> <question|issue|task|moderation|noise> [p1|p2|p3] [due-window]

Full channel setup and command behavior: Channel Setup.

API Endpoints

• GET /healthz
• GET /readyz
• GET /api/v1/heartbeat
• GET /api/v1/info
• POST /api/v1/chat
• GET/POST /api/v1/tasks
• POST /api/v1/tasks/retry
• POST /api/v1/pairings/start
• GET /api/v1/pairings/lookup?token=<token>
• POST /api/v1/pairings/approve
• POST /api/v1/pairings/deny
• GET/POST /api/v1/objectives
• POST /api/v1/objectives/update
• POST /api/v1/objectives/active
• POST /api/v1/objectives/delete

Detailed payloads and response examples: API Reference.

Security Model (Summary)

• Admin/API access is intended to be protected by mTLS.
• Sensitive actions require explicit approval.
• Command execution is sandboxed and allowlist-based.
• Channel identities are linked through one-time pairing tokens.

Operational hardening: Production Checklist.

Documentation

Start here: Docs Index

• Getting started: Getting Started
• Feature guide: Feature Guide
• Install: Install
• Configuration: Configuration
• Operations: Operations
• API reference: API Reference
• Development: Development Guide

Contributing

• Contribution guide: CONTRIBUTING.md
• Code of conduct: CODE_OF_CONDUCT.md
• Security policy: SECURITY.md
• Support: SUPPORT.md
• Changelog: CHANGELOG.md

License

MIT. See LICENSE.