Say it in plain language. A team of agents delivers.
The self-hosted Agent Operating System for the enterprise.
OryxOS is the self-hosted Agent OS for the enterprise. Describe a task in one sentence of natural language — OryxOS breaks it down, assembles a team of agents, and they collaborate to deliver the result:
So every company can run its own agents — in plain language. No code to define an agent, no data leaving your infrastructure, every step audited.
- Today, shipped: define an agent in one sentence (or one markdown directory) and it goes live instantly — with memory, 24 built-in tools, MCP connectors, skills, notifications, and cron scheduling, all on your own servers.
- The north star: publish a task in one sentence and an agent team self-organizes to deliver it — planner, specialists, reviewer — fully audited, with humans approving the dangerous steps. See the roadmap.
Long-term vision: enter the Apache Software Foundation as a top-level project.
Everything an agent needs is built into the OS — an agent just references what it wants:
This is the whole point: drive the cost of defining an agent toward zero. You write intent; the OS supplies the capabilities, the safety rails, and the audit trail.
An agent harness is the scaffolding around a model that turns it into a working agent: the loop that drives reason → act → observe, the tools it can call and the execution that runs them, the context assembled before every call, the memory it accumulates, the sandbox that contains it, and the audit trail that records what it did. A bare model only generates text — the harness is what lets it do things, reliably and safely.
The bottleneck for reliable agents in production is not the model — it's the harness around it. And an enterprise never runs just one agent. OryxOS gives every agent the same production-grade harness, and runs the whole fleet like an operating system runs processes — that's the Agent Harness OS.
| Bare Model | Agent Harness | Agent Harness OS | |
|---|---|---|---|
| Scope | A single LLM call | One reliable agent | A fleet of agents |
| Provides | Text generation | Loop, tools + execution, context, memory, sandbox, audit, delivery | Lifecycle, channels, routing, shared registries, scheduling, governance, admin + API |
| Analogy | A CPU instruction | A process with its runtime | An OS running many processes |
OryxOS is the third column — and it ships the second one for every agent it runs.
🤖 One Directory = One Agent
An Agent is a directory: .oryxos/agents/<name>/AGENT.md — YAML frontmatter plus task instructions. Its optional skills/ directory contains relative symlinks to shared Skill entities. Every prompt receives only each bound Skill's name, description, and local path; bodies and resources load on demand. Multiple agents co-exist on one instance.
⚡ Dynamic Agent Management
Create an agent via REST, generate a draft AGENT.md from one sentence with an LLM, or update its workspace directory during a maintenance window. Single-node mode uses WorkspaceWatcher; cluster mode uses version polling and periodic reconciliation to reload definitions without restarting.
📦 One Binary, Zero Ceremony
A single executable artifact with a self-implemented, fully inspectable ReAct loop and synchronous execution on virtual threads. bin/oryx-server start and you're live — REST API, web console, scheduler, and sandbox in one process. No extra runtimes, no sidecars.
🔒 Private & Compliant Runs on your own K8s, VM, or bare metal. Data never leaves your environment. No cloud lock-in. Credentials go through environment variables and your enterprise key management.
🔀 Dynamic Provider Registry
LLM providers and notify channels are stored in SQLite with full CRUD — add, edit, or remove them at runtime. Explicit name → ChatModel routing is preserved; the model is rebuilt and cached when its key or base URL changes.
🛡️ Security as Foundation Tool calls pass through file-path, command, and domain whitelists. Full audit trail from day one — every tool invocation and LLM call is persisted to the audit tables, not just logged.
🔌 Open Standards
Tools via MCP with a three-tier plugin model (zero-code SKILL.md → custom MCP server → native @Tool). Notify channels addressed by name. Agent-to-agent collaboration via A2A on the roadmap.
| Capability | Description |
|---|---|
| LLM Routing | Dynamic, SQLite-backed provider registry with CRUD. Agents are provider-agnostic; explicit name → model routing keeps multi-provider dispatch correct. Switch or add providers at runtime. Local inference supported. |
| ReAct Loop | Self-implemented reasoning engine — no external framework. LLM decides whether and which tool to call; OryxOS executes, feeds the result back; LLM decides the next step. Synchronous execution on virtual threads; loop fully controllable. |
| Memory | Per-agent long-term memory (.oryxos/agents/<name>/MEMORY.md, timestamped entries; global fallback when no agent context). Auto-injected into every system prompt. Recall upgrades to semantic three-route retrieval (vector + keyword + recency, weighted RRF) once embedding.* is configured; pluggable backends incl. self-hosted mem0. |
| Knowledge | Named knowledge bases (.oryxos/knowledge/<name>/) with chunking + embedding indexing (md / txt / text-layer PDF), hybrid retrieval (vector + keyword, RRF fusion) behind a pluggable backend contract; agents bind via symlinks and retrieve with mandatory citations (retrieve_knowledge), hot-reload + admin console lifecycle + usage dashboard included. |
| Tool System | Built-in file, shell, and HTTP tools. Three-tier extension: zero-code SKILL.md + community MCP server → light-code custom MCP server → heavy-code native @Tool method. |
| REST API | All capabilities exposed via REST. Any language can integrate. Business systems connect via HTTP. |
Phase 1 — Single-node Runtime Kernel ✅ (shipped) Define an agent in one sentence or one directory; it goes live with no restart. Memory, 24 built-in tools, MCP, skills, notify, cron, sandbox, full audit, REST API, and a web console — all working on a single node.
Next — parallel tracks, pick one and start (see Vision & Roadmap)
- A · Distributed foundation — pluggable storage (SQLite → MySQL/PostgreSQL), stateless instances, DB-based cluster scheduling (xxl-job style)
- B · Knowledge & memory — built-in knowledge base + semantic memory on a shared vector subsystem
- C · Flow orchestration — declarative markdown flows, sub-agent delegation, A2A protocol
- D · Self-improving agents — auto-distill skills from successful runs
- E · Omni-channel & multimodal — Feishu / WeCom / DingTalk / Slack / Telegram, voice, browser, vision
- F · Container-grade sandboxing — Docker / SSH execution backends
- G · Enterprise governance — multi-tenancy, SSO/RBAC, cost dashboards, capability marketplace
- H · Enterprise-only powers — human-in-the-loop approval, audit-to-data-flywheel, cost governance, smart model routing
- I · The north star — publish a task in one sentence; an agent team self-organizes and delivers the result
oryxos/
├── oryxos-core # OryxTool, Session, ReActLoop, PromptBuilder, ToolExecutor, AgentScheduler
├── oryxos-persona # Persona preset catalog (12 built-in) + user-defined persona CRUD
├── oryxos-provider # ProviderService, Function Calling adapter, explicit multi-provider map
├── oryxos-memory # MemoryService, LongTermMemory, MemoryTools (save/recall)
├── oryxos-knowledge # Knowledge base: local backend plugin, chunk/embed/index pipeline,
│ # hybrid retrieval (vector + keyword + RRF), retrieve_knowledge
├── oryxos-tool # Built-in tools (file/shell/http), MCP Client, ToolRegistry, SandboxChecker
├── channels/ # Channel adapters, grouped under the oryxos-channels aggregator
│ ├── oryxos-channel-cli # CLI channel: oryxos chat implementation
│ ├── oryxos-channel-feishu # Feishu inbound channel (long connection)
│ ├── oryxos-channel-wecom # WeCom smart-bot inbound channel
│ ├── oryxos-channel-dingtalk # DingTalk stream inbound channel
│ ├── oryxos-channel-slack # Slack inbound channel (Socket Mode)
│ ├── oryxos-channel-discord # Discord inbound channel (Gateway)
│ ├── oryxos-channel-telegram # Telegram bot inbound channel
│ ├── oryxos-channel-whatsapp # WhatsApp inbound channel
│ ├── oryxos-channel-teams # Microsoft Teams inbound channel
│ ├── oryxos-channel-gchat # Google Chat inbound channel
│ ├── oryxos-channel-mattermost # Mattermost inbound channel
│ ├── oryxos-channel-matrix # Matrix inbound channel
│ ├── oryxos-channel-qq # QQ official bot inbound channel
│ ├── oryxos-channel-douyin # Douyin OpenAPI inbound channel
│ ├── oryxos-channel-weixin # WeChat iLink bot inbound channel
│ ├── oryxos-channel-weixin-kf # WeChat Customer Service inbound channel
│ ├── oryxos-channel-weixin-mp # WeChat Official Account inbound channel
│ ├── oryxos-channel-weixin-mini # WeChat Mini Program inbound channel
│ └── oryxos-channel-alipay # Alipay lifestyle inbound channel
├── oryxos-web # REST API controllers, Web admin console, GlobalExceptionHandler
├── oryxos-storage # SQLite, SessionRepository, ToolInvocationRepository, LlmCallRepository
├── oryxos-cli # Picocli entry, 12 subcommands, ConfigLoader
└── oryxos-boot # Spring Boot main class, auto-configuration, dependency aggregation
Modules are decoupled through interfaces. Adding a new Channel or Tool requires only a new module — oryxos-core stays untouched.
Prerequisites: Java 21, Maven 3.9+, and an LLM API key (DeepSeek / Qwen / OpenAI / Ollama). The Maven build installs a local Node.js on first run to bundle the admin UI — no global Node.js required.
Quickest setup — SDKMAN! (recommended): the repo ships a .sdkmanrc that pins the exact JDK and Maven versions. After installing SDKMAN, enable sdkman_auto_env=true in ~/.sdkman/etc/config, then:
cd oryxos
sdk env install # installs the JDK + Maven versions declared in .sdkmanrcFrom then on, every cd into the project directory auto-switches to the right toolchain. If you prefer to install Java and Maven yourself (e.g. via apt, brew, or a tarball), make sure java -version reports 21+ and mvn -version reports 3.9+.
Windows: Built-in workspace storage requires a native POSIX filesystem, so start the server inside WSL2 (Ubuntu). Clone into the Linux home directory, for example ~/oryxos, then build and run there. A checkout on a Windows drive such as /mnt/d/... is still NTFS and fails the same startup check. Docker on WSL2 is the other supported path.
git clone https://github.com/oryx-labs/oryxos.git
cd oryxos
mvn package -DskipTests # compiles all modules + bundles the Vue admin UI into the fat JARcp config/application.yml.example config/application.yml
# edit config/application.yml → fill in the deepseek api-keyconfig/application.yml is gitignored, so your key stays local and is never committed. Only one provider key is needed to boot — Spring AI's eager OpenAI auto-config is excluded, so serve starts without spring.ai.openai.api-key.
bin/start.sh # defaults to port 8080; or: bin/start.sh 9000
bin/stop.sh # stopstart.sh launches a single process that serves both the REST API and the Web Manager on the same port, waits for the health check to pass, then prints the URLs (/api/v1/health, /admin/, /swagger-ui). Logs stream to logs/oryxos.log. On the first run it creates config/application.yml from the template and asks you to fill in the key.
JAR=oryxos-boot/target/oryxos-boot-*.jar
java -jar $JAR init # initialize the .oryxos/ workspace (agents/ memory/ sessions/ logs/)
export DEEPSEEK_API_KEY=your-key-here # the CLI reads the key from the environment
java -jar $JAR chat --profile default # interactive multi-turn chat
java -jar $JAR serve --port 8080 # REST API + Web Manager (same as start.sh)The workspace defaults to .oryxos/ but is configurable — set ORYXOS_ROOT (or -Doryxos.root=, or oryxos.root in application.yml) to point OryxOS at a custom workspace directory. The selected workspace root and its checked native execution view are auto-added to the file sandbox whitelist. Shared deployments use the shared-posix provider with a pre-provisioned .workspace-id; see the shared workspace guide for plugin requirements, conflict handling, output isolation and recovery.
Every release also ships a multi-arch container image (linux/amd64 + linux/arm64) on GHCR — no Java 21 install, no tarball download:
docker run -d --name oryxos -p 8080:8080 -v oryxos-data:/data ghcr.io/oryx-labs/oryxos:latest
curl http://localhost:8080/api/v1/health # → {"code":0,…}The container boots keyless (configure providers in the web console afterwards) and keeps all state — config/, the .oryxos/ workspace, oryxos.db, logs — in the /data volume, so upgrading means pulling a new tag and recreating the container. The image runs as a non-root user and carries a built-in healthcheck against /api/v1/health; see docker-compose.yml at the repo root for a ready-to-use compose stack. To build the image locally from source: make docker (after make build).
The example above uses default SQLite — run one container. Multi-replica deployments require shared PostgreSQL and a shared workspace. See the K8s deployment guide and shared-volume requirements. Local kind validation does not establish cross-host storage HA; the 042 acceptance record keeps that verification pending.
serve (and bin/start.sh) exposes one process with two faces on the same port:
| URL | What |
|---|---|
http://localhost:8080/api/v1/** |
REST API (see below) |
http://localhost:8080/admin/ |
Web Manager — Vue 3 console |
http://localhost:8080/swagger-ui |
OpenAPI docs |
The Web Manager is a Vue 3 + Vite console (same stack and dark-orange theme as the site) with pages for agent management (create, one-sentence LLM generation, file editor, per-agent session and memory views), provider and notify-channel CRUD, scheduled tasks, sessions, tools, sandbox whitelist, and a workspace file browser. It is built to oryxos-web/src/main/resources/static/admin/ and served by Spring at /admin, so the fat JAR ships it — no separate frontend process.
When iterating on the console UI, run the Vite dev server instead of rebuilding the JAR each time — it hot-reloads on save and bypasses the browser cache:
# 1. Keep the backend running — the dev server proxies the API to it
bin/start.sh # REST API on :8080
# 2. In another terminal, start the Vite dev server
cd oryxos-web/src/main/frontend
npm install # first time only
npm run dev # → http://localhost:5173/admin/The dev server runs on port 5173 with base /admin/ and proxies /api → localhost:8080 (see vite.config.js). Edit any file under src/ and the page updates instantly. When finished, npm run build bundles the production assets into static/admin/ so the next mvn package ships them in the fat JAR.
One directory = one Agent. Each agent lives in .oryxos/agents/<name>/ with an AGENT.md, optional scripts/references, and a skills/ binding view. Shared Skill entities live under .oryxos/skills/<name>/; an Agent binds one through a relative symlink at agents/<agent>/skills/<name>. Each prompt receives only bound Skill names, descriptions, and local paths. Bodies and resources load on demand through read_file / shell; there is no use_skill tool or .oryxos/profiles/ directory.
---
name: ops-agent
description: DevOps assistant
identity:
agent_name: ops-agent
prompt: You are a professional DevOps assistant...
provider:
name: deepseek # Switch to qwen / ollama / openai — zero code change
model: deepseek-chat
api_key: ${DEEPSEEK_API_KEY}
tools:
- shell
- read_file
- http_get
- save_memory
- recall_memory
schedules:
- key: daily-brief
name: Daily brief
cron: "0 0 9 * * *"
zone: Asia/Shanghai
settings:
max_iterations: 10
max_history_turns: 20
---
You are a professional DevOps assistant. When triggered, ... (task instructions)Schedules with an omitted or blank zone use UTC, consistently across replicas. To keep a local-time schedule when upgrading from the previous system-time-zone default, set zone explicitly to the deployment's former time zone. For example, a daily 09:00 schedule without zone now runs at 17:00 in Shanghai; set zone: Asia/Shanghai to keep 09:00 Shanghai time.
In single-node mode, WorkspaceWatcher registers workspace changes without restarting. In cluster mode, use the management API; direct file changes require a stopped-writer maintenance window and are picked up by periodic reconciliation. Agents can also be created via POST /api/v1/agents or drafted from one sentence via the admin console.
All endpoints are prefixed with /api/v1 and every response is wrapped in a unified envelope: { "code": 0, "message": "success", "data": <payload>, "timestamp": ... } (non-zero code on error). Authentication is configurable and disabled by default; configure web authentication, API keys and authorization for your deployment before exposing protected operations.
| Method | Path | Description |
|---|---|---|
POST GET |
/agents, /agents/{name} |
Agent CRUD (create / list / get / PUT update / DELETE archive) |
POST |
/agents/{name}/invoke |
Stateless single-turn invocation |
GET |
/agents/{name}/memory |
This agent's long-term memory |
GET POST |
/agents/{name}/session, /agents/{name}/session/messages |
Console session + send message |
POST |
/agents/{name}/generate-files |
One sentence → LLM-drafted AGENT.md (preview only) |
POST |
/agents/{name}/files |
Save edited agent files |
POST GET |
/providers, /providers/{name} |
Provider CRUD (create / list / get / PUT / DELETE) |
POST GET |
/notify-channels, /notify-channels/{name} |
Notify-channel CRUD |
POST GET |
/sessions, /sessions/{id} |
Session create / list / history / DELETE archive |
POST |
/sessions/{id}/messages |
Send a message (triggers ReAct Loop) |
GET POST PUT |
/schedules, /schedules/{id}/executions, /schedules/{id}/run, /schedules/{id} |
List / history / run-now / enable-disable |
GET POST DELETE |
/sandbox/whitelist, /sandbox/whitelist/{category} |
List / add / remove sandbox entries (FILE|SHELL|HTTP) |
GET POST |
/workspace/tree, /workspace/file |
Workspace file browser (read tree / read / write file) |
GET |
/profiles |
List derived profiles (one per agent) |
GET |
/tools |
List available tools |
GET |
/health, /info |
Health check / runtime info + provider status |
- Platform before Agent — the most important deliverable is not a powerful Agent, but the environment that lets any Agent run reliably
- Self-implement the core — reasoning loop is self-implemented; protocol adapters reuse mature libraries; no reinventing the wheel
- One directory = one Agent —
AGENT.md+ Agent-local Skill symlinks + optional scripts, not code - Open standards — MCP for tools, A2A for collaboration, open formats for skills
- Stateless instances — state externalized from the start; the prerequisite for scaling to distributed
- Security as foundation — controlled tool sources, least privilege, mandatory sandbox, encrypted storage for managed secrets, audit trails
- Phased and disciplined — build the minimal complete runtime kernel first; every architecture upgrade is proven by real usage data
| Component | Choice |
|---|---|
| Language / Runtime | Java 21 (virtual threads) |
| Framework | Spring Boot 3.x |
| LLM Integration | Spring AI (OpenAI-compatible protocol translation + @Tool schema only) |
| CLI | Picocli |
| Config | SnakeYAML |
| Persistence | SQLite (default) / PostgreSQL (cluster), Spring Data JPA; pluggable local/shared POSIX workspace |
| Logging | Logback + SLF4J (structured JSON) |
| Build | Maven multi-module |
First PRs are welcome — see the Contributing Guide and the GitHub workflow primer.
Apache License 2.0 · oryx-labs · Goal: Apache Software Foundation top-level project