oar

Open Agent Runtime (OAR)

A containerized agent orchestration system that enables execution of arbitrary workloads packaged as OCI images. OAR provides session-based agent execution with container reuse optimization and automatic lifecycle management.

Overview

Open Agent Runtime is designed to run containerized agents that expose HTTP endpoints for receiving work payloads. The system manages the complete lifecycle of these agents, from container creation to cleanup, while providing session management capabilities for stateful interactions.

Key Features

• Containerized Execution: Agents are packaged as OCI images and executed in isolated containers
• Session Management: Logical grouping of related agent invocations with container reuse
• Automatic Lifecycle Management: On-demand container creation with configurable TTL and cleanup
• Identity & Secrets Management: OAuth 2.0 compliant identity system with JWT-based authentication and cloud federation
• Cloud Provider Federation: Secure credential-free access to AWS, GCP, and Azure via OIDC
• Secrets Management: Unified interface for accessing secrets from Kubernetes, AWS Secrets Manager, GCP Secret Manager, or Azure Key Vault
• Multiple Deployment Modes: Standalone and distributed architectures
• Backend Flexibility: Support for Kubernetes orchestration
• TLS Security: Built-in mutual TLS authentication and encryption

Architecture

OAR operates in two deployment modes:

Standalone Mode

Both the HTTP API Server and Agent Orchestrator run within the same process. Suitable for single-node deployments and development environments.

Distributed Mode

The Agent Orchestrator runs as a separate service from the HTTP API Server, enabling deployment across multiple backend clusters while centralizing the API interface.

Core Components

Agent: A unit of work defined by an OCI image that exposes an HTTP endpoint for receiving work payloads.

Session: A logical grouping of related agent invocations identified by an invocation ID, allowing for container reuse and stateful interactions.

HTTP API Server: Exposes REST API endpoints for agent management, invocation, session management, and system status.

Agent Orchestrator: Manages complete agent lifecycle including pod management, session tracking, and cleanup operations.

Requirements

• Go 1.24 or later
• Docker (for local development)
• Kubernetes cluster or Podman (for agent execution)
• PostgreSQL database

Installation

From Source

git clone https://github.com/MadsRC/oar.git
cd oar
go build -o oar .

Using Go Install

go install github.com/MadsRC/oar@latest

Quick Start

Using the HTTP API

The OAR API is a REST API accessible at port 8443 (HTTPS). The full API specification is available at docs/usage/openapi.json.

Register an Agent

curl -X POST https://localhost:8443/v1/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-agent",
    "image": "myregistry/my-agent:latest",
    "description": "My agent description",
    "labels": {"env": "dev"}
  }'

List Agents

curl https://localhost:8443/v1/agents

Invoke an Agent

curl -X POST https://localhost:8443/v1/agents/{agentID}/invocations \
  -H "Content-Type: application/json" \
  -d '{"input": {"message": "hello"}}'

Check Health

curl https://localhost:8443/v1/health

Server Operations

# Start server in distributed mode (requires database and orchestrator)
go run . server start --distributed --orchestrator-url https://orchestrator:8444

# For development with TLS certificates
make dev-setup
make run-server

Agent Development

Agents must be packaged as OCI images that expose an HTTP endpoint. The agent should:

1. Listen on a configurable port (default: 8080)
2. Accept POST requests with JSON payloads
3. Return appropriate HTTP status codes and responses

Example agent structure:

my-agent/
├── Dockerfile
├── main.go
└── go.mod

Backend Support

Kubernetes

• Full distributed and standalone mode support
• Pod-based agent execution with sidecar metadata service
• Automatic resource cleanup
• RBAC integration
• Integrated identity and secrets management

Documentation

API Documentation

• OpenAPI Specification: docs/usage/openapi.json - Complete REST API specification
• API Guide: docs/usage/api.md - Detailed API usage guide with examples

User Guides

• Agent Authentication: docs/usage/agent-authentication.md - How agents authenticate and use identity
• Secrets Management: docs/usage/secrets-management.md - Accessing secrets from multiple backends
• AWS Federation: docs/usage/aws-federation.md - AWS STS integration via OIDC
• GCP Federation: docs/usage/gcp-federation.md - GCP Workload Identity integration
• Azure Federation: docs/usage/azure-federation.md - Azure Workload Identity integration

Development Documentation

• Architecture: docs/development/ - System design and implementation details
• Security Hardening: docs/development/security-hardening.md - Security model, threat analysis, and production recommendations
• Design Documents: Design documents for identity and secrets system, HTTP API migration, and more

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Repository

https://github.com/MadsRC/oar