# 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.

![OpenGathering home screen](docs/assets/opengathering-home.png)

## 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.

```bash
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:

```dotenv
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:

```toml
[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

```mermaid
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](docs/architecture.md) 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

```bash
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:

```bash
python -m unittest discover -s tests -v
```

Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.

## Community and license

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

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