How Capy works

In most apps, a message goes from you to a company's server, and the server sends it on. Capy has no such server. Your computer connects to the computers of the people in your room. The app makes no web requests, except one you control: your own device fetches a page to preview a link you type. A link you click in a message opens in your own web browser, as it would from any other app; Capy's windows don't load it.

To find each other, devices use a public phone book that nobody owns, called a distributed hash table (DHT). Every room has a topic. Devices that share it look it up, learn each other's addresses and connect. A technique called hole punching gets the connection through home routers and firewalls, and everything on the link is encrypted end to end.

Sometimes a direct link can't be made, for example between two strict mobile networks. Then Capy goes through a blind relay: a computer run by the Capy team that passes the encrypted bytes between the two devices. It can't read them, and it is only used when a direct link can't be made. Big files and a room's Files never take the relay: they wait for a direct link.

There is no sign-up, email or password. When you start, Capy makes 24 words. They are your identity. Capy keeps them on your device, in a file that only your user account can read, and doesn't send them anywhere.

From the words, Capy derives a Keet identity key. Each time the app runs, it also makes a fresh key for this device, and your identity vouches for it. The device key signs everything you write: messages, your profile and read receipts. Everyone else's app checks those signatures, so a message without your signature isn't shown as yours, and no server has to say who you are.

Type the same words on another computer and it finds your other devices by itself, and your rooms come over. Log out and the device forgets the words, and keeps your rooms, secure rooms aside, for when you type them again. To clear this computer's copy, Log out and erase, at the bottom of Settings → Privacy & security, removes everything Capy kept for the account here, while your rooms stay with the other people in them and on your other devices.

Each member's device keeps its own log and adds to it. Autobase merges all the logs into one order that every device agrees on, and a small database on top (HyperDB) turns it into messages, profiles and tasks. There is no central copy: the room is the sum of its members' copies.

You join with an invite, a code you paste or scan as a QR code. Your app sends a request, and the app of a member who is online checks the invite and lets you in. From then on the whole history replicates to you, because every member's device holds a copy.

No device trusts a record just because it arrived. Before one counts, each device checks its shape, its size, its signature and whether its author may do that, such as removing someone or renaming the room. A record that fails is skipped the same way everywhere.

The room also holds up against a member who tries to break it. Each device limits how much it takes live from any one person, in the room and in its calls, and from people the room never let in, so nobody can flood the others' apps. If a member sends far more than anyone does, or something that can't be read, Capy stops taking in what they send on that computer and goes on with everyone else's; the room says so above the composer, and its owner or an admin can remove them from there. And nobody can make your computer lose anything else: Delete for everyone clears only that message's own files, and Remove from Files takes a file out of the list without touching anyone else's copy.

A room lives on its members' devices. If all of them are offline, a device coming back has nobody to copy from. A blind peer fills that gap. It is a computer meant to stay online that keeps an encrypted copy of the room's data, chat files up to 25 MB included, and hands it to members when they come back. Bigger files and a room's Files are never given to it. It never has the key that opens any of it, hence blind.

Capy ships with one, run by the Capy team, and there is nothing to set up: every room is registered with it as it opens, except secure rooms, which never are. A blind peer holds signed blocks, so it can keep them or drop them, but it can't change them.

It also keeps the sealed copies of message keys that let a message open while its author is offline (more under storage).

Photos, videos and files go into a room from the attach button, by dropping them on the window or by pasting. Photos show in the conversation and open in a viewer that zooms with the wheel, a pinch or its buttons: zoom out, zoom in, back to fit and actual size. Videos and sounds play where they are, and any file can be saved. The previews of photos and videos are made on your computer.

Up to 25 MB, a file in the chat travels like the room's messages. It is encrypted with the room's key and comes from whoever has it. When two devices can't connect directly, it can go through the team's blind relay, which passes only encrypted bytes, and the team's blind peer keeps an encrypted copy, so a member who was offline still gets it when nobody else is online. Neither of them can open it. Video and voice messages are held to the same 25 MB.

Two kinds of file don't work that way. A file above 25 MB is a big file, and every file in a room's Files follows the same rule as a big file: they go only on direct links, never through the team's helpers. So they come over only while you and someone who has the file are both online, at the same time. The table puts the three side by side.

A file coming in says how it's going, from what your computer measures: how much of it came, its speed, about how long is left once the speed is steady, and from how many computers. When it can't come yet, it says why, such as “Waiting for Ana to be online” or “Waiting for the message's key”, and “Couldn't download” comes with Try again. A message's photos, files and voice and video messages download while the message is on your screen.

A file in the chat can be up to 10 GB. Above 25 MB it is a big file, and it never downloads by itself: its card shows its name, its size and Download. Before a download starts, Capy checks there is room for it on your disk. A big file has to be a file on your computer: one pasted from the clipboard can be 25 MB at most.

A big file goes only between two devices connected directly. It never goes through the team's blind relay, and the blind peer never keeps it. So it moves only while the person who sent it, or someone who has the whole file, is online and reachable directly. When nobody is, a download waits and the card says “Waiting for … to be online with you”, with the sender's name.

A download can be paused and resumed, keeping what already came, or cancelled, which clears what came. While it moves, and while you send one, the card shows how much is through, the speed and, once the speed is steady, about how long is left. A room's Files follow these same rules for every file, whatever its size: a file in them reaches you only while you and a member who has it are both online at the same time.

Besides what's sent in the chat, a room has a Files tab: a tree of folders and files that the people in the room keep together. Anyone in the room can upload a file or a whole folder with its subfolders, make folders, rename and move things, and put a new version of a file over the old one.

Each member's device writes what they add into a drive of its own for that room, a Hyperdrive. The room's log holds signed records that place each file in the shared tree: where it goes, its size, a fingerprint of its content, who added it and when. Every device checks those records before it shows them, as it does with messages.

Nothing in Files downloads by itself. A file or a folder comes when you press Download, with pause, resume and cancel, and only over direct links, whatever its size: the team's relay never carries these files and the blind peer never keeps them. So a file moves only while you and someone who has it are both online, at the same time: if the person who added it is offline and nobody else has it, it waits until you're both online. Uploads and downloads show how far they are, the speed and, once it's steady, about how long is left.

When you type a link in the composer, Capy makes a preview card: the page's title, a short description, the site's name and a small picture. To make it, your computer fetches that page. The card shows in the composer with an ×, so you can drop it before you send.

The preview then travels inside your signed message. The other people in the room never fetch anything: their devices don't contact the website, and everyone sees the same card, members who were offline when you sent it included.

This is the one time Capy fetches a web page, and it happens in the app's background process: the app's windows still make no web requests. Capy fetches only http and https addresses, never one on your own network or computer, checks that again at every redirect (three at most), and stops after 5 seconds, 512 KB of page or 2 MB of picture. The picture is made into a small image on your device.

Everything lives on the members' devices, in a folder the app keeps (a Corestore). Capy has no central database. Photos, videos and files sent in the chat go in cores of their own, encrypted with the room's key so that a blind peer can't read them. A room's Files go in each member's own drive, which the blind peer never gets.

Each message is sealed with a key of its own. That key is never in the room's log. It sits in a separate file on each device and travels only to members, over the room's encrypted connections.

So a message can open while its author is away, every device publishes a new prekey each day. The author seals each message's key to the other devices' prekeys, and blind peers keep those copies. Only the device that owns a prekey can open its copy.

A secure room is for 2 to 8 people. It has its own folder and its own store, shared with nothing else in the app, and it keeps nothing but the chat: no files, transcripts, minutes, notes or AI.

Its key is made on the owner's device and kept in one file on the device that only your user account can read, sealed with your system's keychain where there is one (the Keychain on a Mac, DPAPI on Windows, the secret service on Linux), so a copy of the file is no use outside your session. It stays there through quits and restarts. The room is erased for everyone when the call ends, so a call there is never started by someone alone: the call button and the lobby's Start call wait until another member is online, saying “Start the call when someone else is here”. Joining a call that is already on always works. If no call ends it, it is erased a day after it was made, a safety limit nobody sets: making a secure room asks only how many people it holds. Its owner can erase it any time, and logging out erases it on that device. Erasing purges every core of its store and removes the folder, key file included.

A secure room announces no topic, so it can't be found on the DHT. Members connect straight to each other by key. It is never on your account's list and never given to a blind peer. While one is open, Capy asks macOS and Windows to keep its windows out of screenshots, recordings and screen sharing, which some capture tools may not respect. Linux can't do that, and Capy says so. On a Mac, its folder is marked so Time Machine leaves it out of backups.

Your microphone is encoded as Opus audio and your camera as VP8 video. Both are cut into small packets and sent straight to the others in the call, over the same encrypted connections the room uses, as unordered messages that don't wait for one another.

A call takes up to 16 people at once, and a secure room's call the 2 to 8 it was made for; a room itself can have more members. Each device seats people in the order it saw them join the call, keeps a seat until its person leaves, and exchanges the call's audio and video only with the people it seated. When a call is full, Join says “This call is full · 16 of 16”, and someone who joined at the same moment as the last seat is told “The call filled up just before you” and can join when someone leaves.

A call adapts to the link as it goes. Video, from a camera or a shared screen, starts at about half its rate and climbs while the link stays good, and backs off when it turns poor or frames keep getting lost. The sound waits a little longer for voices that arrive late, and eases back when they don't. While a call struggles, the AI that only follows it on your computer (the live summary, suggestions and caption translation) waits, so the call gets the computer first.

The call's insights don't come from a server either. On your computer, a voice detector notices when you talk. Your device writes that, signed, into the room: in batches, every 5 seconds and when you leave. Every device then works out talk share and interruptions from the same records, so every screen shows the same numbers, also for someone who joined late.

The connection signal, the bars on the tiles and the card in the lobby and in the call's Insights, comes from what Capy really measures: the round trip, how long a small message takes to reach another device and come back, and loss, how many packets don't arrive. Every audio and video packet carries a number, so the device receiving them can tell which came, which were lost and which came late. A round trip on the network isn't the delay you hear in a call, so Capy doesn't show it as one: you see the bars, or Good, So-so or Poor with a plain line, such as “From a quick test, video may stutter. Voices should be fine.”

When someone else shares a screen or presents a PDF, it takes your stage, but nobody has to watch it: Minimize folds it into a chip in the call's header, with the page for a PDF, and Show brings it back. Minimize the same person a second time and what they share stays minimized for the rest of the call, which you can undo. On the canvas, Esc first stops following whoever leads it, then minimizes it too. Only your view changes: nothing about it is sent, and the person presenting isn't told.

Nobody hosts a call. Anyone in it can move the round along, mark a decision or edit the notes. The room's owner, or an admin, can mute or remove someone, and each app obeys only them.

Capy's AI is QVAC, Tether's on-device AI. You pick and download each model once in Settings → Notes & AI, and it comes over the peer-to-peer network, not from a website. Until you download one, those features stay off. The models then run in a second process on your computer.

Nobody transcribes you but you. With the transcript on, your computer turns your own voice into text with Whisper or Parakeet and signs each sentence into the room. The text is shared with the room: that is the transcript. The audio is not stored.

When a call is over for you, your computer does the rest by itself, if it has a minutes model: first your own minutes, then the decisions, tasks and unanswered questions it found, for you to add with a click, then chapters for the transcript. It never does this while you're in another call, and if Capy closed first, it does it the next time it opens, for calls of the last two days. Your minutes stay on your computer and show first in the call's notes. If the room has no minutes of that call yet, yours are shared with it, so someone with no model, or on an older Capy, still has some to read, and Capy shows whose they are. The minutes and the suggestions each have a switch in Settings → Notes & AI.

There is no update server. The Capy team publishes each version to the Pear network, and the app downloads it from other computers that already have it, the way a room replicates. Your app checks when it starts. When a new version turns up while it's open, Capy looks for it after a short random wait, a few minutes at most.

When the download is ready, a card in the sidebar offers Restart now. In a call it waits: the card offers to restart when the call ends, and restarts at once only if you pick Restart now anyway. A production release needs a quorum of the team's signing keys, so a single key can't push an update on its own.

On macOS and Linux, an update nobody restarts for installs itself. Once it has been ready for two hours of Capy running (time asleep doesn't count), Capy waits for a quiet moment: no call and none ringing, no secure room on screen, no file being sent or downloaded, nothing being recorded, and you away from the computer for three minutes or its window out of sight. Then the card counts down one minute, with Restart now and Not now. Not now puts it off for at least an hour, up to three times, and a call that starts stops the countdown. The next time Capy opens, it says it was updated while you were away. On Windows it never restarts by itself.

If a new version fails to start twice in a row, Capy puts the previous app back and doesn't try that version again until a newer one arrives. On a Mac outside Applications, Capy offers to move itself there so it can replace itself later.

Versions before 1.0.8 could wait up to an hour for that. Quitting and opening Capy again checks at once.

Capy runs as two parts on your computer: the window you see, and a background part that keeps your rooms and talks to other devices. An error no longer stops the background part: it's noted, and the rest goes on. If it stops anyway, Capy starts it again by itself, after 1, 5 and then 30 seconds, and the window says “Reconnecting…”, then “Capy reconnected”. After three tries in a row it stops and offers Restart.

The window looks after itself too. If it crashes, it loads again, up to three times in two minutes, and if it stops answering for 10 seconds, Capy asks whether to wait or load it again. A message Capy can't show reads “This message couldn't be shown” while the rest of the room draws as usual, and if your microphone, camera, screen share or sound stops in a call, Capy says so and how to start it again.

When the window loads again, what you were typing in a room comes back, and so does a message you sent while the background part was away, until the room shows it. In a secure room nothing is stored for that.

Errors are kept on your computer and go nowhere unless you send a report from Settings → Help & feedback, where you see exactly what goes first. In a report, each error says which version of Capy it happened in and the newest comes first, and the list on your computer starts over after an update. For a call that went badly, a report can also carry a second-by-second log of up to its last 15 minutes: whether the link was direct or through the relay, round trip, loss, jitter, sending rate, how busy the app was and which AI tasks were running, with no names, keys or addresses.