Full Multiplayer Mode

This guide covers running Agor in full multiplayer mode with RBAC (Role-Based Access Control) and Unix-level isolation for production shared environments.

Overview

Multiplayer Agor enables true collaboration on shared development environments:

• Shared development environments - Multiple users working on the same codebase with proper isolation
• True Unix isolation - Worktree-level permissions enforced at the filesystem level
• Real-time collaboration - See what teammates are working on, share terminals, pair program

Security Considerations

Running Agor in full multiplayer mode with Unix isolation grants the Agor daemon significant system privileges.

What the Daemon Can Do

• Create and manage Unix users and groups
• Impersonate managed users to run agent sessions
• Modify filesystem permissions on worktree directories
• Execute privileged commands via sudo

Exposure Considerations

• API Keys - Users configure their own API keys (Anthropic, OpenAI, etc.) through the UI. These are stored in the Agor database and used by the daemon when running sessions on their behalf.
• Worktree Access - Users with worktree access can see files, terminal output, and session history for that worktree.
• Daemon Compromise - If the daemon is compromised, an attacker could potentially access all managed worktrees and user API keys.

Recommendations

1. VPN/Private Network - Run on a trusted network, not exposed to the public internet
2. Trusted Users Only - Only grant access to users you trust with shared infrastructure
3. API Key Rotation - Regularly rotate API keys, especially if users leave the team
4. Minimal Permissions - Use the RBAC system to grant minimal necessary permissions per worktree
5. Audit Logs - Enable comprehensive logging for security auditing

Setup Guide

Prerequisites

• Linux server with systemd
• PostgreSQL (recommended for production)
• sudo access for initial setup
• tmux (for multiplayer terminal sessions)

1. PostgreSQL Configuration

For production multiplayer deployments, use PostgreSQL instead of SQLite:

# ~/.agor/config.yaml
database:
  driver: postgres
  url: postgresql://agor:password@localhost:5432/agor

2. Volume Configuration

Configure persistent storage for worktrees and repositories:

# ~/.agor/config.yaml
storage:
  repos_dir: /var/lib/agor/repos
  worktrees_dir: /var/lib/agor/worktrees

3. Sudoers Configuration

The daemon needs sudo access for Unix user/group management. We provide a reference sudoers file with comprehensive documentation:

Download the sudoers template:

# Download the reference sudoers file
curl -O https://raw.githubusercontent.com/preset-io/agor/main/docker/sudoers/agor-daemon.sudoers
 
# IMPORTANT: Validate syntax before installing
sudo visudo -c -f ./agor-daemon.sudoers
 
# Install to sudoers.d (use your daemon username if not 'agor')
sudo install -m 0440 ./agor-daemon.sudoers /etc/sudoers.d/agor
 
# Verify the configuration
sudo -l -U agor

Or view the file directly: agor-daemon.sudoers on GitHub

# Core feature: User impersonation (run agents as the user who created the session)
# Only agor_users group members can be impersonated (prevents root escalation)
agor ALL=(%agor_users) NOPASSWD: ALL
 
# User management (create Unix users for Agor users)
agor ALL=(ALL) NOPASSWD: /usr/sbin/useradd *
agor ALL=(ALL) NOPASSWD: /usr/sbin/userdel *
agor ALL=(ALL) NOPASSWD: /usr/sbin/usermod *
 
# Group management (create agor_wt_* groups for worktree isolation)
agor ALL=(ALL) NOPASSWD: /usr/sbin/groupadd *
agor ALL=(ALL) NOPASSWD: /usr/sbin/groupdel *
agor ALL=(ALL) NOPASSWD: /usr/sbin/gpasswd *
 
# Filesystem operations (scoped to Agor paths only)
agor ALL=(ALL) NOPASSWD: /usr/bin/chown * /home/*/agor/*
agor ALL=(ALL) NOPASSWD: /usr/bin/chmod * /home/*/agor/*
# ... and more (see full file for complete scoped rules)
 
# Query commands (read-only, safe)
agor ALL=(ALL) NOPASSWD: /usr/bin/id *
agor ALL=(ALL) NOPASSWD: /usr/bin/getent *
agor ALL=(ALL) NOPASSWD: /usr/bin/test *

Security properties of this configuration:

1. Scoped impersonation - Only agor_users group members can be impersonated, preventing escalation to system users (root, postgres, etc.)
2. No TTY required - Defaults:agor !requiretty allows daemon operation without a terminal
3. Audit trail - All sudo operations logged to /var/log/auth.log
4. Defense in depth - App layer validates before sudo, OS layer enforces after

Customization:

• Replace agor with your daemon username if different (e.g., agorpg for PostgreSQL deployments)
• The file is well-commented; read through it before deploying

4. Enable RBAC

Enable the worktree RBAC feature flag:

# ~/.agor/config.yaml
execution:
  worktree_rbac: true
  unix_user_mode: full  # Options: simple, full

5. Observability Setup

For production deployments, configure logging and monitoring:

# ~/.agor/config.yaml
logging:
  level: info
  format: json
  file: /var/log/agor/daemon.log
 
metrics:
  enabled: true
  port: 9090  # Prometheus metrics endpoint

How It Works

User Management

When RBAC is enabled:

1. Each Agor user can have an associated Unix username
2. Users are added to the agor_users group for daemon impersonation
3. Agent sessions run as the user’s Unix account, not as the daemon

Worktree Isolation

Each worktree gets:

1. A dedicated Unix group (agor_wt_<short-id>)
2. Filesystem permissions based on RBAC settings
3. Owners with specific permission levels (view/prompt/all)

Permission Levels

Troubleshooting

Daemon Can’t Create Users

Check sudoers configuration:

sudo -l -U agor

Permission Denied on Worktree

Verify group membership:

id username
ls -la /path/to/worktree

Session Fails to Start

Check if user is in agor_users group:

getent group agor_users

Related Docs

• Architecture - System design overview
• Advanced Features - Multiplayer terminal sessions
• Concepts - Understanding worktrees and sessions