Skip to content
Roster Roster Roster Docs

Getting Started

Roster ships as a single deployable platform image and exposes four integration surfaces from the same runtime:

  • web platform
  • REST API
  • CLI access through MCP
  • MCP server for agent runtimes

For the fastest evaluation, start with Run locally with SQLite. You only need Docker, two stable generated secrets, and a one-time bootstrap administrator password. Add a model provider API key later, when you are ready to test Resolve—asking Roster which role or person should handle a request.

Choose your path

Section titled “Choose your path”
GoalRecommended path
Evaluate Roster on one computerStart one container with SQLite, then follow the guided evaluation.
Run a standalone production deploymentChoose SQLite for one Roster instance or Enterprise PostgreSQL for managed database operations.
Run multiple Roster instancesUse Enterprise PostgreSQL and complete the High Availability guide.
Upgrade an existing 1.0.x deploymentKeep the existing SQLite database and /data volume; Roster does not provide an automated SQLite-to-PostgreSQL migration.

Deployment prerequisites

Section titled “Deployment prerequisites”

For every production or externally reachable deployment, plan these inputs:

  • Docker or a container platform that can run the advantys/roster image
  • a public ROSTER_AUTH_URL before exposing Roster or connecting OAuth MCP clients
  • a generated ROSTER_AUTH_SECRET
  • a generated ROSTER_BOOTSTRAP_ADMIN_PASSWORD for the first start of a fresh production database
  • a generated ROSTER_PROVIDER_SECRET_ENCRYPTION_KEY

Then add the storage required by the selected deployment shape:

  • SQLite: one Roster instance and a durable block volume mounted at /data
  • Standalone PostgreSQL: an Enterprise license and a managed PostgreSQL 17 or 18 database; keep durable /data storage when local connector files or other runtime files must survive container replacement
  • High availability: an Enterprise license, PostgreSQL writer and read-only endpoints, two or more Roster instances, and shared S3 or SFTP storage for CSV connector files

When ROSTER_AUTH_URL is unset, Roster defaults to http://localhost:${PORT} for same-machine local tests. Do not rely on this default when testing integrations with authenticated MCP clients; set ROSTER_AUTH_URL to the URL that the MCP client can reach.

Production defaults

Section titled “Production defaults”

The production container stores SQLite data, worker journals, connector files, and runtime state under /data by default:

ROSTER_DATA_DIR=/data

When ROSTER_DATABASE_URL is unset, SQLite uses /data/roster.db. Enterprise deployments can set ROSTER_DATABASE_URL to a postgres:// or postgresql:// URL to use PostgreSQL. PostgreSQL database support is not available in Free or Pro.

The MCP endpoint accepts both API keys and OAuth tokens by default:

ROSTER_MCP_AUTH_MODE=api_key,oauth

Leave ROSTER_MCP_AUTH_MODE unset to use this default. Set oauth when only user-based OAuth MCP clients should connect, or api_key when only API-key automation should connect. Roster derives the MCP OAuth resource URI automatically as ${ROSTER_AUTH_URL}/mcp.

First production checklist

Section titled “First production checklist”
  • Choose and document the deployment shape before creating production data.
  • For SQLite, mount /data on durable block storage and run exactly one Roster instance. For PostgreSQL, complete the database-role and migration procedure.
  • Set ROSTER_AUTH_SECRET to a high-entropy secret.
  • Set ROSTER_BOOTSTRAP_ADMIN_PASSWORD to a unique strong password for the first production start, save it for first login, then remove it after the bootstrap administrator is confirmed.
  • Leave ROSTER_BOOTSTRAP_ADMIN_PASSWORD_CHANGE_MODE unset for the default recurring reminder, or set required when password rotation must block protected actions.
  • Set ROSTER_PROVIDER_SECRET_ENCRYPTION_KEY to a separate high-entropy secret.
  • Use the default api_key,oauth MCP auth mode for mixed API-key automation and OAuth MCP clients, or set a narrower explicit mode.
  • Configure identity providers for human login.
  • Create API keys with only the scopes each integration needs.

Next steps

Section titled “Next steps”
  • Use the Deployment Overview to launch a local Docker container and prepare production configuration.
  • Review Licensing to compare editions, limits, and Enterprise-only deployment features.
  • Choose Databases and Migrations before configuring production storage, migrations, or backups.
  • Use High Availability for multiple Roster instances behind a load balancer with PostgreSQL failover.
  • Use Hosting Platforms to plan hosting on AWS, Google Cloud, Azure, Fly.io, or Kubernetes.
  • Use Environment Variables for the complete public runtime and CLI variable reference.
  • Use Directory Connectors to connect enterprise directory data.
  • Use Authentication to configure login and API access.
  • Use MCP to expose Roster to agent runtimes.