Skip to content
Get in touch

A machine is a table

Design notes on the machine package: one table per machine, a supervisor that reads it, a relay that passes proven calls only, a pulled store for builds, and one clock the machines agree on. What it depends on, what was measured, what it does not do.

By Bogdan Vladoiu, 2026-11-17

This is a design document for the machine package of the ComputeShack codebase, written when the work on it settled in November 2026. It records what the package is, which other packages it is built from, what was measured, and where it stops. The source is public: git clone https://computeshack.com/git/computeshack.git.

Scope

The package answers one question for the rest of the codebase: where does something run, and how is it reached. It covers a handful of machines owned by one person: a workstation, a small board that is the public door, and a laptop. It is not an orchestrator and does not try to be one.

Terms

Term Meaning
Machine One table and the daemons registered in it. Not a host, an operating system or a user. It has a chosen name, never the hostname.
Daemon A process that serves one or more interfaces on a local socket and has a row in its machine's table.
Table The record of a machine's daemons: name, where each answers, which interfaces it offers, the command that starts it, the build it runs.
Supervisor The one process the operating system keeps alive on a machine.
Relay The process through which daemons on different machines reach each other.
Set One numbered build of the binaries for a target, with a checksum sheet and a stamp.

Components

The table

A machine keeps one table. The table records facts and judges nothing; callers decide what a fact means. A daemon registers when it starts and is found by name from then on. A daemon that is asked for and does not answer is started from the command in its row. A daemon with no command that stays silent for three passes is removed.

The table is a key-value store over SQLite, from the store and sql packages. Its schema changes go through numbered migrations, and an upgraded database is required to be identical to a fresh one.

The daemon recipe

Every daemon starts the same way: it claims its name, serves a unix socket, registers, joins the relay and waits. The recipe is one function with defaulted arguments. What a daemon does with errors is configured once in its main, through the errors package; the recipe does not know about alerts or mail.

The supervisor

Every ten minutes, or when told, the supervisor walks the table and starts what should be running and is not. When a new set arrives it verifies the checksums, writes each binary under a new file so running daemons are untouched, and restarts only the daemons whose binary changed, the table daemon first.

The relay

Daemons on different machines reach each other through a relay. A caller proves that it holds the house secret before the relay passes anything; without proof the connection is closed. The secret is held by one daemon, from the crypto package, and is never written to disk on the door. A daemon can also declare which calls it accepts from the relay; the store, for example, serves other machines read-only.

The store

Builds are pulled, never pushed. A publish writes a set into the publishing machine's own store and tells the other stores. Each store pulls what is newer, in pieces of one megabyte through the fs package, and keeps the last three sets. A machine that was off when a set was published catches up by itself.

The clock

Machines do not trust each other's wall clocks. Each table serves a platform clock, from the time package: wall time plus a learned offset, never repeating and never going back. Every daemon takes its time from its machine's table.

When a machine announces itself to another it sends its own platform time, and the receiver stamps the arrival with its own. The difference is that machine's skew. The fleet's time is the local time corrected by the mean skew, with outliers dropped and the correction bounded.

This is agreement on time, not on state, and it is enough for what the machines need to agree on. Sets, pages and rows carry a stamp from that clock, and the newer stamp wins. Two machines that both changed something while apart do not need an election when they meet again: they compare stamps taken from a clock they already agree on. There is no leader to lose and no quorum to wait for.

Dependencies

Package What the machine package takes from it
time The platform clock and five named durations; every timeout and cadence in the package is one of them or a small multiple.
store, sql The table and its migrations.
socket, net Unix sockets on a machine, one framed connection between machines.
crypto The house secret and the proof a caller gives the relay.
fs Reading a file on another machine in pieces.
execution The three places work runs: processor, input and output, interface. Nothing else dispatches work.
errors, log One error channel and one log per process.
version The number of the set a machine runs.
tools Every interface of every daemon is also a tool an agent can call, on this machine or another.

Measurements

Taken on the three machines in November 2026. The full tables are in machine_benchmarks.md in the package.

What Result
A call on the same machine 21 to 26 ms, including starting the calling process
A call to another machine about 240 ms
Asking every daemon of another machine whether it answers 0.5 to 1.9 s for 10 to 19 daemons
A new set arriving, to every daemon answering 17 s on the workstation, 3 s on the laptop, under 10 s at the door
A set told to another store held there 25 s later
A search across machines with one of them not answering about 3 s, with that machine named in the result
The live table (8,070 rows) opened by a new binary every count equal

Known limits

  • A restart has a gap of seconds. Starting a new door before stopping the old one was written and removed: its moving parts cost more than the gap.
  • A call that names no machine goes to the first daemon registered with that interface.
  • The table daemon's own restart is a short outage for everything that registers through it.
  • One table per machine and a relay between them fits a handful of machines one person owns. It would not be the right tool for a hundred.
  • There are no containers, no scheduler and no agreement on state beyond the stamps.

Next

The registry of daemons and the list of machines are still two interfaces over the same table and are to become one. The relay and the secret are to move into the same binary as the table, so that one binary makes a machine a full member.

ComputeShack

Small, good solutions.

[email protected]

Privacy policy · © 2026 ComputeShack