Biz OS

Open source AI-powered business operating system. Build production-ready AI agents with proper authentication, MCP servers, and human-in-the-loop workflows.

Features

• Email Concierge Agent - Scans inbox, classifies emails, drafts replies
• Two Agent Modes:
  • Ambient/Background - Event-driven batch processing
  • Conversational - Chat interface for queries
• Auth0 Integration:
  • User authentication (social login)
  • Token Vault (secure OAuth storage)
  • Async authorization (human-in-the-loop)
• MCP Server - Protected Gmail tools, works with ChatGPT, Claude, Cursor
• Supabase - Local PostgreSQL for tasks and connections

---

Quick Start

# 1. Clone the repo
git clone https://github.com/hollaugo/biz-os.git
cd biz-os

# 2. Ensure Docker Desktop is running

# 3. Configure environment
cp .env.example .env.local

# 4. Edit .env.local with your credentials:
#    - Auth0 (domain, client ID, secret)
#    - OpenAI API key
#    - Google OAuth (for Gmail access)

# 5. Start everything
./scripts/start-all.sh

The start script will:

• Check prerequisites (Node.js, Python, Docker, Supabase CLI)
• Install dependencies automatically
• Start Supabase, MCP Server, and Web App

Open: http://localhost:3000

---

Prerequisites

Tool	Install Command
Node.js 20+	nodejs.org
Python 3.11+	python.org
Docker Desktop	docker.com
Supabase CLI	brew install supabase/tap/supabase
uv (Python)	curl -LsSf https://astral.sh/uv/install.sh | sh

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    NEXT.JS APP (port 3000)                   │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │   Auth0     │  │   AI SDK    │  │   Tasks     │          │
│  │   Login     │  │   Agent     │  │   UI        │          │
│  └─────────────┘  └─────────────┘  └─────────────┘          │
└─────────────────────────────────────────────────────────────┘
           │                │                │
           v                v                v
┌──────────────┐  ┌──────────────────┐  ┌──────────────┐
│    Auth0     │  │   MCP Server     │  │   Supabase   │
│  (Identity   │  │   (port 8001)    │  │  (port 54321)│
│   + Tokens)  │  │                  │  │              │
└──────────────┘  └──────────────────┘  └──────────────┘
                          │
                          v
                  ┌──────────────┐
                  │  Gmail API   │
                  └──────────────┘

---

Project Structure

biz-os/
├── scripts/
│   ├── install.sh          # One-time setup script
│   ├── start-all.sh        # Start all services
│   └── supabase-start.sh   # Supabase bootstrap
├── web/                     # Next.js 15 app
│   └── src/
│       ├── app/             # App Router pages
│       ├── components/      # React components
│       └── lib/             # Auth0, AI SDK, tasks
├── mcp-servers/
│   └── email-mcp/           # FastMCP Gmail server
├── supabase/                # Local Supabase config
├── .env.example             # Environment template
└── README.md

---

Manual Setup

1. Install Dependencies

./scripts/install.sh

2. Configure Environment Variables

Copy the example and fill in your credentials:

cp .env.example .env.local

Required variables:

# Auth0 (create app at https://manage.auth0.com)
AUTH0_DOMAIN='your-tenant.auth0.com'
AUTH0_CLIENT_ID='...'
AUTH0_CLIENT_SECRET='...'
AUTH0_SECRET='...'  # Run: openssl rand -hex 32

# OpenAI
OPENAI_API_KEY='sk-...'

# Supabase (auto-filled after starting Supabase)
SUPABASE_URL='http://127.0.0.1:54321'
SUPABASE_ANON_KEY='...'
SUPABASE_SERVICE_ROLE_KEY='...'

3. Start All Services

./scripts/start-all.sh

4. Open the App

• Web App: http://localhost:3000
• Supabase Studio: http://localhost:54323
• MCP Server: http://localhost:8001

---

Auth0 Setup

1. Create an Auth0 Application (Regular Web App)
2. Set Allowed Callback URLs: http://localhost:3000/api/auth/callback
3. Set Allowed Logout URLs: http://localhost:3000
4. Enable Google social connection
5. Copy credentials to .env.local

For Token Vault (Gmail):

• Enable Auth0 for AI Agents features
• Configure Gmail as an external connection

---

Useful Commands

# Start everything
./scripts/start-all.sh

# Re-run installation
./scripts/install.sh

# Check Supabase status
supabase status

# Stop Supabase
supabase stop

# Generate Auth0 secret
openssl rand -hex 32

---

Troubleshooting

Docker not running:

❌ Docker is not running. Please start Docker Desktop.

→ Open Docker Desktop and wait for it to start.

Missing environment variables:

❌ Missing web/.env.local

→ Run cp .env.example web/.env.local and fill in credentials.

Port already in use: → Stop other services on ports 3000, 8001, or 54321.

---

For Developers

Key files to understand:

File	Description
web/src/lib/agents/email-concierge.ts	Ambient agent logic
web/src/app/api/agent/route.ts	Chat agent endpoint
mcp-servers/email-mcp/server.py	MCP server with Gmail tools
web/src/lib/auth0.ts	Auth0 configuration

---

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

---

License

MIT