Agent OS

An interactive macOS-style desktop simulation for demonstrating AI agent patterns and concepts.

Built for the Building Better Agents workshop

Live Demo | Getting Started | Deploy to Vercel | Architecture

---

Overview

Agent OS is an educational demo platform that simulates a macOS desktop environment to teach fundamental AI agent concepts. Each "app" in the OS demonstrates different agent patterns, from basic script execution to advanced autonomous decision-making with approval workflows.

Who Is This For?

Audience	Value
Developers	Learn agent architecture patterns through hands-on examples
Project Managers	Understand AI autonomy vs. trust tradeoffs for product decisions
Designers	Explore UX patterns for AI transparency and human-in-the-loop workflows
Workshop Attendees	Interactive playground for the Building Better Agents curriculum

---

Key Features

macOS Desktop Experience

• Window Management — Drag, resize, minimize, maximize, and close windows
• Dock — App launcher with running indicators and magnification effects
• Menu Bar — System controls, time display, and app-specific menus
• Spotlight Search — Quick app launching with Cmd + Space
• Launchpad — Grid view of all available apps
• Control Center — System toggles and settings
• Desktop Widgets — Clock and calendar widgets
• Animated Wallpapers — Dynamic aurora background effects
• Context Menus — Right-click actions throughout the interface
• Boot Screen — Authentic startup animation

Agent Demonstrations

App	Concept	What It Teaches
Terminal	Script vs. Agent Mode	Compare deterministic scripts with AI interpretation
Calendar	Four Pillars	Intent, Memory, Tools & Feedback loops
Docker	Autonomy vs. Trust	Adjustable independence with approval workflows
Notes	Specialization	Why focused agents outperform generalists

Security & Governance

• API Rate Limiting — 20 requests per minute per IP
• Input Validation — Zod schema validation on all API endpoints
• Security Headers — CSP, X-Frame-Options, and more
• Global Agent Toggle — Enable/disable AI features system-wide
• Per-App Settings — Fine-grained control over each app's AI behavior
• Approval Workflow — Modal prompts for high-risk agent actions
• Action History — Audit trail of all agent decisions

---

Deploy to Vercel

The fastest way to get Agent OS running is with Vercel's one-click deploy:

One-Click Deploy

Step-by-Step Vercel Deployment

1. Fork the Repository

   # Or clone and push to your own repo
   git clone https://github.com/RitualChain/agent-os.git
   cd agent-os

2. Import to Vercel

   • Go to vercel.com/new
   • Click Import Git Repository
   • Select your forked/cloned repository

3. Configure Environment Variables

   In the Vercel dashboard, add these environment variables:

   Variable	Required	Description
   ANTHROPIC_API_KEY	Yes	Your Anthropic API key from console.anthropic.com
   DATABASE_URL	No	Neon Postgres connection string (optional, for persistence)

4. Deploy

   • Click Deploy
   • Wait for the build to complete (typically 1-2 minutes)
   • Your app will be live at your-project.vercel.app

Post-Deployment Setup

Connect a Database (Optional)

For persistent features like saving notes and calendar events:

1. Create a free database at neon.tech
2. Copy the connection string
3. Add DATABASE_URL to your Vercel environment variables
4. Run the migration:

   # Option 1: Using Drizzle Kit
   npx drizzle-kit push
   
   # Option 2: Direct SQL
   psql $DATABASE_URL < scripts/001_create_agent_tables.sql

5. Redeploy from the Vercel dashboard

Custom Domain

1. Go to Settings > Domains in your Vercel project
2. Add your custom domain
3. Follow the DNS configuration instructions

---

Getting Started (Local Development)

Prerequisites

• Node.js 18.17+ or Bun 1.0+
• Anthropic API Key (required for AI features)
• Neon Database account (optional, for persistence)

Installation

# Clone the repository
git clone https://github.com/RitualChain/agent-os.git
cd agent-os

# Install dependencies
bun install
# or
npm install

# Set up environment variables
cp .env.example .env.local

Environment Variables

Edit .env.local with your values:

# Required for AI features
ANTHROPIC_API_KEY=your_anthropic_api_key

# Optional: Database persistence
DATABASE_URL=postgres://user:pass@host/database

Development

# Start the development server
bun dev
# or
npm run dev

# Open http://localhost:3000

Build & Production

# Create production build
bun run build

# Start production server
bun run start

---

Architecture

agent-os/
├── app/                      # Next.js App Router
│   ├── api/agent/            # AI agent API routes
│   │   ├── route.ts          # Streaming agent responses
│   │   └── generate/route.ts # One-shot text generation
│   ├── globals.css           # Design system & tokens
│   ├── layout.tsx            # Root layout with fonts
│   └── page.tsx              # Main entry point
├── components/
│   ├── apps/                 # Individual app implementations
│   │   ├── terminal.tsx      # Script vs Agent demo
│   │   ├── calendar.tsx      # Four Pillars demo
│   │   ├── docker.tsx        # Autonomy slider demo
│   │   ├── notes.tsx         # AI categorization demo
│   │   └── ...               # Other apps
│   ├── ui/                   # Reusable UI primitives (Radix-based)
│   ├── widgets/              # Desktop widgets
│   └── ...                   # Desktop components
├── lib/
│   ├── agent-context.tsx     # Global agent state management
│   ├── db.ts                 # Neon Postgres connection
│   └── utils.ts              # Utility functions
├── middleware.ts             # Rate limiting & security
├── SECURITY.md               # Security documentation
└── scripts/
    └── 001_create_agent_tables.sql  # Database schema

State Management

The agent system uses React Context (AgentProvider) to manage:

interface AgentState {
  globalEnabled: boolean           // Master toggle
  terminalMode: 'script' | 'agent' // Terminal behavior
  calendarAssistantEnabled: boolean
  dockerAutonomyLevel: number      // 0-100 slider
  notesAiEnabled: boolean
  pendingActions: AgentAction[]    // Awaiting approval
  actionHistory: AgentAction[]     // Audit trail
  currentThinking: string | null   // Live reasoning
  isProcessing: boolean
}

API Routes

Endpoint	Method	Purpose
/api/agent	POST	Stream AI responses with tool calling
/api/agent/generate	POST	One-shot text generation

Both routes include:

• Zod input validation
• Rate limiting (20 req/min per IP)
• Error sanitization

---

Demo Walkthrough

Terminal: Determinism Demo

1. Open Terminal from the dock
2. Click "Run Demo" or type demo
3. Watch the comparison between:
   • Script Mode: Deterministic 5 + 3 = 8 (always)
   • Agent Mode: Interprets "help with 5 and 3" differently each run

Calendar: Four Pillars

1. Open Calendar from the dock
2. Try natural language: "Meeting with Sarah tomorrow at 3pm"
3. Observe the four pillars in action:
   • Intent: Parses your request
   • Memory: Remembers patterns
   • Tools: Creates the event
   • Feedback: Confirms success

Docker: Trust Levels

1. Open Docker from the dock
2. Adjust the Autonomy Slider (0-100%)
3. Try container actions at different levels:
   • Low (0-30%): Every action requires approval
   • Medium (30-70%): Routine actions auto-approve
   • High (70-100%): Full autonomy, notification only

Notes: Specialization

1. Open Notes from the dock
2. Create a new note with content
3. Enable AI Categorization
4. Watch the specialized agent suggest folders, tags, and summaries

---

Database Schema

For persistent features, Agent OS uses Neon Postgres:

-- Agent memory for learned patterns
agent_memory (app_id, memory_type, key, value)

-- Audit trail of all decisions
agent_actions_log (app_id, action_type, autonomy_level, approved, reasoning)

-- Per-app user preferences
user_preferences (app_id, autonomy_level, settings)

-- Calendar events
calendar_events (title, start_time, end_time, created_by_agent)

-- Notes with AI metadata
notes (title, content, folder, tags, ai_summary, ai_category)

Run migrations:

# Using Drizzle Kit (recommended)
npx drizzle-kit push

# Or direct SQL
psql $DATABASE_URL < scripts/001_create_agent_tables.sql

---

Tech Stack

Category	Technology
Framework	Next.js 16.1 (App Router)
Runtime	React 19, TypeScript 5
Styling	Tailwind CSS 4, CSS Variables
Animation	Framer Motion 12
UI Primitives	Radix UI
AI	Vercel AI SDK 6, Claude Sonnet
Database	Neon Postgres, Drizzle ORM
Validation	Zod 4
Analytics	Vercel Analytics
Package Manager	Bun (recommended) or npm

---

Security

Agent OS includes production-ready security features:

• Rate Limiting — Middleware limits API requests
• Input Validation — All endpoints validate with Zod schemas
• Security Headers — CSP, X-Frame-Options, X-Content-Type-Options
• Environment Safety — Graceful handling of missing env vars

See SECURITY.md for the full security policy and production deployment checklist.

---

Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open a Pull Request

Development Guidelines

• Follow the existing code style
• Add TypeScript types for all new code
• Use semantic tokens from the design system
• Test on both light and dark modes
• Ensure mobile responsiveness

---

License

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

---

Acknowledgments

• Apple — For the macOS design inspiration
• Vercel — For the AI SDK and hosting platform
• Anthropic — For Claude, powering the agent demos
• Radix UI — For accessible UI primitives
• Building Better Agents Workshop — The curriculum this demo supports

Special Thanks

A huge thank you to @StarKnightt for open-sourcing the base version of the emulated macOS on v0's platform. Their foundational work made it possible to remix and extend into this demonstration showcasing applications designed for highlighting agentic enhancement techniques.

---

Made with care for the AI agent community

Back to Top