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.

Agora Bridge is the write-side component of the Agora stack. While agora-server handles reading and rendering content, the bridge is responsible for pulling content in from external sources, running bots, and managing integrations with social platforms. Every garden that appears in your Agora gets there because the bridge fetched it.

​
How the bridge works

The bridge runs as a persistent service that reads a central configuration file (bridges.yaml) and executes fetch or sync tasks in a loop. Each task is called a bridge and has a direction:
TypeDirectionDescription
inputRead into the AgoraPulls content from an external source
outputWrite out of the AgoraPushes content to a target (e.g. filesystem)
bidirectionalBothReads and writes (e.g. a two-way sync)
The default input bridge is git — it clones or pulls a git repository containing a user’s garden. The default output bridge writes the assembled content to the local filesystem, where agora-server reads it.

​
Supported sources

As of 2022, the bridge supports ingesting content from:

Git

The primary source type. Clones or pulls any public git repository containing markdown or other supported garden formats.

Fedwiki

Pulls content from Federated Wiki instances into the Agora node graph.

Mastodon

Ingests toots and interactions from Mastodon accounts or feeds.

Twitter

Pulls tweets containing wikilinks and stores references to them in the Agora.

​
bridges.yaml

bridges.yaml is the main configuration file for the bridge service. You can pass it to the service as a command-line parameter. It defines all active bridges — which sources to pull from and what to do with the content. 
# bridges.yaml — example structure
bridges:
  - name: example-garden
    type: input
    source: git
    url: https://github.com/example/their-garden
    format: markdown
    target: /home/agora/agora/gardens/example

  - name: fedwiki-source
    type: input
    source: fedwiki
    url: http://example.fed.wiki
    target: /home/agora/agora/gardens/fedwiki-example
The bridge reads agora/gardens.yaml (your Agora’s source list) and bridges.yaml together. gardens.yaml declares what sources exist; bridges.yaml configures how the bridge interacts with them.

​
Per-user agora.yaml

Each user who participates in an Agora community can publish an agora.yaml file inside their digital garden. This file configures the Agora’s behaviour for that user — which actions to take, which outputs to enable, and how their content should be treated. 
# agora.yaml — example structure (published inside a user's garden repo)
user: flancian
sources:
  - url: https://github.com/flancian/garden
    format: markdown
settings:
  push_to_gitea: false
  consent_to_store_messages: false
Signing up to an Agora is as simple as publishing an agora.yaml in your garden and pointing an Agora Bridge instance (either your own or a community-run one) at your configuration file’s URL.

​
Signing up users to your Agora

When someone wants to join your Agora, the process is:
1

User publishes agora.yaml

The user adds an agora.yaml to their garden repository (or any publicly accessible URL) with their source information and any Agora action preferences.
2

Add their garden to gardens.yaml

Add the user’s repository URL to your Agora root’s gardens.yaml (or sources.yaml). This is the authoritative list of gardens your Agora includes.
3

Bridge picks it up

On its next run cycle, the bridge reads the updated gardens.yaml, fetches the new garden, and the content becomes available in agora-server.

​
Running the bridge

After setup (see Self-hosting guide), start the bridge with: 
./run-prod.sh
The bridge runs in a continuous loop, re-fetching all sources on each cycle. For production deployments, register it as a systemd service using the example unit file included in the repository.

​
Community and contributions

If you have questions about configuring the bridge, join the Agora Matrix room.
Developers can send a pull request to the reference Agora repository to add their garden directly. For the development discussion room, see the Agora development room.

Build docs developers (and LLMs) love

Get started for freeTalk to us