How it works

A headless core, a thin surface#

PalanaCore is a headless Swift library that owns everything true—the topology, directory reads, plan engine, and transports—and carries a 90% test-coverage floor. Palana, the app you see, is a thin surface over it: it renders state, forwards intent, and decides nothing. It never composes a shell command, never classifies an operation, never touches a host. If the app disappeared tomorrow, everything pālana knows and everything pālana can do would still be sitting in the core, fully tested.

Two lines in that picture carry most of the architecture. The boundary between surface and core is the only thing the app can see across. The Conduit is the only door to the hosts. Both exist for the same reason: a boundary you can point at is a boundary you can test.

The Conduit#

Every fact discovered, every directory read, every byte moved passes through one component that does nothing but run the ssh already on your Mac. No other component spawns a process toward a host, ever.

pālana wraps the system SSH binary instead of embedding an SSH library. An embedded library would need its own key handling, config parsing, and ProxyJump semantics. Using the system binary means your ~/.ssh/config, keys, agent, and ProxyJump apply identically, and there is no parallel transport stack to audit.

The Conduit holds one ControlMaster session per host—opened on first use, reused after, closed on quit—so per-command overhead is near zero once a host is warm. That's why a pane refresh over SSH feels local.

The core, in four sentences#

The Field owns the map: hosts parsed from your ssh config, per-host facts—reachability, ZFS topology, userland flavor—discovered on demand and remembered. The Listing reads directories, one command per read; it never writes. The plan engine is a pure function from gathered facts to a Plan—no I/O of its own, which makes it the most testable object in the system, and it had better be, because it is the part that must never lie. The Transports run exactly the commands the plan composed—no improvisation between your Enter and the wire—and own the verification that gates the dangerous steps.

The Workbench is the fifth piece: a plugin API that hands a tool the Conduit, the Field, and a surface slot—and never the core's internals. The ZFS tool is its first, shipped proof.

Where your state lives#

No database. A database would make the cache look like a system of record, and it isn't one—the hosts are. Local state is five plain files in ~/Library/Application Support/palana/—settings, favorites, the append-only operations log, and the two that shape what you see on launch:

field-cache.json—the last-known topology, timestamped: what the Field remembers from your last visit, rendered as remembered until you ask it to look again. session.json—pane hosts and paths, window state: the workbench as you left it. Both are safe to delete at any time.

On launch, panes return to their previous locations and cached topology is clearly dated. Nothing contacts a host until you request an action that needs one.

No daemon, on purpose#

pālana runs when you open it and stops when you close it. There is no helper, launch agent, or background process. Discovery has no polling loop. That is a deliberate constraint: closing the app stops its orchestration.

While a transfer runs, pālana is running it. Close the window mid-run and the orchestration stops with it. The plan told you which machine the command runs on; a host-to-host rsync is jodo's process, interrupted like any ssh session would be—and --partial is in the flags so an interrupted transfer resumes instead of starting over.

Built in public#

pālana is open source under GPL-3.0, and so is its process: the ho-process/ directory in the repo is the full build record—seed, system design, and every bounded session that followed, written before the code they scoped. The system design holds every decision on this page with its rationale.