Documentation

OmniArena

Bare-metal execution layer for AI agents. 186KB binary. 6-layer defense including seccomp-bpf. Per-agent identity & rate limiting. Python + JavaScript SDKs. Zero dependencies.

What is OmniArena?

OmniArena is not an AI agent. It does not think, decide, or generate code. It is the execution layer that sits between your AI agent and the operating system.

When an AI agent (OpenClaw, Claude Code, LangChain, CrewAI, or any custom agent) needs to run a shell command, OmniArena receives it via HTTP, checks it against the active security policy, and executes it inside a kernel-level controlled environment with 6 layers of defense: command filtering, network namespace isolation (no connectivity), filesystem jail (chroot + read-only bind mounts), resource limits, privilege restrictions, and seccomp-bpf kernel filter (blocks 17 dangerous syscalls including socket, connect, ptrace). If the command is dangerous, OmniArena blocks it before it reaches the kernel.

How it fits in the stack

You → "create a Python app that calculates fibonacci"

AI Agent → decides what commands to run

OmniArena → executes or blocks, logs everything

Kernel → hardware

Important distinction

OmniArena does not replace your agent framework. It complements it. Your agent decides what to do. OmniArena controls how it gets executed at the system level — with process isolation, resource limits, policy enforcement, and full audit logging. If the agent makes a mistake, OmniArena is the last barrier before the kernel.

Quick Start

Install OmniArena

One command. Installs binary + dashboard + systemd service. 186KB, zero dependencies.

# Install OmniArena (downloads binary + dashboard + systemd service)
curl -sSL https://getomnios.com/install/omniarena.sh | sudo bash

# Or download manually:
curl -fsSL https://getomnios.com/downloads/omniarena/omniarena-linux -o omniarena
chmod +x omniarena
sudo ./omniarena   # root = full 6-layer isolation (namespaces + seccomp-bpf)

Connect your AI agent

Choose your integration method. All agents get controlled execution, rate limiting, audit logging, and seccomp-bpf kernel protection automatically.

For OpenClaw and any MCP-compatible agent. One script configures everything: MCP server, mcporter, and auto-start.

# 1. Start OmniArena (if not already running)
sudo omniarena &

# 2. Run the OpenClaw integration setup (downloads MCP bridge + configures mcporter)
curl -fsSL https://getomnios.com/downloads/omniarena/omniarena-setup.sh | bash

# 3. Done! OpenClaw now executes commands through OmniArena.
#    Ask your agent: "List the files in /tmp using OmniArena"
#    Every command is controlled, logged, and rate-limited automatically.

For LangChain, CrewAI, AutoGPT, or any Python agent. Replace subprocess.run() with arena.exec().

pip install omniarena

from omniarena import Arena

arena = Arena()  # connects to localhost:7575
result = arena.exec("echo hello", agent="my-agent", model="claude-opus-4",
                     tokens_in=100, tokens_out=30)
print(result.stdout)  # "hello\n"

# Works with LangChain, CrewAI, or any Python agent:
# Just replace subprocess.run() with arena.exec()

For Node.js agents. Native fetch, zero dependencies, TypeScript definitions included.

import { Arena } from 'omniarena'

const arena = new Arena()  // connects to localhost:7575
const result = await arena.exec("echo hello", {
  agent: "my-agent", model: "gpt-4o",
  tokensIn: 100, tokensOut: 30
})
console.log(result.stdout)  // "hello\n"

For any language or framework. OmniArena is a standard HTTP API — just POST JSON.

# Any language, any framework — just HTTP POST
curl -u arena:omniarena -X POST http://localhost:7575/api/exec \
  -H "Content-Type: application/json" \
  -H "X-Agent: my-agent" \
  -d '{"cmd":"echo hello","tokens_in":100,"tokens_out":30,"model":"claude-opus-4"}'

# Response:
# {"ok":true,"stdout":"hello\n","stderr":"","exit_code":0,"duration_ms":1}

# Blocked command:
curl -u arena:omniarena -X POST http://localhost:7575/api/exec \
  -d '{"cmd":"rm -rf /"}'
# {"ok":false,"error":"command blocked by blacklist"}

Verify

# Health check
curl -u arena:omniarena http://localhost:7575/api/health

# See all registered agents and their metrics
curl -u arena:omniarena http://localhost:7575/api/agents

# Audit log
curl -u arena:omniarena http://localhost:7575/api/audit

Defaults

Port: 7575 Auth: arena:omniarena Profile: strict Rate limit: 20 req/s global Per-agent: 30 req/min Isolation: 6-layer + seccomp-bpf

Dashboard

Open http://localhost:7575 in your browser. No authentication required for the dashboard.

What you see

▸ 7 metric cards — total executions, blocked commands, bytes captured, uptime, active profile, isolation level, binary size
▸ 11-column agents table — Status, Agent, Execs, Blocked, Bytes, Rate/min, TokensIn, TokensOut, Model, LastActive
▸ Sandbox terminal — an input field to run shell commands manually
▸ Profile selector — switch between strict, moderate, and permissive
▸ Audit log — last 20 events, auto-refreshes every 3 seconds

The terminal field is not a chat

The input field in the dashboard executes raw shell commands (like ls -la or python3 -c 'print(1+1)'). It does not understand natural language. It is the same as calling POST /api/exec manually. Use it for testing and monitoring — your AI agent calls the API directly.

Typical workflow

Your AI agent works in the terminal (via MCP or HTTP). You open the dashboard in a browser to supervise in real time: see what commands the agent is running, which ones were blocked, and the full audit trail. Think of it as a control room.

API Reference

All endpoints require authentication: HTTP Basic Auth (arena:omniarena) or Bearer Token (Authorization: Bearer <token>). Token read from /etc/omniarena/token or defaults to omniarena-default-token. CORS enabled. Dashboard at GET / requires no auth. Use X-Agent: name header for per-agent identity tracking.

GET /api/health

Sandbox status: active profile, execution counts, uptime, resource limits.

{
  "ok": true,
  "version": "1.0.4",
  "uptime_sec": 3600,
  "total_execs": 42,
  "blocked_cmds": 3,
  "profile": "strict",
  "isolation": "kernel",
  "agents_count": 3,
  "max_rate_per_agent": 30,
  "default_token_budget": 0,
  "binary_size": "~186KB",
  "dependencies": 0
}

POST /api/exec

Execute a shell command. Checked against the active security policy.

Request

{ "cmd": "ls -la /tmp" }

Success (200)

{
  "ok": true,
  "stdout": "total 0\ndrwxrwxrwt 2 root root 40 ...",
  "stderr": "",
  "exit_code": 0,
  "duration_ms": 5,
  "files": ["output.txt", "data.csv"]
}

Blocked (403)

{
  "ok": false,
  "error": "command blocked by blacklist"
}

POST /api/profile

Switch security profile. Immediate effect.

Request

{ "profile": 1 }

Response

{
  "ok": true,
  "profile": 1,
  "timeout_ms": 30000,
  "max_mem_mb": 256,
  "max_cpu_sec": 30
}

GET /api/agents

Per-agent metrics: executions, blocked commands, bytes, rate/min, token consumption, model. Up to 8 agents auto-registered via X-Agent header.

{
  "agents": [
    {
      "name": "claude-agent",
      "execs": 142,
      "blocked": 3,
      "bytes": 28400,
      "rate_1m": 5,
      "last_active": 1711036800,
      "tokens_in": 15000,
      "tokens_out": 8200,
      "tokens_total": 23200,
      "token_budget": 50000,
      "model": "claude-4"
    }
  ],
  "count": 1,
  "max": 8,
  "rate_limit": 30
}

GET /api/audit

Audit log. Every execution recorded with timestamp, command, result, and exit code. Also persisted to /var/log/omniarena/audit.log.

{
  "entries": [
    "[00:01:23] EXEC ls -la → exit:0 OK",
    "[00:01:25] BLOCK rm -rf / → exit:0 BLACKLIST",
    "[00:02:10] CONFIG set_profile → exit:1 OK"
  ]
}

POST /api/budget

Set token budget per agent or global default. When an agent exceeds its budget, all further commands are rejected with 429.

# Per-agent budget
curl -u arena:omniarena -X POST http://localhost:7575/api/budget \
  -H 'Content-Type: application/json' \
  -d '{"agent":"claude-agent","max_tokens":50000}'

# Global default budget
curl -u arena:omniarena -X POST http://localhost:7575/api/budget \
  -H 'Content-Type: application/json' \
  -d '{"default":100000}'

# Response: {"ok":true,"agent":"claude-agent","max_tokens":50000}

POST /api/policy/reload

Hot-reload policy from /etc/omniarena/policy.conf. Updates blacklist, whitelist, and config without restart.

curl -u arena:omniarena -X POST http://localhost:7575/api/policy/reload

# Response: {"ok":true,"blacklist_count":17,"whitelist_count":14,"profile":0}

# Policy file format (/etc/omniarena/policy.conf):
# [blacklist]
# rm -rf /
# wget
# [whitelist]
# ls
# echo
# [config]
# profile=0
# default_token_budget=50000

DELETE /api/sandbox

Reset sandbox: clear audit log and counters.

{ "ok": true, "message": "sandbox reset" }

Security Profiles

Profile	Policy	Timeout	Mem	CPU	Procs
0 — Strict	Whitelist only	5s	64MB	5s	5
1 — Moderate	Blacklist	30s	256MB	30s	10
2 — Permissive	Audit only	5min	1GB	5min	50

# Switch to moderate
curl -u arena:omniarena -X POST http://localhost:7575/api/profile \
  -d '{"profile": 1}'

# Switch back to strict
curl -u arena:omniarena -X POST http://localhost:7575/api/profile \
  -d '{"profile": 0}'

Policy Engine

Blacklist (always blocked)

rm -rf /dd if=mkfs:() (fork bomb)wget, curlnetcat, nmapchmod 777, chown rootshutdown, reboot/etc/shadow, /etc/passwd.ssh/id_, /dev/sda

Whitelist (strict mode)

ls, cat, echo, pwdhead, tail, wcgrep, finddate, whoami, unamepython3, node

Strict: Command must start with a whitelisted command. Blacklist also checked.

Moderate: Only blacklisted commands are blocked. Everything else allowed.

Permissive: Nothing blocked. Everything audited.

Kernel Isolation

When running as root, OmniArena applies 6 layers of kernel-level isolation to every command execution. This provides Docker-level isolation without Docker.

Layer	Mechanism	What it protects
1	Blacklist	Fast-path: rejects before fork (saves resources)
2	CLONE_NEWNET	Empty network stack: no HTTP, no reverse shells, no data exfiltration
3	CLONE_NEWNS + chroot	Isolated filesystem: only /bin, /usr/bin, /lib (read-only) + /tmp (writable tmpfs)
4	setrlimit x5	CPU, RAM, processes, file size, file descriptors
5	NO_NEW_PRIVS	No privilege escalation via SUID binaries
6	seccomp-bpf	Blocks 17 dangerous syscalls (socket, connect, ptrace, reboot...) at kernel level — unevadable

As root (kernel isolation)

Network: completely isolated (no loopback) Filesystem: chroot jail at /var/arena/jail Visible: /bin, /usr/bin, /lib, /lib64 (read-only) Writable: /tmp only (fresh tmpfs per execution) Invisible: /etc, /home, /root, /proc, /sys Health API: "isolation": "kernel"

Without root (basic isolation)

Blacklist + whitelist policy engine setrlimit resource caps (CPU, RAM, procs) NO_NEW_PRIVS privilege restriction Full audit logging No namespace isolation (requires root) Health API: "isolation": "basic"

Graceful degradation

OmniArena works without root — it automatically falls back to blacklist + rlimits isolation. Run as root for full kernel-level protection. The /api/health endpoint reports the active isolation level so you can verify.

Resource Limits

Every command runs in an isolated child process with kernel-enforced limits via setrlimit. As root, each command also runs inside Linux namespaces (mount, network) with a chroot jail.

Resource	Description	Signal
RLIMIT_CPU	Max CPU seconds	SIGKILL
RLIMIT_AS	Max virtual memory	ENOMEM
RLIMIT_NPROC	Max child processes	EAGAIN
RLIMIT_FSIZE	Max file size	SIGXFSZ
RLIMIT_NOFILE	Max open file descriptors	EMFILE

Configuration

Compile-time globals in source code. Modify before building with omnic.

Param	Default	Description
PORT	7575	HTTP listen port
MAX_RPS	20	Rate limit (req/s)
AUTH_USER	arena	Basic Auth user
AUTH_PASS	omniarena	Basic Auth password
AUDIT_SLOTS	64	Max log entries (ring buffer)
g_profile	0	Initial security profile (0/1/2)
MAX_AGENTS	8	Max concurrent agents
g_max_rate_per_agent	30	Per-agent rate limit (req/min)
Bearer token	/etc/omniarena/token	Bearer token file (fallback: omniarena-default-token)