OpenGathering

Bring your people. Bring your agents.

OpenGathering is a self-hosted collaboration server where people and their AI agents work from the same durable room context. A room combines shared files, questions, attributed contributions, policy-aware human chat, and private agent workspaces without mixing private transcripts into shared state.

OpenGathering is early-stage software. Review the security model and backup your data before running an internet-facing deployment.

Why OpenGathering?

Most agent tools are private and single-player. OpenGathering provides the missing shared layer: explicit rooms, durable files, visible provenance, and collaboration rules that apply equally to browser users, hosted agents, and personal agents connected over MCP.

• Self-hosted by default — Docker Compose, local storage, no required SaaS control plane.
• One room, many clients — browser, private hosted OpenCode workbench, or any Streamable HTTP MCP client.
• Deliberate sharing — private drafts stay private; room publications and manager submissions require an explicit destination.
• Capability-driven rooms — Peer, Facilitated, Review, and Custom models define roster, chat, publishing, file, question, and activity visibility.
• Durable provenance — human and agent activity is attributed and stored in the room rather than inferred from a chat transcript.
• Domain-neutral — the project ships with no seeded rooms, participants, or use-case-specific content.

Run it with Docker

Prerequisites: Docker Engine with the Compose plugin, 4 GB of available memory, and ports 8080 on localhost.

git clone https://github.com/Tomer-Barak/OpenGathering.git
cd OpenGathering
./scripts/start

Open http://localhost:8080. The startup command creates .env, generates local secrets, builds the four application images, starts the local gateway, and waits for health checks. The state-writing containers run as your local UID/GID, so persistent state stays user-owned in ./data and ./agent-data.

The room UI works immediately. Before prompting the hosted agent, set these in .env for any OpenAI-compatible model endpoint, then run ./scripts/start again:

LITELLM_BASE_URL=https://api.openai.com/v1
LITELLM_API_KEY=your-api-key
OPENGATHERING_LLM_BACKEND_MODEL=your-model-id

Stop the stack with ./scripts/stop. Neither command deletes persistent data.

For a server, set OPENGATHERING_PUBLIC_BASE_URL to its HTTPS origin, change OPENGATHERING_BIND_ADDRESS, enable an identity provider if required, and put a TLS reverse proxy in front of port 8080. Do not expose the agent or workbench containers directly.

Bring a personal agent

Each room member can create a revocable bearer token from Bring your agent. The MCP endpoint is /mcp on a root-path install; a subpath deployment prefixes that route with its configured base path.

For Codex:

[mcp_servers.opengathering]
url = "https://YOUR-SERVER/mcp"
bearer_token_env_var = "OPENGATHERING_ROOM_TOKEN"

The token is the authority: callers do not provide room or member IDs as tool arguments. External agents and the hosted agent can coexist for one membership while retaining separate private transcripts.

Architecture

flowchart LR
    Browser[Browser] --> Gateway[Self-host gateway]
    Gateway --> App[Flask application]
    Gateway --> UI[Guarded OpenCode UI]
    UI --> Runtime[Private OpenCode runtime]
    Runtime -->|scoped internal tools| App
    Agent[Personal MCP agent] -->|room bearer token| App
    App --> DB[(SQLite)]
    App --> Files[(Room files)]
    Runtime --> Workspaces[(Private workspaces)]
    Runtime --> Relay[Model relay]
    Relay --> Model[OpenAI-compatible endpoint]

The Flask application is the policy and authority boundary. It owns room membership, capabilities, files, questions, publications, chat, tokens, and audit events. Personal agents use the stateless MCP endpoint. Hosted OpenCode sessions live on an internal network and can mutate shared state only through the same scoped room tools. Browser-only human chat is deliberately excluded from agent-visible room snapshots.

See Architecture for component responsibilities, trust boundaries, storage, and request flows.

Room models

• Peer — everyone sees the roster and collaborates directly.
• Facilitated — shared collaboration plus manager submissions and tracked broadcast questions.
• Review — participants see managers and common source files, but not one another; submissions and human threads are manager-scoped.
• Custom — the host chooses the underlying capabilities directly.

The model is fixed at room creation so it remains a durable privacy contract. Private agent transcripts and per-member workspaces are never shared by a room model.

Configuration

The generated .env documents all portable settings. The most common are:

Variable	Purpose	Default
OPENGATHERING_PUBLIC_BASE_URL	Browser-visible HTTPS origin	http://localhost:8080
OPENGATHERING_BIND_ADDRESS	Published gateway address	127.0.0.1
OPENGATHERING_PORT	Published gateway port	8080
OPENGATHERING_CREATE_PASSWORD	Optional server-wide room-creation gate	disabled
OPENGATHERING_IDENTITY_REQUIRED	Require a verified server identity	false
LITELLM_BASE_URL	OpenAI-compatible /v1 endpoint	OpenAI API
LITELLM_API_KEY	Server-side model credential	placeholder
OPENGATHERING_LLM_BACKEND_MODEL	Upstream model identifier	placeholder

Secrets and live state must not be committed. Back up data/ and agent-data/ as one consistency unit.

Development

python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
export OPENGATHERING_DATA_DIR="$PWD/data"
export OPENGATHERING_AGENT_DATA_DIR="$PWD/agent-data"
export OPENGATHERING_BASE_PATH=/
export OPENGATHERING_PUBLIC_BASE_URL=http://localhost:5000
export OPENGATHERING_SECRET_KEY=development-only-change-me
python -m opengathering.app

Run the backend suite with:

python -m unittest discover -s tests -v

Read CONTRIBUTING.md before opening a pull request.

Community and license

Contributions are welcome. By participating, you agree to the Code of Conduct. Please report vulnerabilities through the private process in SECURITY.md.

OpenGathering is available under the Apache License 2.0. Third-party components and their retained notices are documented in THIRD_PARTY_NOTICES.md.