waggle-os/docs/guides/team-mode.md

# Team Mode

Waggle Team Mode lets multiple users share workspaces, assign tasks, see who is online, and govern agent capabilities through an admin dashboard. It runs as a separate server backed by PostgreSQL and Redis.

## Architecture

Team Mode adds a **team server** alongside the local Waggle server:

- **Local server** (localhost:3333) -- your personal agent, memory, and workspace management
- **Team server** (your-server:3334) -- shared workspaces, presence, tasks, capability governance

The desktop app connects to both. Local operations stay fast; team operations sync through the team server.

## Docker Setup

The simplest way to run the team server is with Docker Compose.

### Prerequisites

- Docker and Docker Compose installed
- An Anthropic (or other LLM) API key

### Start the Services

```bash
cd waggle-poc

# Set your API key
export ANTHROPIC_API_KEY=sk-ant-your-key-here

# Start PostgreSQL, Redis, and LiteLLM
docker compose up -d
```

This starts:
- **PostgreSQL** on port 5434 (user: `waggle`, password: `waggle_dev`, database: `waggle`)
- **Redis** on port 6381
- **LiteLLM** on port 4000 (model proxy)

### Start the Team Server

```bash
cd packages/server
DATABASE_URL=postgresql://waggle:waggle_dev@localhost:5434/waggle \
REDIS_URL=redis://localhost:6381 \
npx tsx src/index.ts
```

The team server starts on port 3334 by default.

## Cloud Deployment (Render)

For a hosted team server:

1. Create a new **Web Service** on Render from the waggle repository
2. Set the **Build Command**: `npm install && npm run build`
3. Set the **Start Command**: `cd packages/server && node dist/index.js`
4. Add environment variables:
   - `DATABASE_URL` -- your PostgreSQL connection string
   - `REDIS_URL` -- your Redis connection string
   - `CLERK_SECRET_KEY` -- for authentication (Clerk)
   - `CLERK_PUBLISHABLE_KEY` -- for client auth
5. Deploy

## Connecting to a Team Server

### From the Desktop App

1. Go to **Settings** > **Team**
2. Enter the server URL (e.g., `https://your-team.render.com`)
3. Enter your authentication token
4. Click **Connect**

Waggle validates the connection by hitting the team server's `/health` endpoint.

### From the API

```bash
curl -X POST http://localhost:3333/api/team/connect \
  -H "Content-Type: application/json" \
  -d '{"serverUrl": "https://your-team.render.com", "token": "your-auth-token"}'
```

## Shared Workspaces

Team workspaces are created on the team server and synced to each member's local Waggle instance.

### Creating a Team Workspace

1. Connect to a team server (see above)
2. Press **Ctrl+N** to create a new workspace
3. Enable the **Team** toggle
4. Select the team and your role
5. Click **Create**

### Memory Sync

Team workspaces sync memory frames between members:
- When one member saves a decision, it appears in everyone's workspace mind
- Personal mind remains private -- only workspace mind is shared
- Author attribution shows who contributed each memory

## Task Board

Each team workspace has a task board for lightweight project management.

### Creating Tasks

```bash
curl -X POST http://localhost:3333/api/workspaces/{id}/tasks \
  -H "Content-Type: application/json" \
  -d '{"title": "Review Q1 metrics", "assigneeName": "Alice"}'
```

Or ask the agent: "Create a task for Alice to review Q1 metrics."

### Task States

Tasks move through three states: `open` -> `in_progress` -> `done`.

### Filtering

```bash
# Get all open tasks
curl "http://localhost:3333/api/workspaces/{id}/tasks?status=open"
```

## WebSocket Presence

Team Mode uses WebSocket push with a 60-second polling fallback for presence:

- See who is online in a shared workspace
- See who is actively typing
- Get real-time notifications for task assignments and team messages

## Admin Dashboard

Team admins access the admin dashboard at the team server URL. It provides:

### Members Management
- View all team members and their roles (owner, admin, member, viewer)
- Invite new members
- Change roles

### Capability Governance

Two-layer governance model:

**Layer 1: Role Policies**
Define which capabilities each role can use. Example: viewers can only use read tools, members can use write tools, admins can use all tools.

**Layer 2: Per-Capability Overrides**
Fine-grained overrides for specific capabilities. Example: allow a specific member to use `send_email` even if their role policy doesn't include it.

### Approval Request Queue

When a member tries to use a capability they do not have:
1. The agent tool `request_team_capability` creates a request
2. The request appears in the admin queue
3. An admin approves or rejects it
4. The member is notified

### Waggle Dance Messages

View inter-agent communication in team workflows. The Waggle Dance protocol lets agents coordinate tasks, share findings, and report progress.

## Capability Governance API

```bash
# List role policies
curl http://localhost:3333/api/team/governance/policies

# Create a policy
curl -X POST http://localhost:3333/api/team/governance/policies \
  -H "Content-Type: application/json" \
  -d '{"role": "member", "capabilities": ["read_file", "search_files", "search_memory"]}'

# List pending capability requests
curl http://localhost:3333/api/team/governance/requests?status=pending

# Approve a request
curl -X PATCH http://localhost:3333/api/team/governance/requests/{id} \
  -H "Content-Type: application/json" \
  -d '{"decision": "approved"}'
```

## Disconnecting

```bash
curl -X POST http://localhost:3333/api/team/disconnect
```

This removes the team server configuration but preserves any local copies of team workspace data.

## Team Server Status

```bash
# Check connection status
curl http://localhost:3333/api/team/status
```

Returns the server URL, connection state, user ID, and display name.