// open-source · self-hosted · Apache 2.0

Distributed Agent Harness OS
A Production-grade Harness
for Every Agent

OryxOS is an Agent Harness OS built on Java 21. A harness is the scaffolding that turns a model into a working agent — the loop, tools and their execution, context, memory, sandbox, and audit. OryxOS gives every agent the same production-grade harness and runs a fleet of them like an OS runs processes. Deploy privately on your own K8s or servers.

Get Started GitHub

oryxos — bash

❯oryxos init

✓ Workspace initialized at .oryxos/

agents/ · memory/ · sessions/ · logs/ · oryxos.db

❯oryxos chat --profile ops-agent

Loaded profile: ops-agent (deepseek-chat)

Memory: 3 entries loaded from MEMORY.md

youCheck nginx error logs from the last hour

[ops-agent] Thinking...

→ Tool: shell

→ Input: tail -n 100 /var/log/nginx/error.log | grep "$(date +%H)"

→ SandboxChecker: ✓ allowed

[ops-agent]

Found 3 × 502 errors in the last hour, all from upstream backend:8080

Recommend checking backend service health. Want me to run a diagnostic?

❯

9Maven modules

30+REST endpoints

24built-in tools

3memory layers

∞concurrent agents

HOW IT WORKS

Runtime for one. OS for many.

CORE CAPABILITIES

One directory. Unlimited agents.

One Directory = One Agent

An agent is a directory: AGENT.md = frontmatter (its profile) + a body of instructions, plus optional skills/ and scripts/. Create via REST, generate from one sentence with an LLM, or drop in a directory — WorkspaceWatcher makes it live with no restart.

.oryxos/agents/ops-agent/
├── AGENT.md        # frontmatter + task body
├── skills/*.md     # on-demand sub-instructions
└── scripts/        # on-demand shell scripts

# Drop the dir in → WorkspaceWatcher registers it live
# Or: POST /api/v1/agents  (create / generate / edit)

Dynamic Multi-Provider Routing

Providers live in SQLite with runtime CRUD — add, edit, remove anytime. Agents are provider-agnostic; explicit name → ChatModel routing stays correct, and the model rebuilds when its key or base URL changes.

# Providers are runtime-mutable, stored in SQLite
POST /api/v1/providers
{ "name": "deepseek", "apiKey": "${DEEPSEEK_API_KEY}",
  "baseUrl": "https://api.deepseek.com" }

# An agent just references one by name
provider:
  name: deepseek        # → explicit ChatModel map
  model: deepseek-chat

Self-implemented ReAct Loop

Full control over Reason → Act → Observe — sync execution on Java 21 virtual threads, no Spring AI Agent abstractions. Spring AI is used only for protocol translation and @Tool schema generation.

User message
  → PromptBuilder: system + memory + history + tools
  → ProviderService.call()
  → [Tool call?]
      → SandboxChecker whitelist
      → ToolExecutor.execute()
      → write tool_invocations audit
      → append result → loop
  → [Final reply] → return

Layered Memory System

Session memory plus per-agent long-term memory (.oryxos/agents/<name>/MEMORY.md, keyword search, timestamped). Auto-injected into every system prompt so agents stay consistent across sessions — with a clear upgrade path to vector search.

# Agent saves a preference
Tool: save_memory
Input: {"content": "Prefers Spring Boot over MVC"}

# Persisted per-agent, auto-injected next turn
# .oryxos/agents/ops-agent/MEMORY.md

Tool: recall_memory
Input: {"query": "user preferences"}

Sandboxed Tools + MCP

Built-in file / shell / HTTP tools pass through path, command, and domain whitelists (no SecurityManager), manageable at runtime. Three-tier plugins: zero-code SKILL.md → custom MCP server → native @Tool. Notify channels addressed by name.

# Whitelists, not SecurityManager
shell.allowed_commands: [ls, cat, python3]
http.allowed_domains:   ["*.github.com"]

# Manage at runtime
POST /api/v1/sandbox/whitelist/SHELL
# Extend via MCP server or native @Tool

Web Admin Console

A Vue 3 + Vite console at /admin/ (same theme as this site): agent management with one-sentence generation, Provider / Notify-channel CRUD, scheduled tasks, workspace file browser, and memory views. Audit tables llm_calls and tool_invocations are written from day one.

❯ oryxos serve --port 8080

/api/v1/**     REST API (unified envelope)
/admin/        Web admin console
/swagger-ui    OpenAPI docs

USE CASES

Enterprise-ready scenarios

DevOps Agent

Reads logs, runs shell commands, monitors services. Remembers infra preferences across sessions.

Zero-code PR Digest

Write a SKILL.md and connect a GitHub MCP server — daily PR summaries with no Java code.

Customer Service

Handles queries via REST API, recalls past interactions, escalates when needed.

Knowledge Management

Indexes internal docs, answers questions, persists learned facts to long-term memory.

Code Review Agent

Reviews PRs via MCP, comments on issues, tracks review patterns in memory.

HR Assistant

Answers HR queries, schedules interviews, retrieves policy docs via REST API.

Alert Monitor

Polls monitoring APIs, analyzes anomalies with LLM, sends structured reports.

Multi-Agent Collaboration

Multiple agents share one OryxOS instance, each with its own profile, tools, and memory.

ROADMAP

Built to grow. Phase by phase.

Phase 1CURRENT

Single-node Runtime Kernel

5 core capabilities
Multi-agent on one node
REST API exposure
MCP tool protocol

Phase 2PLANNED

Distributed Foundation

Stateless node design
External state store
Multi-replica horizontal scale

Phase 3VISION

Cross-node A2A Collaboration

Agent discovery & registry
Cross-agent task delegation
A2A protocol standard

GET STARTED

From one agent to a fleet.

Initialize the workspace, configure an LLM provider, and start chatting. Your first agent in under 5 minutes — scale to a fleet whenever you're ready.

Read the Docs GitHub

# 1. Initialize the workspace
❯ oryxos init

# 2. Configure your LLM provider
❯ export DEEPSEEK_API_KEY=your-key-here

# 3. Start your first agent
❯ oryxos chat --profile ops-agent

# Or launch the REST API
❯ oryxos serve --port 8080

Distributed Agent Harness OSA Production-grade Harnessfor Every Agent