AgentOS

The operating system for AI agents.
10 infrastructure primitives. One gateway. Zero glue code.

---

What is AgentOS?

AgentOS gives AI agents the same infrastructure primitives that operating systems give processes — but over HTTP. Audit trails, distributed locks, event buses, secret vaults, and more — all through a single gateway.

The problem: Every AI agent framework makes you glue together Redis, Postgres, message queues, and custom auth. You end up writing more infrastructure code than agent logic.

The solution: AgentOS provides 10 battle-tested primitives behind one API. Your agents focus on thinking, not plumbing.

Why AgentOS?

The coordination problem: When you run multiple AI agents in parallel, things get messy. Who wrote what? Who's allowed to do what? How do you stop two agents from editing the same thing? How do you wait for 4 agents to finish before a 5th one summarizes?

Works with any framework: AgentOS doesn't care if you use LangChain, CrewAI, AutoGen, or your own custom agents. If your agent can make HTTP calls, it works. Python, TypeScript, Go — doesn't matter. It's infrastructure, not a framework.

Real-world examples:

• Two agents need to edit the same document? → Lock ensures they take turns
• Need to wait for 4 research agents before the CEO agent writes a summary? → Fence syncs them
• Need a tamper-proof log of every decision an agent made? → Ledger with hash-chain verification
• Need to pass an API key to an agent securely, with auto-expiry? → Vault handles it
• Need agents to react to each other's events in real-time? → Bus for pub/sub, Pipe for streaming

Before AgentOS:

Your agent code: 30%
Redis glue code: 15%
Postgres queries: 15%
Auth middleware: 10%
Queue setup: 10%
Custom sync logic: 10%
Logging/audit: 10%

After AgentOS:

Your agent code: 95%
import { AgentOS } from '@agentos/sdk': 5%

Quickstart

# 1. Clone and install
git clone https://github.com/mohshomis/AgentOS.git
cd agentos
npm install

# 2. Start infrastructure (Redis, Postgres, NATS)
docker compose -f docker-compose.infra.yml up -d

# 3. Start all services
bash start.sh

# 4. Open the dashboard
open http://localhost:9100

That's it. 11 services running, dashboard live, ready to go.

The 10 Primitives

Primitive	Port	What it does
Ledger	9010	Immutable audit trail with hash-chain integrity verification
Store	9011	Key-value store with agent/scope isolation and versioning
Boundary	9012	Permission system — define what each agent can access
Lock	9013	Distributed locks with TTL, wait queues, and deadlock prevention
Clock	9014	Signed timestamps, cron scheduling, Lamport clocks
Queue	9015	Priority job queue with retry, dead-letter, and backpressure
Bus	9016	Pub/sub event bus with pattern matching and replay
Fence	9017	Synchronization barriers — wait for N agents before proceeding
Pipe	9018	Real-time streaming between agents via WebSocket
Vault	9019	Encrypted secret storage with read limits and auto-expiry

Plus the Gateway on port 9100 — unified entry point with auth, rate limiting, metrics, and the admin dashboard.

Dashboard

Open http://localhost:9100 after starting services. The dashboard shows:

• Live service health for all 10 primitives
• Registered agents with heartbeat status
• Per-primitive request metrics and latency
• Recent audit trail activity
• System-wide stats (requests, error rate, uptime)

SDK

import { AgentOS } from '@agentos/sdk';

const os = new AgentOS({
  endpoint: 'http://localhost:9100',
  agentId: 'my-agent',
});

// Audit everything
await os.ledger.append({ action: 'task.start', resource: 'analysis' });

// Distributed lock
await os.withLock('shared-resource', async () => {
  // Only one agent runs this at a time
  await os.store.set('result', { status: 'done' });
});

// Signed timestamps (tamper-proof)
const time = await os.clock.now();

// Priority queue
await os.queue.push('tasks', { type: 'analyze', data: '...' }, { priority: 10 });

// Pub/sub events
await os.bus.publish('agent.completed', { agentId: 'my-agent' });

// Sync barrier — wait for 3 agents
await os.fence.arrive('sync-point');

// Encrypted secrets
await os.vault.seal('api-key', 'sk-...', { maxReads: 5, ttl: '1h' });

Resilient Client

The SDK includes automatic retry with exponential backoff, circuit breaker, and middleware hooks:

const os = new AgentOS({
  endpoint: 'http://localhost:9100',
  agentId: 'my-agent',
  retry: { maxRetries: 3, baseDelay: 200 },
  circuitBreaker: { threshold: 5, resetTimeout: 30000 },
  autoAudit: true,  // every SDK call logged to ledger
});

// Middleware hooks
os.onRequest((ctx) => console.log(`→ ${ctx.method} ${ctx.path}`));
os.onResponse((ctx) => console.log(`← ${ctx.response?.status} (${ctx.latency}ms)`));

Auth & Security

AgentOS supports JWT tokens and API keys (disabled by default in dev):

# Generate a JWT token
curl -X POST http://localhost:9100/auth/token \
  -H "Content-Type: application/json" \
  -d '{"agentId":"my-agent","tenant":"acme","scopes":["*"]}'

# Create an API key
curl -X POST http://localhost:9100/auth/api-key \
  -H "Content-Type: application/json" \
  -d '{"name":"my-service","tenant":"acme"}'

# Enable auth in production
AUTH_ENABLED=true bash start.sh

Agent Runtime

Register agents, send heartbeats, track lifecycle:

# Register
curl -X POST http://localhost:9100/runtime/register \
  -H "Content-Type: application/json" \
  -d '{"agentId":"worker-1","name":"Worker","version":"1.0.0"}'

# List all agents
curl http://localhost:9100/runtime/agents

Observability

Built-in metrics at /metrics (Prometheus) and /metrics/json:

curl http://localhost:9100/metrics/json
# → { totalRequests, totalErrors, rps, uptimeHuman, primitives: { ... } }

curl http://localhost:9100/metrics
# → Prometheus-compatible text format

Architecture

┌─────────────────────────────────────────────────────────┐
│                    Gateway (:9100)                       │
│  ┌──────┐ ┌───────────┐ ┌─────────┐ ┌───────────────┐  │
│  │ Auth │ │ Rate Limit│ │ Metrics │ │ Agent Runtime │  │
│  └──────┘ └───────────┘ └─────────┘ └───────────────┘  │
│                    ↓ reverse proxy ↓                     │
├─────────┬────────┬──────────┬────────┬─────────────────┤
│ Ledger  │ Store  │ Boundary │  Lock  │     Clock       │
│ :9010   │ :9011  │ :9012    │ :9013  │     :9014       │
├─────────┼────────┼──────────┼────────┼─────────────────┤
│ Queue   │  Bus   │  Fence   │  Pipe  │     Vault       │
│ :9015   │ :9016  │ :9017    │ :9018  │     :9019       │
└─────────┴────────┴──────────┴────────┴─────────────────┘
         ↓              ↓              ↓
    ┌─────────┐   ┌──────────┐   ┌─────────┐
    │ Postgres│   │  Redis   │   │  NATS   │
    │  :5499  │   │  :6399   │   │  :4299  │
    └─────────┘   └──────────┘   └─────────┘

Configuration

Environment variables:

Variable	Default	Description
REDIS_HOST	localhost	Redis host
REDIS_PORT	6399	Redis port
POSTGRES_HOST	localhost	Postgres host
POSTGRES_PORT	5499	Postgres port
NATS_URL	nats://localhost:4299	NATS connection URL
AUTH_ENABLED	false	Enable JWT/API key auth
RATE_LIMIT_ENABLED	false	Enable rate limiting
JWT_SECRET	(dev default)	JWT signing secret

Tech Stack

• Runtime: Node.js + TypeScript
• Database: PostgreSQL (audit trails, state)
• Cache: Redis (locks, rate limits, sessions)
• Messaging: NATS (pub/sub, event bus)
• Gateway: Express with reverse proxy

License

MIT