An always-on IRC bouncer with a REST-first API and a browser PWA that looks like irssi.
Live instance → irc.sindro.me — open it in any browser, or install it to a phone home screen (visitors need no password).
Two components in one monorepo:
- grappa — the server. A persistent bouncer that terminates IRC at the server boundary and exposes a REST API plus a multiplexed WebSocket (Phoenix Channels) for real-time push. One supervised OTP process per
(user, network)(Elixir/OTP + Phoenix). SASL bridging to upstream NickServ. Self-hostable on any VPS. - cicchetto — the client. A PWA that speaks pure REST and never parses IRC. Installable on a phone home screen, visually irssi, with mobile ergonomics added on top — not instead. SolidJS + TypeScript + Vite + Bun;
phoenix.jsfor the Channels client.
Modern IRC — always-on, usable from a phone — without making it not-IRC. For anyone who's been on IRC for a decade: it's irssi-in-tmux, reachable from a browser.
cicchetto on a phone — login (visitors need no password), then irssi-shape channels. Try it live at irc.sindro.me · grappa-irc on my phone →
grappa exposes one scrollback store through two facades:
- REST + WebSocket Channels — the primary surface and the design center. REST for resources, Channels for event push. IRC is fully terminated server-side; cicchetto is IRC-protocol-ignorant end to end.
- IRCv3 listener (Phase 6, planned) — an optional surface speaking
CAP LS+ SASL +CHATHISTORYto existing IRCv3 mobile clients (Goguma, Quassel…). A view over the same store — never a second source of truth.
Read state is server-owned: a per-(subject, network, channel) cursor (last_read_message_id), advanced by cic on focus-leave + browser-blur, exposed to the listener facade as +draft/read-marker MARKREAD lines.
There are good bouncers already. soju + gamja is the closest shape — a persistent Go bouncer + JS web client.
grappa diverges on one deliberate axis: the web client does not parse IRC. soju/gamja put IRC-framing-over-WebSocket on the wire and re-implement IRC protocol state in the browser. grappa terminates IRC at the server; the web client sees only typed JSON resources (channels, messages, members, networks) and an event stream. Scrollback pagination, channel modes, nick changes, join/part — everything arrives as JSON.
Two consequences:
- grappa works against vanilla ircds. Upstream IRCv3 extensions are opportunistic bonuses where the ircd has them, never requirements. No upstream
CHATHISTORYneeded — the bouncer owns scrollback. - grappa can still expose IRCv3 downstream (the second facade), so a mobile IRC client and cicchetto see the same store. It looks identical whichever you open.
flowchart LR
subgraph Clients["Clients"]
cicchetto["cicchetto PWA<br/>(irssi-shape UI)"]
mobileirc["Mobile IRCv3 client<br/>(Goguma / Quassel / …)<br/><em>Phase 6</em>"]
end
subgraph VPS["Self-hosted VPS"]
rest["REST + WebSocket Channels facade<br/>(Phoenix.Endpoint)"]
irclisten["IRCv3 listener facade<br/><em>Phase 6</em>"]
store[("shared scrollback store<br/>(sqlite via Ecto)")]
rest --- store
irclisten --- store
subgraph tasks["Grappa.Session GenServers (one per user×network, supervised)"]
t1["session A"]
t2["session B"]
t3["session C"]
end
rest --- tasks
irclisten --- tasks
end
subgraph Upstream["Upstream IRC"]
azzurra["irc.azzurra.chat"]
libera["irc.libera.chat"]
other["…any ircd<br/>(allowlisted)"]
end
cicchetto <-->|"HTTPS REST + WebSocket"| rest
mobileirc <-.->|"IRC + SASL + CHATHISTORY"| irclisten
t1 <-->|"IRC"| azzurra
t2 <-->|"IRC + SASL"| libera
t3 <-->|"IRC + SASL"| other
- Each
(user, network)has one persistent supervised GenServer (Grappa.Session) owning its upstream connection. A crash is isolated to that session; the supervisor restarts with fresh state and the sqlite scrollback survives. - Events stream into a per-
(network, channel)paginated scrollback (sqlite via Ecto), bounded by a retention policy. - REST is a thin read/write layer: writes (send, join, part) translate to upstream IRC commands; reads return typed JSON.
- New events push over Phoenix Channels — one socket per browser tab, many topic subscriptions per socket.
phoenix.jshandles reconnect + replay; clients catch up via paginated scrollback.
Supervision-tree ordering and the load-bearing invariants live in CLAUDE.md; the chronological decision log is docs/DESIGN_NOTES.md, with the closed months archived verbatim under docs/design_notes/.
- No IRC parsing in the web client. Ever. REST is cicchetto's contract; the browser never sees a raw
PRIVMSG. (Mobile clients on the optional listener parse IRC by definition — that's what they are.) - Upstream IRCv3 is opportunistic. grappa works against any ircd that speaks
CAP LS+ SASL. Downstream, the listener will speakCAP+ SASL +CHATHISTORYfully — that's the point of the second facade. - Scrollback is bouncer-owned. One store: paginated for REST,
CHATHISTORY-mapped for the listener. No dependency on upstreamCHATHISTORY. - Auth is NickServ, bridged via SASL; registration proxied through a dedicated endpoint.
- Self-hostable on any VPS, with an operator-configurable allowlist for upstream networks.
- Irssi-shape on desktop and mobile. Same visual grammar everywhere; mobile adds touch-ergonomic helpers, not a chat-app metaphor.
- Text only on the wire. Media (images, video, files) is uploaded to and hosted by grappa and shared on IRC as a plain link — the wire stays text, never inline media. cicchetto opens that link in an in-app image/video viewer (video is transcoded client-side before upload); scrollback never auto-renders media. Client-side voice I/O (read-aloud + dictate) is a separate, in-scope accessibility feature — see below.
- No push infrastructure. Use the browser PWA push API if present; otherwise no notifications. We don't run notification servers.
- Accessibility is a client concern. The server stays protocol-clean; screen-reader support, TTS, STT, and touch helpers live in cicchetto.
Optional, opt-in, per-channel — and never touches grappa or the IRC wire: TTS reads incoming messages aloud via the browser SpeechSynthesis API; STT composes by voice via SpeechRecognition; an optional Vosk/piper WASM drop-in gives an offline path. Server cost: zero. This unblocks the Android-IRC-with-voice ask that has no good native answer today.
grappa runs as a single container against a sqlite DB. There is no config file — every (user, network) binding lives in the DB and is read by Grappa.Bootstrap at boot. The operator interface is bin/grappa.
Two different programs answer to that name. Check which one you have before copying a command below. A source checkout carries the repo-root
bin/grappa, a docker-compose wrapper with the full verb table. A packaged release carries a much smaller one:mix releasemoves the generated boot script aside and installs the dispatcher frominfra/release/grappa.shin its place (theinstall_operator_cli/1step inmix.exs), so the ghcr.io image, the.deb, the AUR package and a bastille / systemd install all get the release CLI. A release ships no Mix, so everygrappa.*mix task — most of the verbs below — is simply not there, and asking for one gets you the boot script's ownERROR: Unknown command ….
Source checkout — run from the clone:
bin/grappa help # every verb (boot-time + live-state + debug)
bin/grappa help <verb> # per-verb usage
bin/grappa <verb> --help # the same per-verb usage, as a flag (or -h)
bin/grappa create-user ... # boot-time verb (mix task inside the container)
bin/grappa list-visitors # live-state verb (RPC into the running BEAM)
bin/grappa remote-shell # iex --remsh into the live nodeBoot-time verbs run as mix tasks in the container; live-state verbs attach to the running BEAM over Erlang distribution, so they introspect or mutate the actual supervised state (no second BEAM, no port collision).
Packaged release — three account verbs, plus whatever the release boot script already knew:
grappa help # the three verbs and their arguments
grappa create-user NAME [--admin] [--password PW]
grappa add-network USER NETWORK --server HOST:PORT --nick NICK --auth METHOD [...]
grappa remove-network USER NETWORK
grappa start | daemon | eval | rpc | remote | stop | pid | versionHow you reach that program depends on the substrate: sudo grappa … on a .deb / AUR box, docker exec -it grappa bin/grappa … against the container infra/docker/deploy.sh installs (named grappa unless GRAPPA_CONTAINER says otherwise), .../rel/grappa/bin/grappa … in a jail or under systemd. Anything outside the list above — list-visitors, add-server, set-network-caps, seed-scrollback, remote-shell … — has no verb here: live state is reachable through the release's own rpc / remote (grappa rpc 'Grappa.Operator.list_visitors_text!()' is the twin of bin/grappa list-visitors), and the per-network caps live in the admin console's Networks tab.
Developer scripts — gates, tests, shells — live in scripts/*.sh; how to run the test suites is documented in docs/TESTING.md; the full operator + deploy runbook is docs/OPERATIONS.md. The design of per-client derived outbound source addresses — written for the staff of networks a grappa instance connects to, rather than for developers — is docs/DERIVED_SOURCE_ADDRESSES.md (not yet implemented; #454, #543).
Self-hosting? INSTALL.md is the one-command Docker install — infra/docker/deploy.sh install generates every secret, builds, brings up the single grappa container, and waits until /healthz is green (update and stop are the sibling verbs; the old scripts/quickstart*.sh still work as shims). It also covers exposing it with TLS (Caddy / nginx / mkcert). The workflow below is the operator / hot-deploy path used for the production host.
Don't want to build? Every vX.Y.Z release also publishes a self-contained, multi-arch image (linux/amd64 + linux/arm64) to ghcr.io/vjt/grappa (:<tag> + :latest) — pull it instead of compiling from source. It bundles the ERTS + the cicchetto SPA and boots on its own. A one-liner brings it up on a host with only Docker + curl (no clone): curl -fsSL https://raw.githubusercontent.com/vjt/grappa-irc/main/infra/docker/get.sh | bash (append -s -- update to update an existing box), or copy compose.release.yaml if you would rather not pipe a script into a shell. Those are two different boxes, not two ways to drive one, so the compose path updates with its own pair — docker compose -f compose.release.yaml pull then docker compose -f compose.release.yaml up -d — and the -s -- update recipe above does not reach it (it looks for a box it never installed, and the install it then recommends builds a second, empty one; INSTALL.md has the untangling). Note it is a release image: it has no Phoenix.CodeReloader, so it is not the hot-edit dev environment — the Docker Compose stack above stays the development runtime, and updates on the image path are always cold (pull + recreate; the data volume survives). The same release also publishes ghcr.io/vjt/grappa-shottino on the same tag scheme and the same two arches — the shottino --ircd bridge, for reaching grappa from irssi/weechat/hexchat/goguma without a checkout to compile it in. See INSTALL.md and docs/OPERATIONS.md.
On Arch Linux? Two community-maintained AUR packages repackage the official release assets — grappa-bin (the server, cicchetto bundled) and shottino-bin (the terminal client and --ircd bridge): yay -S grappa-bin / yay -S shottino-bin, x86_64 only. They are maintained outside this repo (by vash909), not by the project, so they follow tagged releases at the maintainer's pace. They are the only AUR path today: the source recipe in infra/packaging/aur/ is not published there.
Packaging grappa yourself? PACKAGING.md is the contract the release pipeline keeps with downstream packagers: release asset names and URLs, package layout, runtime user and paths, configuration keys, supported platforms, the SHA256SUMS file, and how a change to any of it is announced.
An update that changes the toolchain is always cold. A release bundles its own Erlang runtime (ERTS) and its OTP and Elixir applications. The Arch package and the container image are built with whatever Erlang and Elixir their builder ships, and a jail bundles the toolchain of its latest pkg upgrade at its next mix release, so an update can move the toolchain with no change in this repo. The running node then refuses to load the new code hot: POST /admin/reload answers 409 stale_toolchain, naming what moved, with or without --force-hot, and the update takes a restart (issue 1112). The container image is always updated by recreating it anyway. A .deb, .rpm or Arch upgrade applies itself to a running service: it reloads the new code in place when it can and restarts the service when it cannot, a toolchain move included, so there is nothing to do after the upgrade (PACKAGING.md); on a jail or a systemd host, run the cold deploy.
When the database migrations run depends on the format (issue 1112). A hot deploy of a source checkout (jail, systemd host, Docker via scripts/deploy.sh) applies the pending migrations inside the reload. A cold deploy of one first checks the migrations while the running service still serves — a migration version claimed by two files refuses the deploy with nothing stopped — then stops the service, migrates, seeds the built-in themes and starts the new code, so old code never runs on the new schema; a migration that fails at that point leaves the service down, and the deploy says so. infra/docker/deploy.sh update on the published image (and get.sh -s -- update) keeps the same order: the new image checks the migrations while the old container serves, then the old container is removed, the database migrated and seeded, and the new container started. A container started from compose.release.yaml or a bare docker run migrates in its entrypoint at every boot, before the release starts. A .deb, .rpm or Arch package migrates in its install scripts when the service is not running; an upgrade of a running service migrates inside the reload, or, when it restarts, in the unit's ExecStartPre after the new release has checked its migrations — a refused check leaves the service running and fails the upgrade (PACKAGING.md).
The release serves its own frontend AND owns its security headers (#485). Phoenix's embedded web server publishes the built cicchetto bundle (CIC_DIST_ROOT, default runtime/cicchetto-dist), streams uploads, and emits the Content-Security-Policy + sibling security headers itself (GrappaWeb.Plugs.SecurityHeaders, the single source of truth — register_before_send so static hits and error pages carry them too). So a plain bin/grappa start on an HTTP port is a complete, header-hardened instance — no nginx in the box, no separate proxy required for the CSP that guards the localStorage bearer token. This is what makes a native (non-Docker) systemd / rc.d install stand up on its own; see docs/OPERATIONS.md for the release path. If you terminate TLS some other way (Caddy, a cloud LB, nginx), that front door is only for TLS — configure it as a dumb reverse proxy and let it forward grappa's headers untouched; it must not re-assert a CSP of its own (duplicate Content-Security-Policy headers are enforced as the intersection, a prod-only footgun). A plain-HTTP self-serve is fine for LAN / trusted-network use; a public deployment still needs TLS in front for the service worker + push (browsers gate those on a secure context).
git clone https://github.com/vjt/grappa-irc /srv/grappa && cd /srv/grappa
cp .env.example .env
# Three required secrets — paste each into .env.
# The first bin/grappa call builds the image (~5-10 min, one-time); later calls reuse it.
bin/grappa gen-encryption-key # GRAPPA_ENCRYPTION_KEY — encrypts upstream creds at rest (Cloak AES-GCM)
scripts/mix.sh phx.gen.secret # SECRET_KEY_BASE
scripts/mix.sh phx.gen.secret 32 # SECRET_SIGNING_SALT
scripts/deploy.sh # build the cic bundle + start the grappa containerBack up GRAPPA_ENCRYPTION_KEY separately — losing it means losing every stored upstream password. On a fresh DB no IRC sessions spawn until you bind a network; Phoenix answers /healthz web-only.
On later deploys scripts/deploy.sh auto-detects hot-safe changes (running-module swap, sessions preserved) vs cold-required ones (mix.lock / supervision tree / long-lived GenServer struct shape → image rebuild + force-recreate); --force-hot / --force-cold override the heuristic. For cic bundle-only changes use scripts/deploy-cic.sh (no server restart; connected browsers get a refresh banner).
From a source checkout — three verbs, all flags named:
bin/grappa create-user --name vjt --password "correct horse battery staple"
bin/grappa add-server --network azzurra --host irc.azzurra.chat --port 6697 --tls
bin/grappa bind-network --user vjt --network azzurra \
--nick vjt --password 'NICKSERV_PASS' --auth nickserv_identify \
--autojoin '#italia,#hacking'On a packaged release — the same thing in two verbs, because add-network creates the network and the server itself. create-user takes the name positionally and rejects a flag in that slot (create-user --name vjt errors with "create-user needs an account name, got the flag --name"):
grappa create-user vjt --password "correct horse battery staple"
grappa add-network vjt azzurra --server irc.azzurra.chat:6697 \
--nick vjt --password 'NICKSERV_PASS' --auth nickserv_identify \
--autojoin '#italia,#hacking'--auth:auto | sasl | server_pass | nickserv_identify | none, on both forms.- TLS: explicit
--tlson the checkout'sadd-server; onadd-networkit defaults to on for port 6697 and off otherwise, with--tls/--no-tlsto override. - Omit
--passwordon the releasecreate-userand it prompts on the terminal, so the secret stays out of shell history — pass-itif you are going throughdocker exec. --source <IPv4|IPv6>(on the checkout'sadd-server, or--sourceon the release'sadd-network) pins a per-network fallback outbound IP; a per-subject vhost pin/selection (admin panel → Vhosts tab, #228) overrides it. The auto-rotation pool is DB-driven (curatedin_poolvhosts), no env var.bin/grappa set-network-caps --network azzurra --max-visitor-sessions N --max-user-sessions Nsets independent visitor/user admission caps (omit for unlimited; visitor saturation never blocks operator login). It is a mix task, so a packaged release has no such verb — set the caps from the admin console's Networks tab instead.
Re-run scripts/deploy.sh and Bootstrap picks up the binding on boot — or attach via remote-shell and drive the spawn orchestrator directly for no downtime.
Operators get a multi-tab admin pane in cicchetto, gated on User.is_admin (REST /admin/* 403s for everyone else, enforced BEAM-side by the :admin_authn pipeline):
- Visitors — list visitor sessions; delete to free cap slots.
- Sessions — every live
Session.Server(user + visitor) with DBconnection_stateand live pid shown side by side; per-row disconnect (park) / terminate. - Networks — per-network cap editor + live counters, plus reset-circuit and force-reap.
PATCH /admin/networks/:slugflips the per-networkvisitor_enabledallowlist flag (visitors may attach only visitor-enabled networks, toggled live with no restart — the runtime replacement for the old compile-time visitor-network pin) ANDvisitor_autoconnect(the subset a visitor auto-connects at login: zero-friction multi-network from first login, no picker;visitor_enabled-but-not-autoconnect networks are offered on the home page for on-demand one-tap connect). - Events — real-time admin-event tail over the
grappa:admin:eventstopic; disk-backed (#215) so it survives a restart. - Session Log — the persisted IRC session-lifecycle log (#215): connect / register / NickServ
+r/ disconnect (with reason + duration + clean-vs-error) / reconnect-backoff, per(user|visitor, network)session. Every lifecycle transition also lands as a greppable, structured Logger line (session=<kind>:<uuid>:<network_id> event=disconnected reason=… duration_ms=… clean=…), so a 2amgrep <nick>of the server log finally explains a drop.
The admin UI's Promote button needs an existing admin, so bootstrap the first admin with --admin on create-user — in whichever of the two shapes your install has:
bin/grappa create-user --name vjt --password '…' --admin # source checkout
grappa create-user vjt --admin # packaged release (prompts for the password)After that, promote/demote everyone else from the Admin → Users tab. To promote an already-existing user from the shell, the expression is the same on both; only the way in differs — bin/grappa remote-shell --batch -e '<expr>' from a checkout, the release's own rpc on a packaged install:
grappa rpc 'Grappa.Accounts.get_user_by_name!("vjt") |> Grappa.Accounts.update_admin_flags(%{is_admin: true})'irssi-style theming as a first-class feature (Settings → themes):
- Gallery — browse the built-in curated schemes (solarized / gruvbox / nord / dracula / …, seeded by
mix grappa.seed_themes) plus anything users and visitors publish. Each card is a derived palette-swatch preview (no stored screenshot) and shows how many people currently have it in use. Tap a card to apply it live and reveal its actions (copy / edit / publish / delete); the active theme is server-owned (PUT /me/theme) so it follows you across devices. - Day / night pairing — flip "use a different theme at night" to pick a day theme + a night theme; cicchetto swaps the applied theme automatically on the OS
prefers-color-schemesignal — the same one the base light/dark look already follows (no time-of-day scheduler, no geolocation). A single pick still applies in both modes. The pair is server-owned, so it follows you across devices too. - Editor — a covering overlay with live preview: color pickers per token (base / mode / 16-slot nick palette), a curated font family, and a background image. Every change re-paints the app in real time; Save persists your own copy (create or edit), Cancel restores the pre-open theme. Editing always saves a copy — no copy-on-write, no shared state.
- Everyone's a producer — logged-in users AND anonymous visitors can create / copy / edit / publish / keep their own themes (visitors are capped at 50 owned themes; a visitor's published themes re-home to the house account when the visitor is reaped, so gallery contributions survive). A visitor-published theme is credited to a fixed guest label — never a nick.
- Share — publish your copy into the gallery for others to pick, or share a published entry by id (
/theme/<id>); the recipient copies it into their own account. Delete your copies freely (everyone else already has their own). Owners edit/delete their own; admins moderate any entry. - Fonts — a curated, self-hosted monospace set (JetBrains Mono, Fira Code, Source Code Pro, IBM Plex Mono, Cascadia Code, Hack). No runtime CDN/Google-Fonts fetch — the woff2 are served from our own origin (a remote webfont would be a per-render tracking beacon).
- Background — pick from a curated set of built-in backgrounds (system-owned, read-only, served as long-cached static assets) or upload your own image (or fetch by URL; re-encoded + re-hosted server-side — raster only, no SVG, EXIF stripped, SSRF-guarded). Either way it paints as a wallpaper behind the message list at a user-configurable opacity.
Security by construction: a theme is a closed set of tokens (palette + font-id + background), never raw CSS — the renderer only ever consumes the sanitized model, so a published theme can't smuggle CSS/JS or a tracking url().
REST carries resources (id-addressed); state changes push over Channels. The main families: POST /auth/login + /auth/logout; /me; /networks (CRUD, plus PATCH to flip connection_state between connected/parked — subject-agnostic: users AND visitors park/reconnect each network the same way; PATCH /networks/:id/identity sets per-network IRC nick/ident/realname, live-applied via an internal reconnect); POST /session/networks (a visitor one-tap-connects an additional visitor_enabled network — accretion); /networks/:id/channels (join / part / topic); /channels/:id/messages (paginated GET, POST to send); /channels/:id/members; /channels/:id/read-cursor; /networks/:id/archive; /settings; /uploads; /push/subscriptions; and WS /socket/websocket. The router (lib/grappa_web/router.ex) is the source of truth; a published OpenAPI schema is a pre-PUBLIC-OPEN deliverable.
Events are typed JSON (message, join, part, quit, nick, mode, topic, notice, window-state transitions, mentions bundle…) on user-rooted Channel topics:
| Topic | Scope |
|---|---|
grappa:user:{user} |
session-wide: network connect/disconnect, mentions bundle |
grappa:user:{user}/network:{slug} |
per-network: motd, server notices, nick changes |
grappa:user:{user}/network:{slug}/channel:{chan} |
per-channel: message, join/part, mode, topic, notice |
The client updates local state from these; it never reasons about IRC framing. Reconnect and replay-on-resubscribe are handled by phoenix.js.
Typed in cicchetto's compose box, parsed client-side, dispatched to REST or IRC. Unknown verbs surface as inline errors.
| Verb | Effect |
|---|---|
/me <text> |
CTCP ACTION in the active channel |
/join <#chan> |
Join a channel |
/part [#chan] [reason] |
Part the active or named channel |
/cycle [#chan] [message] |
Part then re-join the active or named channel (irssi's CYCLE). Channel-scoped only — the network bounce is /reconnect. A first word without a channel sigil is the message, not a target. No key slot, so a +k channel needs /part + /join #chan <key> |
/topic <text> · /topic -delete |
Set / clear the channel topic |
/nick <newnick> |
Change nick (users and visitors) |
/msg <nick> <text> |
Private message — opens a query window (channel-shaped targets are rejected). When the target is a network service (NickServ/ChanServ/SeenServ/…), its replies land in that open query window rather than the server tab (#400); unsolicited service traffic with no open query still lands in the server tab |
/query <nick> · /q <nick> |
Open a query window without sending |
/whois <nick> · /whowas <nick> |
WHOIS / WHOWAS; reply renders as an inline card |
/who <#chan-or-mask> · /names <#chan> |
WHO (channel or host/nick mask) / NAMES; WHO opens a modal, NAMES a members refresh |
/lusers |
Network-stats card pinned in the current window |
/op /deop /voice /devoice <nick>… |
Channel MODE ±o / ±v (chunked per ISUPPORT MODES=) |
/kick <nick> [reason] |
KICK on the active channel |
/kb <nick> [reason] · /kickban … |
Kickban: MODE +b *!*@host (offender's host verbatim, from the on-demand userhost lookup — no domain/octet wildcard; fail-closed if the host is unknown, "run /whois first") then KICK. Two frames, ban first (no rejoin window), both attempted |
/ban <nick-or-mask> · /unban <mask> |
MODE +b / -b (bare nick → mask via WHOIS cache) |
/banlist |
Open the ban-management modal: list the channel's +b masks (mask · set-by · time), add a ban via an easy mask builder (nick → nick!*@* / *!*@host / *!user@host, or paste a mask verbatim), remove a ban in one click. Op-gated as a hint (non-ops see a de-emphasised, still-clickable UI — the server's 482 is the real gate) |
/invite <nick> [#chan] |
INVITE (active channel by default) |
/umode <modes> |
Set own user modes (e.g. /umode +i) |
/umode |
With NO mode args: open the user-mode (umode) viewer/editor modal — your own umodes as retro toggle buttons; server/services-managed umodes (o/r/a/A/S) shown read-only. Also reachable via /mode <yournick> or by tapping the umode indicator on the network-header row |
/mode <#chan> <modes> [args] |
Apply channel MODE directly (e.g. /mode #c +k key) |
/mode [#chan] |
With NO mode args: open the mode viewer/editor modal (retro toggle buttons; chanop-gated editing; available modes from the network's ISUPPORT). Bare /mode targets the current channel; tapping the mode indicator next to the topic opens it too |
/ns <cmd> · /cs /ms /os /hs /rs <cmd> |
Send a command to a network service (NickServ / ChanServ / MemoServ / OperServ / HelpServ / RootServ); the reply shows inline in the server window |
/ns · /cs /ms … (bare) |
With NO args: open the dedicated services console modal (titled by the service) and fire help — the service's NOTICEs mirror into the modal (nick stripped, service in the title) with a > command prompt, instead of flooding the server window. The notices also stay in the server window (mirror, not move). Display-only: the modal never drives an auth action off notice content (the source nick is spoofable) |
/away [reason] |
Set away; bare /away clears explicit away |
/notify <nick>… · /watch <nick>… |
Watch nicks for presence (online/offline dots + toasts); bare opens the watch lists settings section |
/hilight <pattern> · /dehilight <pattern> |
Add / remove a highlight keyword (alias /highlight); bare opens the watch lists settings section |
/alias <name> <expansion> · /unalias <name> |
Define / remove your own slash-command alias (/alias wii whois $1 $1 → /wii foo runs /whois foo foo). $1..$9 positional, $N- the Nth arg and everything after it (/alias k kick $1 $2-), $* all args; with no placeholder the rest is appended. Server-synced per user; builtins can't be shadowed. Bare /alias opens the aliases settings section, where existing aliases are also editable in place (rename + change expansion) |
/credits |
Roll the end titles — the same modal as the credits entry at the bottom of the settings drawer, one verb deep instead of three taps |
/connect <network> |
Unpark + respawn a network |
/disconnect [network] [reason] |
Park one network (persists across reboots until /connect) |
/reconnect [network] [reason] |
Bounce one network — park, then unpark, in that order (irssi's RECONNECT). The one-command form of /disconnect + /connect, and the way to re-roll a vhost (the source address is picked per connect). Bare form targets the active window's network; the reason travels as the upstream QUIT |
/quit [reason] |
Park all networks, QUIT upstream, log out |
Per-window UI behavior — channel header, query/DM focus rule, archive section, the server-owned window-state machine, mobile layout, scrollback polish, the mention-aware scroll-to-bottom badge (jump to the next unseen mention below), mentions-while-away, auto-away, image upload, multi-line paste flood guard (a confirm dialog before pasting >3 lines, since each line sends as its own message) — is documented in docs/DESIGN_NOTES.md. cic mirrors server state; it never originates window state client-side.
In scope: text chat on IRC (channels, queries, notices, CTCP ACTION); multi-network per user AND per visitor (visitors auto-connect the admin-flagged set at login + one-tap-connect more from the home page, park/reconnect each network independently, persistent across reboot); persistent paginated scrollback; NickServ auth bridging (including a guided in-app "📝 Register nick" wizard that walks non-technical users through NickServ registration — Azzurra networks, via the emailed confirmation code — and auto-saves the password so the nick auto-identifies thereafter); a per-network on-connect perform list (raw IRC commands run server-side automatically at every (re)connect, at 001 before channels are joined — auto-identify, /oper, +x, auto-rejoin — edited in a settings panel, with $nickserv_pass / $oper_pass variables so passwords stay out of the text and encrypted at rest, plus $nick for the configured nick so an identify still names the account when the session landed on an alt nick; NOT slash-commands or aliases); media sharing — images, video, and files uploaded to and hosted by grappa, surfaced on IRC as a plain link (📸/🎬/📄), opened in cicchetto's in-app image/video viewer, with client-side video transcode before upload; receiving a file a peer offers over DCC SEND (grappa connects OUT, holds the offer for the user's consent, spools the bytes into an authenticated DCC inbox — never the public upload route — and posts a 📥 link in the conversation the offer arrived in; it never listens, so passive/reverse DCC is refused); a PWA that works on phones without an app-store detour; self-hosting for individuals and small groups.
Out of scope: offering a file over DCC from grappa (DCC SEND outbound — the upload store already hands out an HTTPS URL, so a second transport for the same bytes buys nothing; grappa does RECEIVE an offered file, see In scope, and refuses passive/reverse DCC precisely so it never has to listen); real-time voice / video calls and audio messages; inline auto-rendering of media in scrollback (media is a click-to-view link, never an autoplay/preview card); hosted multi-tenant SaaS (self-hosted only); push notification servers (PWA push only if the browser provides it).
Pre-alpha, late stage. Phases 1–3 (server skeleton, multi-user auth, client skeleton) and most of Phase 4 (irssi-shape UI) have shipped and run in production — a FreeBSD bastille jail on m42, live at irc.sindro.me for it-opers people since 2026-05-27. Phase 5 hardening is in flight.
The road to PUBLIC OPEN (self-hostable by anyone, not just a single operator) is a sequence of clusters, each shipped to the live operator before the next begins:
- Voice TTS+STT — on-device Web Speech, per-channel toggle.
- UI polish — a real mobile-first pass (breakpoints beyond 768px, touch-target sizing, sidebar ergonomics, scroll behavior).
- PUBLIC OPEN — gated on Phase 5 hardening (TLS verification replacing
verify: :verify_none, scrollback eviction, NickServ REGISTER proxy), self-hoster docs, and a published OpenAPI schema.
Phase 6 (the IRCv3 listener facade — CHATHISTORY, server-time, batch, labeled-response, drop-in for Goguma/Quassel) is long-tail work beyond PUBLIC OPEN. The full backlog lives in GitHub issues; design decisions in docs/DESIGN_NOTES.md.
Read for behavior, not imported — grappa is greenfield: soju (the reference for correct bouncer behavior: SASL, scrollback, reconnect/backoff), gamja (web-login + PWA flows), The Lounge (canonical manifest + service-worker), IRCCloud (the mobile-IRC UX north star), ZNC (every bouncer exists in dialogue with it).
"Grappa" is Italian distillate — the direct homologue of Korean soju. "Cicchetto" is the small glass of wine served at a Venetian bàcaro, parallel to gamja. A deliberate riff on soju/gamja. It's also a tribute: Italian Grappa! has been the call-sign of the Italian Hackers' Embassy at European hacker camps since 2001. This repository isn't affiliated with the association that carries the name today; it borrows the reference in the spirit it was intended — Italian hackers showing up somewhere with a bottle.
grappa has a motive, not just an architecture. Three posts tell it:
- 2002 — Forking Bahamut for Azzurra IRC — a 21-year-old forking an IRC server to add IPv6 + SSL because the Italian network he'd fallen for needed it. Why IRC, and why Azzurra.
- 2002–2005 — Sux Services — writing SQL-backed IRC services from scratch in C, because the off-the-shelf ones weren't good enough. Same instinct grappa runs on: if the existing thing is almost right, write the thing.
- 2026 — Claude walks into #it-opers — twenty-four years later, the same crew on the same network in the same channel, with a Claude Code session bridged into IRC as
vjt-claude. The evening that surfaced "we should just do this."
The throughline: nostalgia, honestly admitted — Azzurra is still alive, preserved across network "earthquakes" by people who still want it there; the spirit carries on, and the network (not any single nick) is the persistence worth investing in. A preference for self-hosted chat that keeps working when this year's SaaS pivots or dies. And a preference for text only — no unfurls, no reactions on reactions, no presence surveillance. Just text, the thing the brain wants at 23:00 after a day on Teams. grappa isn't a product; it's a tool for people who still want IRC on a phone in 2026 and would rather self-host it than rent it.
MIT — see LICENSE.
vjt (Marcello Barnaba), who built bahamut-inet6 and suxserv for the Azzurra IRC network. grappa-irc is the 2026 attempt at making Azzurra — and any IRC network — liveable on a phone.



