Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/flancian/garden/llms.txt

Use this file to discover all available pages before exploring further.

The Agora is not a single monolithic application. It is composed of three distinct, independently deployable repositories that together form a functioning Agora instance. Understanding how they fit together helps you decide which parts you need, how to run your own Agora, and where to contribute.

​
The three components

The Agora

Root configuration: gardens.yaml (the source list) and CONTRACT.md (the public commitment). No code — just config and contract.

Agora Server

Read-only Python/Flask web frontend. Renders the distributed graph as navigable HTML. This is what you use when you visit anagora.org.

Agora Bridge

Ingestion hub and write layer. Pulls content from Git, Federated Wiki, Mastodon, and Twitter. Also runs the platform bots.
You technically only need Agora Server to run an immutable, read-only Agora. Agora Bridge is required if you want live ingestion from external sources or bot integrations.

​
How data flows

[Contributor gardens]  [Social media]  [Federated wiki]
        |                   |                 |
        +-------------------+-----------------+
                            |
                    [Agora Bridge]
                    (pulls & ingests)
                            |
                    [gardens.yaml]
                    (source list in
                     Agora root repo)
                            |
                    [Agora Server]
                    (reads assembled
                     content at request time)
                            |
                    [anagora.org/<node>]
                    (served to the browser)
Agora Bridge runs in a loop, pulling from all sources listed in gardens.yaml. Agora Server reads the assembled content at request time and renders it. The Agora root repository is the shared source of truth for which gardens belong to the instance.

​
The Agora root repository

The root repository contains no running code. Its two key files are:
  • gardens.yaml — the list of all content sources for this Agora instance. Think of it as the filesystem table (fstab) for the Agora: each entry points to a garden (a Git repository, a wiki, or another source) that Agora Bridge will pull from.
  • CONTRACT.md — the system account’s public commitment to the ecosystem. If you modify the CONTRACT when running your own Agora, your instance may become incompatible with the Agora you forked from. Conflict resolution is part of Agora Protocol but is not yet fully specified.
git clone https://github.com/flancian/agora.git
Edit gardens.yaml to define which gardens your instance will serve.

​
Agora Server

Agora Server is a Python 3 / Flask application with a TypeScript frontend (no framework). It is the read-only web interface to the assembled graph — what you interact with when you browse anagora.org.
1

Clone and configure

git clone https://github.com/flancian/agora-server.git
If your repositories are not in the default /home/<user>/<repo> paths, edit app/config.py to point to the correct locations.
2

Set up the Python environment

cd agora-server
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
./setup.sh
3

Run in development or production

# Development
./run-dev.sh

# Production (served via UWSGI)
./run-prod.sh
4

Configure nginx and UWSGI (production)

Use agora-server.service as a systemd service template. Add an nginx virtual host and forward traffic via UWSGI:
location / {
    include uwsgi_params;
    uwsgi_pass unix:/tmp/agora-uwsgi.sock;
}
Add TLS with certbot:
certbot --nginx -d example.anagora.org

​
Agora Bridge

Agora Bridge is the write layer and integration hub. It is written in Python with YAML configuration, and also includes TypeScript components for certain integrations. It handles:
  • Git ingestion — the default input bridge; pulls from all sources in gardens.yaml on a loop
  • Mastodon integration — bot at @agora@botsin.space
  • Twitter/X integration — bot at @an_agora
  • Federated wiki ingestion
  • Output bridges — writes assembled content to a filesystem via git pull
Bridges are configured in YAML. The main configuration file is bridges.yaml, which can be passed to the service as a parameter. Each bridge is typed as input, output, or bidirectional (read/write/read-write).
1

Clone and set up

git clone https://github.com/flancian/agora-bridge.git
cd agora-bridge
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
./setup.sh
2

Run the bridge

# Run directly
./run-prod.sh

# Or as a systemd service
systemctl enable agora-bridge
systemctl start agora-bridge
3

Configure optional bots

See the bots/ directory and the Agora Bridge install docs for instructions on enabling the Mastodon and Twitter bots.
All three repositories must be cloned under the same user in a Unix-like system. The reference deployment at anagora.org runs on Debian GNU/Linux under a dedicated agora user. Docker support is not yet available.

​
Deployment summary

ComponentLanguageRoleRuns as
Agora root—Config only—
Agora ServerPython 3 / Flask + TypeScriptRead-only web frontendSystemd + UWSGI + nginx
Agora BridgePython + YAML + TypeScriptIngestion and botsSystemd loop

Build docs developers (and LLMs) love

Get started for freeTalk to us