Skip to content

README.md

Latest commit

 

History

History
220 lines (159 loc) · 7 KB

README.md

File metadata and controls

220 lines (159 loc) · 7 KB

ContinuOz Workspace

ContinuOz demonstrates multi-agent coordination for coding teams. Multiple AI agents collaborate in real-time — assigning tasks, producing artifacts, and handing off work — without stepping on each other.

ContinuOz Workspace is an open-source collaborative AI agent workspace built with Warp's Oz API. It provides a chat-based interface where you can create rooms, assign agents to them, and have those agents work together on tasks — communicating in real time via SSE (Server-Sent Events). Agents can @mention each other, create tasks on a Kanban board, produce artifacts (PRs, plans, documents), and send notifications to your inbox.

Key Concepts

  • Rooms — Chat channels where humans and agents collaborate on a topic.
  • Agents — Configurable AI agents with a system prompt, skills, MCP servers, and associated repo. Agents run via the Oz harness and report results back to the room.
  • Tasks — A per-room Kanban board (backlog → in progress → done) that agents can self-manage.
  • Artifacts — Documents, PRs, and plans generated by agents during their work.
  • Notifications — An inbox of alerts from agents (e.g. "PR ready for review").

Tech Stack

Prerequisites

  • Node.js ≥ 20
  • npm (ships with Node)
  • A Warp account with an API key (for running agents)
  • A database: Turso/libSQL (SQLite-compatible) or Postgres

Getting Started

1. Clone & install

git clone https://github.com/warpdotdev/oz-workspace.git
cd oz-workspace
npm install

2. Quick setup (recommended)

Run the setup script to install dependencies, generate secrets, and initialize the database:

./scripts/setup.sh

Then edit .env.local to add your Warp API key, environment ID, and callback URL.

Alternative: Manual setup

Copy the example env file and fill in your values:

cp .env.example .env.local

At minimum, you'll need:

# Database — local SQLite for development
TURSO_DATABASE_URL="file:./prisma/dev.db"
DATABASE_URL="file:./prisma/dev.db"

# Auth (generate with: openssl rand -base64 32)
AUTH_SECRET="<your-random-secret>"

# Warp API Key — create one in the Warp app under Settings > Platform
WARP_API_KEY="<your-warp-api-key>"

# Warp Environment ID — get from the Warp dashboard or CLI
WARP_ENVIRONMENT_ID="<your-environment-id>"

# Agent callback URL — agents need a publicly accessible URL to POST responses
# For local dev, use ngrok: ngrok http 3000, then paste the https URL here
AGENT_CALLBACK_URL="<your-ngrok-or-public-url>"

See .env.example for the full list of options.

3. Set up the database

Generate the Prisma client and push the schema:

# SQLite/libSQL
npx prisma generate
npx prisma db push

For Postgres (local or managed), start a database (Docker Compose example):

docker compose -f docker-compose.postgres.yml up -d

Set the database URL:

DATABASE_URL="postgresql://oz:oz@localhost:5432/oz_workspace?schema=public"

Then use the Postgres schema:

npx prisma generate --schema prisma/schema.postgres.prisma
npx prisma db push --schema prisma/schema.postgres.prisma

4. Run the development server

npm run dev

Open http://localhost:3000. You'll be redirected to the login page.

5. Create an account & seed data

  1. Sign up at /signup to create a user account.
  2. To populate the workspace with sample agents, rooms, messages, and tasks, send a POST request to the seed endpoint (you must be logged in):
curl -X POST http://localhost:3000/api/seed \
  -H "Cookie: <your-session-cookie>"

Or trigger it from the browser console / app UI if available.

Project Structure

app/
  (workspace)/       # Authenticated workspace pages
    home/            # Dashboard
    room/[roomId]/   # Chat room view
    agents/          # Agent listing & detail
    inbox/           # Notifications inbox
    settings/        # User settings
  api/               # API routes
    invoke/          # Dispatch an agent in a room
    events/          # SSE endpoint for real-time updates
    rooms/           # CRUD for rooms
    agents/          # CRUD for agents
    messages/        # Chat messages
    tasks/           # Task management
    notifications/   # Notification management
    seed/            # Seed sample data
    auth/            # NextAuth handlers
components/          # React components
hooks/               # Custom React hooks
lib/                 # Shared utilities (prisma client, auth, event broadcaster, etc.)
prisma/
  schema.prisma      # SQLite/libSQL schema
  schema.postgres.prisma  # Postgres schema

Scripts

Command Description
npm run dev Start the dev server
npm run build Generate Prisma client & build for production
npm run start Start the production server
npm run lint Run ESLint
npm run db:generate:postgres Generate Prisma client using the Postgres schema
npm run db:push:postgres Push Postgres schema to the database

GKE deployment (app only)

Use the helper script to build, push, update the secret, and apply manifests:

PROJECT_ID=your-project \
DATABASE_URL='postgresql://USER:PASSWORD@HOST:5432/oz_workspace?schema=public' \
AUTH_SECRET='...' WARP_API_KEY='...' WARP_ENVIRONMENT_ID='...' \
AGENT_CALLBACK_URL='https://your-domain.example.com' AGENT_API_KEY='...' \
./scripts/deploy.sh

You can also store env vars in a file and have the script source it:

ENV_FILE=.env.gcp ./scripts/deploy.sh

The script defaults to:

  • PRISMA_SCHEMA=prisma/schema.postgres.prisma
  • IMAGE_NAME=oz-workspace, IMAGE_TAG=latest
  • SECRET_NAME=oz-workspace-secrets
  • NAMESPACE=default

StatefulSet Postgres (quick testing)

For a quick in-cluster Postgres (not production), set POSTGRES_MODE=statefulset:

PROJECT_ID=your-project \
POSTGRES_MODE=statefulset \
AUTH_SECRET='...' WARP_API_KEY='...' WARP_ENVIRONMENT_ID='...' \
AGENT_CALLBACK_URL='https://your-domain.example.com' AGENT_API_KEY='...' \
./scripts/deploy.sh

The script will create a Postgres StatefulSet and set DATABASE_URL to:

postgresql://oz:oz@oz-postgres:5432/oz_workspace?schema=public

When you wire a managed Postgres instance, set DATABASE_URL and rerun the script. The Service is a LoadBalancer, so GKE will provision a public IP.

Contributing

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

License

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