You run a few computers and you'd like to know what orchy is really doing on them, especially while you're asleep. Fair question. This book answers it one layer at a time, each built on the one before, with no hand-waving. Every claim is marked: built, still a design, or a known limit. Give it ten minutes or a whole afternoon. Either way you'll finish knowing what your orchy does, what it doesn't do yet, and where it can still let you down.
This book describes orchy as it is today. If something is built and we've checked that it works, it's labelled serving today (green). If it's an idea we haven't built, it's on the design table (amber). If orchy falls short somewhere, that's a known limit (red). We're Earnest Ventures, the company that makes orchy, and we don't want to sell you our plans as if they were finished. The book sticks to that rule, and a test in our code checks that it does.
Orchy is one idea, used everywhere: take the computers you already own and make them act like one computer. The rest of this book is what follows from that.
Right now your laptop, your home server and your rented cloud server (a VPS) are islands. Want to run something "in the cloud"? You rent a stranger's machine and hand over your data. Want to reach a machine at home from outside? You open a port on your router (a numbered door the internet can knock on) and hope nobody else finds it. Orchy skips both.
Orchy links your machines, one at a time, over a private encrypted network called the mesh. Then it gives them one shared set of records: which devices exist, where your apps should run, what your data is, and who's allowed to touch it. You type orchy up, and they start acting like one computer. That whole shared space has a name: your orchy.
Here's the awkward part about getting computers to work together: none of them can trust another one just because it says so. A device can't assume the box it's talking to is who it claims to be. It can't assume something was saved just because someone said "saved". So before orchy can do anything useful, it has to solve four problems, in this order:
Part 1 starts with a single machine, because everything hangs off that. Parts 6 and 7 finish the job: how a stranger's app is kept in its box, and how you look inside your own orchy.
Read it start to finish, or jump to the part you need. Long words get a plain explanation in brackets the first time they show up. The coloured boxes are labels you can trust: green is built, amber is a design, red is a known limit. If our marketing and the facts ever disagree, believe the red box.
Orchy uses plain words on screen. The middle column below shows the technical names, which you'll only meet when you ask a command for machine-readable output (the --json option) and in settings files.
The full list of plain words and their technical twins lives in the repository's terminology spec. It includes how we describe when a device is around: "always on", "part-time" and "whenever on". The docs, the console, the CLI and this site all follow it.
Storage circles (keeping a set of data across 3 to 5 devices, which uses less disk than plain copies) and solo survival (one device carrying on when it's lost touch with all the others). Parts 4 and 5 explain both. Both are still designs.
It all starts with one device. The mesh, the records and the copies come later. This part covers what a single machine does, and why it can wake a sleeping app in milliseconds.
Orchy is one program. It starts your apps and watches over them. It can do the same for a container image, which is an app packed up with everything it needs, in the format a tool called Docker made popular. Docker, and Kubernetes (the tool big companies use to run many containers), each need background services of their own. Orchy needs neither. The boxes that keep one app away from the rest (sandboxes) come from the core of the operating system, its kernel. The watching-over comes from orchy, and nothing else gets installed. On most systems you don't even need an administrator password.
When you run orchy up on a fresh machine, it does six things:
orchyd;The daemon does the dull, important work. It starts your apps, keeps them running, and restarts them if they crash. It also lets them stop. Picture a photo gallery you made for your family (a made-up example): it gets looked at on Sunday evenings and sits idle the rest of the week. If you've switched on sleep-when-idle for it, the daemon shuts it down when nobody's using it, so it uses no power. The front door stays awake. When a request comes in, the device starts the app in a few milliseconds, where the usual container setup would take seconds. That's what "sub-second wake" means.
Our site says "wake in under 30 ms". That's for an app that's already installed on the device and just needs starting. Your numbers will depend on your hardware. Run orchy info on a device to see what it really does.
How much should an app be boxed in? That depends on whose app it is. Orchy has four levels:
/dev/kvm, which is Linux's built-in support for virtual machines, and the microVM software installed. You choose it with orchy deploy --isolation max, and orchy only puts a sealed app on a device that says it can run one.One rule covers all four: fail closed. If orchy can't build the box you asked for, it refuses to start the app. On systems that aren't Linux, only raw is supported. We've tested the jailed level with programs that try to break out of it (Part 6).
A jailed app's private top-level folder is missing /lib, /etc and /dev, the places Linux keeps shared code, settings and access to hardware. So your app has to bring everything it needs: either all its code is built into the one file (statically linked), or it carries its own set of folders. If orchy can't put the box together, the app refuses to start, which is the safe outcome.
When you deploy, orchy reads your project, suggests memory and CPU limits, and bundles your app into one package. Before it unpacks anything, it checks the package's fingerprint (a SHA-256 digest) against the one in your orchy's records. Unpacking can't write files outside the app's own folder (the trick known as zip-slip is blocked). Files that would run with someone else's powers (setuid and setgid) are refused. And the app runs boxed in at the level you chose, with only the powers that level gives it.
If any of those checks fails, the deploy stops and tells you why.
One machine running apps is the easy bit. The hard bit is trusting a second one. This part covers how a new device proves who it is, how devices talk in private, and how traffic gets in and out when you haven't opened a single port.
A device proves who it is with cryptography, where a person would type a password. The first device creates a private certificate authority for your orchy. Think of it as the family's passport office. Each new device makes its own key pair: a private key it keeps secret and a matching public key it can show anyone. (It's an ECDSA P-256 key, made with the operating system's secure random numbers.) Then it gets a certificate from that office. From then on, two devices in the family can prove who they are to each other on every connection. There's no shared password anywhere on the mesh, so there's no password to steal.
The one thing outsiders see is the family's fingerprint (engineers call it the CA's SPKI digest), and it's built into your join code. Everything else rests on that fingerprint. A device that doesn't match it is a stranger, whatever it says about itself.
A join code is a bundle: a one-time code, the brain's network address (or the address it relays through), your orchy's ID, the CA fingerprint, and a check that catches typos and tampering. Once it's been used, it's dead. Here's what happens when a second machine joins:
$ orchy join orchy1_AgAE4WPWrAkVUteChY3…✓ joined your orchy "orchystra" · laptop-pro · linux/arm64
Every connection on the mesh uses TLS 1.3, the same encryption that puts the padlock in your browser. Here it's mutual, which means both sides show a certificate before a single byte moves. Every message is tied to the identity that was checked, so one device can't speak in another's name, and every decision records who made it. Both ends check the family certificate. A key that's been retired or revoked is turned away at the edge of the mesh before it can do anything.
App deployments, the stream of changes from a data disk to its copies, the chatter that lets devices know about each other, and instructions from the brain. All of it travels over the same checked connections.
Home networks have two problems. You often don't get a public address of your own, because your provider shares one between many homes (that's called CGNAT), and you can't, or shouldn't, open ports. Orchy has an answer for each:
1. The relay. Your brain doubles as a relay. A device stuck behind a home router can't be dialled from outside, so it dials out to the brain and stays connected. Join codes carry the relay's public address so new devices know where to call. Devices on the same local network find each other directly. Everywhere else, the relay is how one mesh can cover two homes and a coffee shop.
2. The front door. For visitors from the internet, your device opens a connection outwards, called a tunnel, to a company that passes visitors along it (Cloudflare Zero Trust, Tailscale and ngrok all offer one). Your router never has a port open for incoming traffic, because nothing comes in that way. That's the secret front door. It handles HTTPS (the padlock again), fetches the certificates for you from a free service (the standard for that is called ACME), and passes requests to your apps.
The devices can talk. Now for the hardest problem in this whole area: getting separate machines to agree on what's true. If you only read one part twice, make it this one.
Say your app saves something on this machine only, and then this machine dies. The data's gone, unless another machine really got that save too. So "trust me, I kept a copy" falls short. Orchy has to answer a harder question: did the other copies really get it? And it has to answer truthfully: yes, or the save stays unconfirmed.
A quorum is the smallest number of copies that have to say "got it" before a save counts as done. Orchy uses a strict majority of the copies you asked for. With the default of 2 copies, that's both of them: the device doing the writing and one spare. The save isn't confirmed until that many copies are safely on disk.
The fabric store is the shared library where every record is kept. Everything in it has a fingerprint worked out from its bytes, and the fingerprint is checked again every time something is read or copied to another device. If it doesn't match, that's serious. The item is set aside (quarantined) and never handed out.
The store is divided into named sections called buckets, and they come in two sorts. System buckets (system:events, system:sessions, system:trust and friends) are for orchy's own use. Application buckets are for your apps. The wall between them is real: your apps can't see, list or change the system buckets.
Anything worth knowing about gets written in a journal: a device joined, someone was given a role, an app was placed on a device, a save reached its quorum, a damaged file was quarantined. Each entry carries a trace ID, a tag shared by entries that belong to the same piece of work, so you can ask "what happened around that change?" and read it back as a story.
Why does that help when things break? Because when a device disappears and later comes back, the journal lets everyone get back in step without a fight. The shared history, in order, is the truth. The returning device replays it and catches up. Everything in Part 5 leans on this.
The journal is packed into blocks you can search, and kept for 30 days by default. App logs roll over at 16 MiB each. There's no separate, hidden metrics system. The record is the monitoring, which is why Part 7 can simply say "ask the record".
| State | What it means | You see... |
|---|---|---|
| local-only | Your orchy is one device, so "copies" means one. There's nobody else to copy to. | A friendly notice: "1 copy — add a device to reach 2". |
| degraded | Orchy tried to make the copies, but too few confirmed in time. | An error. The save isn't confirmed, and it's up to the app what to do next. |
| quorum-committed | Enough copies confirmed they're on disk. | Success. The save is safe. |
| deleted | The delete itself reached quorum (3.5 explains how). | The object is gone, and a returning device can't bring it back. |
| quarantined | A fingerprint didn't match when the item was read or copied. | A serious event. The item is never handed out. |
"My save failed" is annoying to see. But think about what the other choice is: orchy says "saved", the only device holding it goes to sleep, and the data's gone for good. A refused save is one you can try again. A system that won't lie to you is one you can trust, and that's worth more than a friendlier message.
Deleting is risky when devices can disagree. A deleted file can come back from the dead, copied in from a device that never heard it was deleted. So orchy writes a small permanent note, called a tombstone, that says "this object, with this fingerprint, is deleted". The tombstone has to reach quorum before the delete is confirmed. If an old copy turns up later from a device that missed the news, the tombstone wins. Deleted stays deleted. The one exception is the journal: a journal page can't be deleted until it's been packed into its block. That protects your history.
| Devices | Your baseline | Writes need | Device loss survival |
|---|---|---|---|
| 1 | Everything is local-only: one copy, no redundancy. | This device online. | None. One machine is the whole thing. |
| 2 | Two copies, both must confirm. | Both devices online. | Either device can die and you lose no data. |
| 3+ | You can ask for more copies. The quorum is a strict majority. | A majority of the copies. | Survives losing devices. Because the majority rules, a network split can't leave two halves each thinking it's in charge (split brain). |
Imagine 19 of your 20 machines vanish at once. A system that only works by majority vote would freeze completely: no majority, so nothing runs, not even on the one machine still standing. Orchy's planned answer is solo survival: every device keeps a small, complete copy of the orchy's outline and records on its own disk, so the last one standing can keep going. It's a design. Part 5 says exactly what's true today and what's still to build.
The quorum rules apply to storage too. But storage comes in two kinds, and mixing them up is the most common mistake people make with this book: a database and a file need different care.
Data disks (floating volumes) are for apps that keep a real database, such as SQLite or Postgres. The app sees an ordinary folder. Every time it asks the system to make a save permanent (programmers call that an fsync), the change is written to a log that reaches your other devices before the save returns. On top of that, the disk's files are copied into the fabric store every half minute. We call each of those copies a fold.
Files (objects and buckets) are for apps that keep whole files: uploads, snapshots, documents. They live in the fabric store (Part 3), they're checked against their fingerprints, and apps reach them through orchy's storage service. Deleting them works through tombstones.
Facts (engineers would say a key-value store, or KV) are small bits of shared state, like a setting several apps need to agree on. Apps that belong together can read and write them. Each fact keeps a history of its revisions, and an app can watch one for changes. Facts are built on the same checked store as everything else.
Only one device holds a data disk at any moment: the one running its app. When your app saves, this happens:
That's what stands behind "two copies": the device only says "saved" once it's true.
The classic disaster goes like this: two devices both think they own the disk, both write to it, and they wreck it between them. Orchy stops that with a lease and a fence. A lease is permission to write that runs out unless it's renewed. The fence is a number that only ever goes up. To write, a device has to hold the disk's current lease, and every write carries the fence number. If a device that lost the disk comes back, its number is out of date. Its writes are set aside, and it leaves the disk alone.
What really happens when the device holding your data dies? Let's say it's the home server and someone trips over the power cable (a made-up example). Step by step:
In our automated drill (four devices on one test machine, with timings sped up), the app and its disk are back about 9 seconds after we kill the device, with every confirmed save in place. The lease is timed from how long a message really takes to go there and back on your network, so most of those seconds go on noticing the loss and starting the app elsewhere. We call it "accelerated" because it's a drill on test hardware, so expect your own numbers to differ.
A data disk keeps the snapshots you ask for. You save the disk as it stands under a name (orchy tools disk snapshot), and later you can put the disk back to it (orchy tools disk restore). The app restarts on the snapshot. Whatever it wrote since is gone from the disk, and the snapshot itself is kept. A snapshot is a sealed copy of one of the disk's folds, so keeping one only costs you the pieces that later writes replace.
Plain copies get expensive when your devices are all different sizes. Your 32 GB laptop would have to hold everything twice. So data in active use starts as 2 copies, and data you rarely touch can be erasure coded: split into a few pieces (k) plus a few extra check pieces (m), so that any k of the k+m pieces can rebuild the original. It's a bit like a jigsaw with spare pieces. Storage can then take about half the room and still be recoverable.
This part works today. orchy storage archive splits an object and spreads the pieces across devices, reads rebuild it from the pieces that are left without you doing anything, and orchy storage restore brings back the full copy. What doesn't exist yet is a background job that archives old objects by itself. That's on the design table below.
Constellations, the "storage circle", go a step further. A set of data is given to a fixed group of 3 to 5 devices, mixing your always-on, part-time and whenever-on hardware. That grouping is still a design.
Anyone can say "it's resilient". Showing your working is harder. This part is the working: a table of failures, what happens when things come back, and two limits we'd rather you heard from us: the single brain, and solo survival that isn't built yet.
| Failure | What happens | Survives? |
|---|---|---|
| App crashes | Orchy restarts it, and a health check decides when it's ready again. | Yes. Same device, the app recovers, no data lost. |
| Device goes offline | Its apps stop and can be started on other devices. | Yes. Apps move, and reads carry on from the other copies. |
| The device holding a data disk dies | The app and its disk come up on another device (Part 4.4). | Yes. Every confirmed save is there, and the old device leaves the disk alone when it comes back. |
| Temporary partition | The side with the majority keeps going. The other side is read-only or paused. | Yes. Thanks to fencing, nobody on the smaller side can write, so there's no split brain. |
| All devices but one are lost | Today the survivor keeps its own apps running, but the brain has probably gone too. | Not fully. Solo survival is a design; see 5.4. |
When a device comes back after being away, nobody takes its word for anything. It replays the shared journal (the record from Part 3, earning its keep), fetches what it missed from the buckets, and rejoins as a spare or a peer. It can't jump ahead of the others. The same fence that keeps a returning disk-holder in line does the job here.
About to take a machine down for a while? orchy device drain moves its work elsewhere first, in an orderly way, and lets your orchy adjust. orchy device boot is the blunt option, for a machine that won't come back. Both rest on Part 4: with fences and copies in place, you can move work around without your visitors noticing.
A new orchy starts with one brain. While it's the only one, deciding where apps run, keeping the records and moving apps off dead devices all depend on it. Give another device a share of the key that signs every device's identity (that makes it a co-brain, orchy brain add) and the brains can elect a new leader when one is lost: the most up-to-date device wins, and a majority has to agree. Re-election is built, and an automated drill exercises it. We haven't yet run it for a long stretch on real hardware. If the only brain dies at the same moment as the device holding a data disk, your orchy can't fix itself until you rebuild the brain.
For the day 19 of 20 devices vanish, the design is this: every device keeps its own complete copy of the small outline of your orchy on its own disk, so a survivor can rebuild your orchy's identity and settings. That's "solo survival" in the spec. It's a real design that we've yet to ship. In today's orchy, if you lose the brain while other devices survive, you recover by inviting them again.
Every number in this part says how we got it. Tier A: checks that run automatically on every build. Tier B: sped-up drills in our test pipeline, with a real kill and real timers (that's where the roughly 9 seconds comes from). The long-running evidence is the owner's own orchy, which has run for weeks on real hardware. We never pass off a simulated number as a measured one, and our own docs hold to the same labels this book uses.
The last new layer is security: who can do what inside your orchy, how far a stranger's code can reach, and how passwords and keys stay out of sight.
When a device joins it gets a role, and each role comes with a list of things it's allowed to do. The owner can do everything. A trusted member (a teammate's machine, say) can deploy and manage apps but can't change the rules of your orchy. A third-party device gets a narrow view: it can read system state but not change it, and it can only write inside its own app's box. Every call that changes something is checked against that list before it runs. The list (the design docs call it a capability matrix) is enforced in code.
A reminder of the levels. raw is for the owner only. guarded gives an app its own view of users, processes, network and files. jailed is the strict one: no special powers, no way to gain any, a private root and tmp, and no network unless you allow it. sealed is built too: each copy of the app gets its own Firecracker microVM, with no network and no access to the host's files. And if orchy can't set up the level you asked for, the app stays stopped. That's what fail closed means.
Our sandbox tests run real probes on Linux that try forbidden things from inside a jailed app: read the daemon's secret file, reach services on the host, get at the host's files. If any of them gets out, the build fails. The probes also check the details that matter: a minimal environment, no special powers at all, programs started without a shell, and a private, empty root. That's why we can stand behind what we say about each level.
Secrets are encrypted on disk (with AES-256-GCM, a standard strong cipher) and kept where apps can't see them. When an app is deployed, orchy makes one or more short-lived keys just for that app and puts them in its environment. The app gets its own secrets and nothing more. It never sees a master key. Secret values are never logged. In the logs you'll see only a secret's name, and that's enforced at the point where logs are sent.
Everything that crosses the mesh uses TLS 1.3, with both sides checked. The front door handles public HTTPS at the tunnel provider's edge, with certificates fetched for you, so a private service is never left exposed without it. A revoked or expired certificate is refused at the edge of the mesh before it can do anything. And if a device loses its key? The owner can issue a one-time replacement that's good for 24 hours. The old key is retired for good, so the replacement is the only way back in.
A system that fixes itself still has to tell you what it did. This part covers how you find out what your orchy has been up to, and how you give it instructions.
The CLI is how you talk to your orchy. On the same machine, it connects through a control socket (a local file two programs can talk through) and proves itself with a local "knock": a secret file for that device, made fresh each time the daemon starts, readable only by you (permissions 0600). So you're never asked for a password, and no web page open in your browser can read it. From another machine you use an access key, which carries a role. Build systems and other outside runners can get an identity of their own, approved by you (through a certificate request), so they never have more power than they need.
There's no separate monitoring system running beside your orchy. The journal is the monitoring. Events carry trace IDs and timings, they flow into the store, and a query layer lets you search them like a database. Ask "what happened?" and the answer comes from the journal. That's why orchy explain shows you the events themselves and lets you see how it reached its answer.
Orchy updates itself. It checks the signature on every update and rolls it out a device at a time. orchy doctor is the check-up: it tests the same kernel features the jail relies on (the ones that limit and separate programs, called cgroups and namespaces), and whether the ports it needs are free, and tells you what would break before it breaks. A system can only fix itself if it can first tell what's wrong.
Green means it's serving today. Amber means it's a design we haven't shipped. Red is a limit you need to plan around.
| Claim | Status | Plain words |
|---|---|---|
| Two copies, quorum writes | Serving today | A save is only confirmed once enough copies really have it. |
| Data-disk failover | Serving today | Measured: about 9 s in a sped-up drill. Fenced, and no confirmed save is lost. |
| Fabric store & journal | Serving today | Everything is fingerprinted, a mismatch is quarantined, and the journal is the monitoring. |
| Facts + files gateways | Serving today | They work, and every call is checked against what the caller may do. System buckets stay off limits. |
| Events, explain, advise | Serving today | You can search the journal and have it explained to you. |
| Isolation floors | Serving today | raw, guarded and jailed are tested with kernel-level probes. sealed runs each app in its own microVM (needs KVM). |
| Secret front doors | Serving today | Tunnels, automatic HTTPS certificates, no open ports. |
| Container images | Partial | An image runs straight from a registry (a private one too, with a login kept in your secrets). It runs jailed and pinned to the exact version pulled, with CPU and memory limits, several ports, a list of outside addresses it may call, and a data disk that's snapshotted into your orchy. If the device is lost, the data disk comes back as of its last snapshot. Suites of several services aren't built yet. |
| Erasure cold tier | Partial | Archive and restore work. Nothing archives old data automatically yet. |
| Storage circles | Design | Still a plan. |
| Solo survival | Design | Still a plan. |
| Brain re-election | Serving today (drilled) | Co-brains elect a new leader. Shown in automated drills; a long run on real hardware is still to come. One brain alone is still a single point of failure. |
First: orchy tells you when something isn't safe. A save that missed its quorum always shows up as an error. Second: anything amber in this book is still a design, and we're happy to talk it through with you.
Does Orchy replace Kubernetes? On your own hardware, more or less. It's a way to not need Kubernetes. It's one program, and you don't install anything extra to run a container image either: orchy pulls the image and runs it itself.
Why 2 copies and not more? With 2 confirmed copies, any one device can die and you lose nothing, and saving stays strict. Ask for 3 or more and the quorum becomes a strict majority. That spreads your data over more devices, and costs you more disk.
What happens when the network splits? Leases, fences and the journal. Only the lease holder can write, the two sides can't both be in charge, and the record gets everyone back in step afterwards. That's this whole book in one sentence.
For engineers: the why (the architecture decisions) and the how (the engineering rules we hold ourselves to) are in the repository's docs/ folder. The storage spec is also where we spell out exactly what we promise about your data.