Jicofo Conference Orchestrator: Setup, Bridges & Clustering

Overview

If you have ever hosted your own Jitsi Meet server, you have probably seen a service called Jicofo in your logs. Most people ignore it until something breaks. Then they learn quickly that the Jicofo conference orchestrator is the piece that decides who joins which room, which video bridge handles the media, and what happens when a bridge goes down.

This guide explains what Jicofo does, how it works with the other Jitsi parts, and how to scale it when one server is no longer enough. I have kept the language simple and added small config examples where they help. If you are planning a self-hosted deployment, this should save you some hours of guessing.

What Is Jicofo?

Jicofo stands for Jitsi Conference Focus. It is a server-side component of Jitsi Meet. When someone opens a meeting link, Jicofo is the service that creates and manages the conference behind the scenes.

Think of it as a meeting host who never appears on screen. It does not carry video or audio. It:

• Notices when the first person enters a room.
• Joins that room as a hidden participant.
• Sets up a session with each user.
• Picks a video bridge to handle the media.
• Cleans everything up when people leave.

The video and audio do not pass through Jicofo. They go through Jitsi Videobridge (JVB). Jicofo only tells everyone where to connect and how.

The Jicofo Conference Orchestrator in the Jitsi Meet Architecture

To understand Jicofo, you need to see the other parts of the Jitsi Meet architecture. A standard install has four main pieces:

Optional pieces include Jibri (recording and streaming) and Jigasi (phone and SIP calls). Jicofo also finds and assigns these when needed.

How a meeting starts, step by step

• A user opens a room link in the browser.
• The browser connects to Prosody and asks to join the room.
• Jicofo sees the request and creates the conference.
• Jicofo picks a healthy Videobridge from the list it knows about.
• Jicofo asks that bridge to set aside resources for the conference.
• Jicofo sends the browser the details it needs to connect to the bridge.
• The browser sends its media to the bridge, and the meeting starts.

When the second, third, and later users arrive, Jicofo repeats the process for each one. When the last person leaves, the conference is closed and the bridge frees its resources.

Why the Jicofo Conference Orchestrator Matters for Stability

A common mistake is to blame the video bridge for every problem. In practice, many problems come from the orchestration layer. Here are some examples:

• People join but can’t see each other. Jicofo may not have found any working bridge.
• The meeting stays on “Waiting for host.” Jicofo may not be connected to Prosody, or authentication is set up in a way that stops the room from starting.
• A bridge crashes and the call freezes. Jicofo has to notice and move users to another bridge.

So Jicofo is not just a helper. If it is down, new conferences cannot start at all. That is why understanding it early helps a lot.

How Jicofo Finds Video Bridges (The Brewery)

Jicofo does not have a fixed list of bridges written in a config file. Instead, it uses something called a brewery room.

A brewery is a special XMPP chat room. Each Videobridge joins it and sends regular status updates, including load, region, and whether it is healthy. Jicofo sits in the same room and reads those updates. So when you add a new bridge, you just point it to the brewery and Jicofo sees it within moments. When a bridge disappears, Jicofo notices that too.

In the Jicofo config file, this looks like:

jicofo {
  bridge {
    brewery-jid = "JvbBrewery@internal.auth.example.com"
  }
}

The same trick is used for Jibri and Jigasi, each with its own brewery room. It is simple, and it is the reason adding capacity in Jitsi is not painful.

Jicofo Bridge Selection Strategy: How It Picks a Bridge

When a new conference starts, Jicofo has to choose a bridge. This is controlled by the Jicofo bridge selection strategy. The most common options are:

Which one is used is a setting in your config:

jicofo {
  bridge {
    selection-strategy = "RegionBasedBridgeSelectionStrategy"
  }
}

Names and defaults can change between releases, so always check the docs for your version before changing them.

How Jicofo decides a bridge is “busy”

Each bridge reports a stress level. It is a number based on how much traffic the bridge is handling compared to what it can take. Jicofo prefers bridges with lower stress. You can also set a cap on how many participants one bridge should get:

jicofo {
  bridge {
    max-bridge-participants = 80
  }
}

This is a soft limit that helps Jicofo spread the load rather than stacking everyone onto one server.

What Happens When a Bridge Fails?

This is where Jicofo earns its keep. Jicofo keeps checking whether each bridge is alive and healthy. If a bridge stops responding, Jicofo marks it as unavailable, stops sending new conferences to it, and works to move the affected participants to another bridge.

Users may see a short freeze or a quick reconnect. But the meeting usually continues, which is far better than the whole call dropping. This only works if you have at least two bridges, so a single-bridge setup has no safety net.

Jicofo Clustering: What It Really Means

Here is something that confuses many people. You will see the term Jicofo clustering in forums, but Jicofo itself is not a cluster that shares one conference across several copies. One conference is handled by one Jicofo instance at a time.

In Jitsi, scaling happens in two layers.

Layer 1: Scale the bridges

This is the easiest and most common step. You keep one Prosody and one Jicofo, and you add more Videobridge servers. All bridges join the same brewery, and Jicofo spreads new conferences across them. This is what most teams should do first, and it takes you a long way.

Layer 2: Scale with shards

When a single Jicofo and Prosody pair becomes the limit, you build another full copy of the signaling stack. Each copy is called a shard. A shard usually contains:

• One Prosody server
• One Jicofo instance
• A set of Videobridges
• Its own Jitsi Meet web setup

A load balancer, commonly HAProxy, sits in front. The key rule is that everyone joining the same room must land on the same shard. That is normally done with room-name based routing. Because of that rule, a single conference never splits across two Jicofo instances.

Single Server vs Bridge Scaling vs Shards: A Quick Comparison

A good rule of thumb: start with the middle option. Move to shards only when you have actual proof that signaling is your limit, or when you need stronger uptime guarantees.

Jitsi Octo Cascading: One Meeting Across Several Bridges

There is one more scaling idea to know about. In the simple setup, all participants in a single conference share one bridge. That caps the size of one meeting to what a single bridge can take.

Octo (bridge cascading) lets several bridges work on the same conference. Bridges exchange media between each other, so users connect to a bridge close to them, and the bridges link up behind the scenes. This helps in two cases:

• A very large meeting that one bridge cannot carry.
• Users spread across the world, so each connects to a nearby bridge for better quality.

Jicofo decides how participants are placed across bridges, and that is where the region-based strategies come in. In the config, cascading is switched on like this:

jicofo {
  octo {
    enabled = true
  }
}

Bridges need matching settings, too, and they must be able to reach each other on the network. Test it carefully before using it in production.

Jicofo Configuration: The Settings Worth Knowing

The Jicofo configuration file lives at /etc/jitsi/jicofo/jicofo.conf on a standard Debian or Ubuntu install. It uses a format called HOCON, which looks a bit like JSON but is friendlier. Older setups may still use a file called sip-communicator.properties, so do not be surprised if you see both.

These are the parts I check first:

• XMPP connection. Make sure the domain, hostname, and password match what Prosody expects. A mismatch here is the top reason for “Jicofo won’t start.”
• Brewery JID. If this is wrong, Jicofo will not see any bridges.
• Selection strategy. Match it to your layout (single region or many).
• Authentication. If you require logins to start rooms, make sure guests can join the right domain.
• Health check. Jicofo has a small HTTP endpoint on port 8888 by default. A health check against /about/health lets you know if it is working. Use this with your monitoring tool.

Logs are usually in /var/log/jitsi/jicofo.log. When something breaks, start reading there.

Common Jicofo Problems and Simple Fixes

Problem: “Waiting for the host” never goes away. Check that Jicofo is running and connected to Prosody. Also confirm the authentication settings on the XMPP domains match.

Problem: Jicofo runs but no meeting starts. Most often, no bridge is visible. Check that the JVB service is running and that its brewery settings match Jicofo’s.

Problem: One bridge takes all the load. Review your selection strategy and the max participants setting. Also check that new bridges are actually joining the brewery.

Problem: Users in another country have poor quality. You may be using a single region. Add a bridge closer to them and use a region-aware strategy.

Problem: After an update, things stopped working. Jitsi has changed config formats across releases. Read the release notes and compare your file with the current default one.

Best Practices from Real-World Setups

These are habits that tend to save trouble, based on how self-hosted Jitsi usually behaves:

• Run at least two bridges as soon as the service matters to your business. Failover only works if there is somewhere to fail over to.
• Watch the bridge stress numbers, not just CPU. It gives an earlier warning.
• Keep versions matched. Jicofo, Prosody, and JVB packages should come from the same release line. Mixed versions cause odd errors.
• Test with a load tool before launch. Jitsi provides a load testing project called Jitsi Meet Torture. Use it to see when your setup starts to struggle.
• Do not reuse passwords or leave defaults. Each component has its own XMPP secrets. Set them properly.
• Monitor the health endpoint. A simple alert on /about/health catches most silent failures.
• Change one thing at a time. When you scale, add a bridge or a shard, test, and then move on. It makes problems much easier to trace.

Is Jicofo the Right Choice for You?

Jicofo is not something you pick on its own. It comes with Jitsi. So the real question is whether Jitsi fits your needs.

Jitsi with Jicofo makes sense if you:

• Want to control your own data and hosting.
• Need something open source with no per-user fee.
• Are comfortable running Linux servers, or have someone who is.

It may not fit if you want a fully managed service with no server work at all. In that case, a hosted meeting service, or Jitsi’s own hosted offering, may be simpler. Self-hosting gives you control, but you take on the updates, monitoring, and scaling.

Conclusion

The Jicofo conference orchestrator is the quiet coordinator inside every Jitsi Meet setup. It creates conferences, discovers bridges through the brewery room, chooses where each participant should connect, and reacts when a bridge fails. It does not carry media itself, and it does not cluster in the way many people expect.

Here are the main points to remember:

Jicofo manages the meeting. Videobridge carries the audio and video. Bridges announce themselves in a brewery room, and Jicofo reads it. The selection strategy decides how conferences are placed on bridges. Scale first by adding bridges, then by adding shards behind a load balancer. Octo cascading lets one meeting use several bridges. Health checks, matching versions, and at least two bridges prevent most outages.

If you run a Jitsi server today, open your jicofo.conf file this week and check three things: the brewery setting, the selection strategy, and your health monitoring. Then add a second bridge in a test environment and watch how Jicofo handles it. Ten minutes of testing now is much cheaper than fixing a live meeting later.