Free and open source, MIT

Running inone command.

It asks for your Anthropic key once, then starts Switch, a Mattermost to try it in, Ferri and Desk in Docker, with a demo event already loaded. No Node, no Switch checkout.

Terminal

$ git clone https://github.com/RudraO2/Ferri.git
$ cd Ferri
$ ./ferri up

Terminal

git clone https://github.com/RudraO2/Ferri.git

cd Ferri

./ferri up

On Windows, the last command is .\ferri up in PowerShell, or ferri up in cmd.

Try before you install

Ferri is live for Lantern Build Night, a made-up event. Ask @ferri when does hacking start?, then something it can't know. Or look around a live Desk, read-only.

Discord Telegram Desk, read-only

Requirements

What you need.

Nothing else: no Node, no Switch checkout.

Docker
Docker Desktop on Windows and macOS, or Docker Engine with the compose plugin v2.20 or newer on Linux.
About 4 GB of free RAM
8 GB is comfortable.
About 8 GB of disk
The first run downloads about 3 GB.
An Anthropic API key
From console.anthropic.com, under API keys.

What ./ferri up does

Five steps, done for you.

1
Asks for your Anthropic key once
Then generates every other secret into .env.
2
Pulls the images
Or builds Ferri's image from the checkout if it cannot pull it. The first run takes several minutes.
3
Starts the stack and waits until it is healthy
Switch (core, dashboard, Postgres), Mattermost, Ferri's Postgres, Ferri and Desk.
4
Sets up Switch and a demo event
Registers Ferri in Switch, creates the rooms ferri-lab and ferri-crew, the test people meera, arjun (members) and priya (crew), and loads Lantern Labs and its event, Lantern Build Night.
5
Prints the addresses, the logins and three messages to try
Running it again changes nothing that is already set.

What you get

Four addresses on your own machine.

The passwords are printed by ./ferri up and kept in .env: MATTERMOST_USER_PASSWORD, MM_TEST_PASSWORD and GATEWAY_ADMIN_PASSWORD.

WhatAddressSign in

Mattermost
the chat to try Ferri in
http://localhost:8065
user and the printed password. meera, arjun and priya share a second printed password.
Desk
the organizers' dashboard
http://localhost:3100
[email protected] and the printed password
Ferri Pocket
the crew's phone app
http://localhost:3100/m
Same as Desk
Switch dashboard
Switch's own Gateway UI
http://localhost:3300
Same as Desk

Also running: the Switch API at localhost:8800, used by Ferri and the scripts, and Ferri's Postgres at localhost:5433.
Every port is bound to 127.0.0.1 only. To change one, set DESK_HOST_PORT, MATTERMOST_HOST_PORT, API_HOST_PORT, GATEWAY_HOST_PORT or FERRI_DB_HOST_PORT in .env, then ./ferri up.

Try it

Three messages in Mattermost.

Open http://localhost:8065, go to ferri-lab, and watch one unknown question go to the crew and come back.

1 ferri-lab
you @ferri when does hacking start?
Ferri answers with the time and a Source line.
2 ferri-lab
you @ferri can I bring my dog?
The demo knowledge doesn't cover it, so Ferri says it is checking with the crew, and a question card opens in ferri-crew.
3 ferri-crew
you, as crew A1 "Yes, dogs are welcome"
Or tap a button on the card. Ferri answers the asker in ferri-lab and remembers it, so the next person gets the answer at once.

Also try does anyone know the wifi password? in ferri-lab, with no mention. Ferri waits a short moment so a person can answer first, then answers with its source.

Connect your apps

One command per app.

Each command adds the platform's connection to Switch, which makes every group on it a Switch room. A value you leave out is read from .env, and it is safe to run again.

Make a bot with BotFather, turn Group Privacy off before adding it anywhere, then add it to the group.

Terminal

./ferri connect telegram --token <bot token>

Discord

Create an application, turn on the Server Members and Message Content intents, invite the bot, then post once in the channel to create the room.

Terminal

./ferri connect discord --token <bot token> --guild <server id>

Slack

Create the app from Switch's manifest (Socket Mode, no public URL), make an xapp- token with connections:write, install it and /invite it.

Terminal

./ferri connect slack --bot-token xoxb-... --app-token xapp-...

Through the whatsapp_web bridge we added to Switch, linked to your own number. It is already in the Switch image; only the sidecar is extra. In .env, add the profile and name the chats that become rooms:

COMPOSE_PROFILES=mattermost,whatsapp
FERRI_WHATSAPP_CHATS=me,Lantern Build Night

Then start the sidecar and pair. The command prints a pairing code: on the phone, WhatsApp, Linked devices, Link a device, Link with phone number instead. Leave out --code to get a QR code instead.

Terminal

./ferri up

./ferri whatsapp:pair --code <phone number>

Read whatsapp.md

Then, on any app

1Type !invite-agent @ferri in the chat. The space shows up in Desk under Discovered, switched off.
2Attach it to the event in Desk, or with ./ferri space attach <space> --mode auto. Use --crew for the room where cards land.

Name the platform bot after Switch, not after Ferri. Slack and Discord turn a typed @ferri into a mention of a bot whose name starts with “ferri”, and then the message never reaches Ferri.

Read platforms.md

Optional parts

Each one is off until you turn it on.

./ferri doctor shows which are on, off or broken, and the next step for each. After you edit .env, run docker compose restart ferri desk.

Shield
Blocks scam links and link floods, and redacts leaked keys, on every message.
$ ./ferri shield:connect
shield.md
Pocket push
The crew's phones buzz when a card needs them.
Keys are generated. Phones need HTTPS: set FERRI_PUBLIC_URL and run a tunnel.
pocket.md
Email
Partner outreach and guest emails through Resend.
Set RESEND_API_KEY and FERRI_EMAIL_FROM
$ ./ferri email:setup
email.md
Social
Posts on LinkedIn, X and Instagram through Buffer.
Set BUFFER_API_KEY, plus FERRI_MEDIA_URL and FERRI_MEDIA_SECRET for images
social.md
Builder
A coding agent Switch runs on your machine: the event site, posters, listings.
On the host, with Node 22 and Claude Code:
$ pnpm install
$ pnpm builder:setup
$ pnpm builder:controller
builder.md
Posters
Background art for the Builder's posters.
Set OPENAI_API_KEY
$ pnpm builder:setup
builder.md
Luma API
Lists events through Luma's API instead of the Builder's browser.
Set LUMA_API_KEY (Luma Plus only)
builder.md
Without Mattermost
On a small server that uses Telegram or Discord, remove mattermost from COMPOSE_PROFILES in .env.

Useful commands

Everything goes through ./ferri.

On Windows, use .\ferri in PowerShell or ferri in cmd.

Something off?

Run ./ferri doctor first. If Ferri does not answer at all, the Anthropic key is usually wrong or out of credit.

troubleshooting.md

./ferri upStart everything. The first run asks for the key and writes .env. Safe to run again.
./ferri downStop. Keeps your data.
./ferri resetStop and delete all data. Asks you to type yes. Keeps .env.
./ferri logs [service]Follow the logs: ferri, desk, switch, mattermost, ferri-setup, ...
./ferri psWhat is running.
./ferri doctorCheck the core of the stack and every optional part: on, off or broken, with the next step.
./ferri connect listList the platform connections in Switch.
./ferri space listSee the rooms Ferri is in.
./ferri space attach <space> --mode autoAttach a room to the event (or --crew for the crew room).
./ferri smokeAsk Ferri through Mattermost and check it answers with a source. CI runs this.
./ferri buildBuild Ferri's image from this checkout instead of pulling it.
./ferri pullPull the newest images.
./ferri <script> [args]Run any package.json script in the stack: kb list, kb ask "<question>", card:preview, ...

Hosting on a server

Our live demo runs exactly this way.

The same ./ferri up, on a small always-on Linux server with Docker and about 3 GB of free RAM, reached through a Cloudflare named tunnel. No ports are opened on the server, and Mattermost is off: your community uses Telegram, Discord or Slack.

Read hosting.md

1
Make a Cloudflare named tunnel
cloudflared tunnel create ferri
2
Clone the repo on the server and fill in .env
COMPOSE_FILE=compose.yml:infra/demo/compose.demo.yml
3
Start it
./ferri up
4
Connect your platform and attach its chats
./ferri space attach build-night --mode auto
5
Turn on Shield
./ferri shield:connect
6
Cap what strangers can spend with a Switch budget
"metric": "messages", "amount_limit": 300, "period_hours": 24
7
Check it
./ferri doctor

Cost

Free software. You pay only for your own model use.

Free and MIT

Ferri is MIT-licensed and runs on your own machine or server, next to your own Switch. Switch itself is licensed by SandboxAQ under its own terms.

Your own Anthropic usage

Your key, your bill. The quick jobs on every message (triage, care reading, sheets, translations) run on Claude Haiku 5.5. Answers and drafts default to Claude Sonnet 5.5; set FERRI_MODEL_MAIN=claude-haiku-5-5 to run them on Haiku too.

Caps you control

A Switch budget can stop Ferri for the day after a set number of messages, and the Builder has its own Switch budget. Also set a monthly spend limit on the Anthropic key.

Clone it. Run it. Ask it something.

CI boots the whole stack with ./ferri up on a clean runner and asks Ferri through Mattermost on every push to main. Your machine is next.

Ferri on GitHub Read the docs How it uses Switch

Running inone command.

Try before you install

What you need.

Five steps, done for you.

Four addresses on your own machine.

Three messages in Mattermost.

One command per app.

Telegram

Discord

Slack

WhatsApp

Then, on any app

Each one is off until you turn it on.

Shield

Pocket push

Email

Social

Builder

Posters

Luma API

Without Mattermost

Everything goes through ./ferri.

Something off?

Our live demo runs exactly this way.

Free software. You pay only for your own model use.

Free and MIT

Your own Anthropic usage

Caps you control

Clone it. Run it. Ask it something.