Quickstart

This page walks you through a first deployment with one agent, Clara. You give her a research task, and she stops for your approval before writing a file.

Prerequisites

• Docker with Compose
• An API key for OpenRouter or DeepSeek

1. Clone and Configure

git clone https://github.com/joshunrau/collegium.git
cd collegium
cp .env.template .env

Open .env and set MATTERMOST_ADMIN_USERNAME and MATTERMOST_ADMIN_PASSWORD. These become the Mattermost administrator credentials you log in with. Set CALLBACK_TOKEN to a random secret (openssl rand -hex 32): it is what the Mattermost plugin presents when it forwards a command, and what signs each approval decision.

Set MATTERMOST_PUBLIC_URL to the address you will open Mattermost at, such as http://localhost:8065. It must match exactly: opened at any other address, including 127.0.0.1, new posts appear only after a reload.

Leave the remaining defaults.

The defaults start a Mattermost beside the app. To use one you already run, follow Use an Existing Mattermost instead.

2. Declare the Agent

Create config.json at the repository root:

{
  "$schema": "https://collegium.sh/config.schema.json",
  "agents": {
    "clara": {
      "expertise": "research, summaries, and follow-through",
      "systemPrompt": "You are Clara, a careful researcher. Verify claims against sources before repeating them, and save your findings as files.",
      "model": { "provider": "openrouter", "name": "anthropic/claude-sonnet-5" },
      "tools": ["web", "workspace", "memory"]
    }
  },
  "providers": {
    "openrouter": { "apiKey": "sk-or-..." }
  }
}

tools lists the toolsets Clara can use: the web browser, reading and writing files in her workspace, and memory.

3. Start the Stack

docker compose up

The first start takes a few minutes. The stack is ready when the system bot posts its boot notice in the team’s Town Square channel.

4. Log In and Send a Task

Open http://localhost:8065 and sign in with the admin credentials from .env. You land in Town Square, and Clara is in the member list.

Clara responds only when mentioned. Give her a task:

@clara Find the three headline features of the latest Mattermost release and save a short summary to mattermost-notes.md

5. Follow the Turn

Three things happen, in order.

A status post. Clara’s status post appears and updates in place as she works. Each line names a tool call and what it does, including every page she visits.

The approval prompt. When Clara tries to write the file, the turn blocks. The prompt shows the path and the entire file body, and her status post reads “waiting on a decision” until you answer. /collegium approvals lists every prompt still waiting in the channels you are in.

The result. Click Approve. The tool runs, the file lands in Clara’s workspace under ./state/app/workspaces/, and Clara posts that she is done.

Run the task again and click Deny with reason instead. Clara receives your reason as the tool result and continues with it.

To see every tool call from a turn with its full arguments and results, copy the link of a post from that turn and run /collegium trace {link} in the channel. Typing /collegium lists every command with its arguments.

Shutting Down

docker compose down

State persists under ./state: the Mattermost data, the conversation store, and Clara’s workspace. Starting again resumes the deployment.

Upgrading

A restart re-reads config.json but keeps the image it already has. To run a newer release, pull the image and recreate the container:

docker compose pull app
docker compose up -d app

If a tool or behavior from a recent release is missing, the running image predates it.

Next: Next Steps.