Running sessions on a Mac host (vord Headless)

What it is

vord Headless runs on a Mac such as a Mac Studio without the vord app. Sessions run on that host and you control them from vord on your Mac or iPhone.

Install once

Download the ZIP for your release from vord-headless releases. The versioned download URL has this form:

https://github.com/lass-machen/vord-releases/releases/download/vord-headless-beta-<version>/vord-headless-<version>.zip

Unpack the ZIP, then run its installer with the app bundle:

./install.sh --from ./vord-headless.app

Enroll and pair

On the host, run vord-headless enroll and enter the enrollment code when prompted. Then run vord-headless pair to display the host’s pairing code.

In vord, open Settings → Connections → iPhone & iPad → Hosts and choose Pair host…. Compare the fingerprint shown in vord with the one shown on the host. The host then asks three questions in German: whether to pair the Mac (Koppeln?), whether it may start sessions (Darf dieses Gerät Sessions starten?) and whether it may administer the host (Darf dieses Gerät den Host verwalten?). Type j or y and press Return to answer yes. Any other answer, including an empty one, means no.

Manage rights later

List paired devices and their IDs with vord-headless devices. Grant or revoke a right for a paired Mac from the host:

vord-headless devices grant <id> start-sessions
vord-headless devices grant <id> host-admin
vord-headless devices grant <id> run-builds
vord-headless devices revoke <id> start-sessions
vord-headless devices revoke <id> host-admin
vord-headless devices revoke <id> run-builds

Update

Check for an update with vord-headless update --check, or install it with vord-headless update. If sessions are running, add --yes to proceed. Choose the release feed with --channel beta or --channel live; without it, the current channel is used.

The updater verifies the archive signature and Apple’s code signature, swaps in the new app, restarts it, and automatically restores the previous version if the new version fails its health check.

Choose a work folder

Set an absolute, existing folder as the work root, for example a directory on an external drive:

vord-headless config set work-root /Volumes/Work/vord

Remove the override with vord-headless config unset work-root. Run vord-headless config to see the current work-root setting.

New project on host

You create a project on the host from the Mac: open the On host… sheet of a project and press New project on host… below the project picker. Pick the Kind — Empty folder lets the host create a new folder with a git repository in it, Copy of a Mac project pushes one of this Mac’s git projects to the host over code sync — then set the Parent folder on the host and the Name of the new project and press Create. The host only creates projects inside its work folder or next to an existing project; any other parent folder is refused. Both kinds need an online host with a current vord-headless; without the matching host feature a kind stays disabled and the section shows “This host does not support it yet.”. As soon as the host lists the new project, the sheet selects it for you.

The sheet around it is described in Starting a session on a host.

A Mac project for every host session

A session started on the host needs a Mac project. On host… from a project sends that project with the start. Opened without a project, the sheet asks for a Mac project and keeps Start off until you choose one. The session cannot start without it.

The host’s own project id is a different id. vord places the tile by the Mac project, not by the host project id.

A session that arrives with neither a Mac project nor a matching project lead stays visible. The sidebar, above the project list, and each host row under Settings → Connections → iPhone & iPad → Hosts show how many sessions have no project. Expand a host row to see the agent and the start time, without the session title. Assign… picks a Mac project on this Mac; the session then shows up as a normal tile in that project. Stop ends it on the host. Once the session is gone, vord forgets the assignment.

When a host session asks for input — for example whether to trust a folder or allow a tool — the same prompt appears on the session tile and in the focus transcript, in both Code and Cowork. Click an option to answer. The paired iPhone shows the same choices in the command zone, and the answer goes to the host. A shared guest can see the session but cannot answer it. If the host does not offer this yet, open the session in the focus view and answer the prompt with the keyboard in the live terminal.

Code sync to the host

The first copy of a repository to the host runs as code sync. The git steps on the host may take up to 4 minutes each, so large repositories clone reliably instead of running into a short timeout.

Every code sync writes one line to the host log ~/Library/Logs/vord-headless/serve.log — the result, the error code, the duration and the target:

code-sync 3fa85c12 accepted - 842ms target=/Volumes/Work/vord

When a sync does not finish, that line is the first place to look.

Agents can check the host

A main session can ask a paired host for a read-only check with host_check. The check shows prompts and states. It never answers a prompt. A person answers a prompt at the session tile.

The check reports tool versions against the lock files, free disk space, the latest error lines, and the service, relay, and cloud state. Pass host (name or id) when several hosts are paired. Pass checks with any of tools, disk, errors, and service to run only those.

Child sessions can call host_status, which reads this Mac’s cache. They cannot call host_check. A host that does not offer the check returns that cached status instead. The Mac needs the right to administer the host. Each check writes one line to the host log.

Child sessions on the host

An agent on the Mac can start child sessions on a paired host. Host children now launch with the agent’s autonomy flags instead of stopping at their very first approval prompt. The levels themselves are described in Child sessions.

A host child gets the same autonomy level as a local child of that agent: the level you set on the Mac, limited by the permission mode of the session that starts it. In plan mode that is standard.

Note

An older host that does not know the level yet starts host children with full access, the vord default. Update the host to apply a stricter level.

If a host child cannot take its first instruction — for example because the agent shows a first-run trust prompt — vord reports it instead of leaving the child idle:

• a permission request with the visible screen text, or
• a failure after the waiting time of ten minutes has passed.

Follow-up messages to a host child arrive even when its tile is not open on the Mac.

Host roles

The host has two roles: Sessions, and Builds (tests and builds). Both are on by default. A paired Mac with the administer the host right can change them. When Sessions is off, the host rejects new sessions.

Host roles on the Mac

In vord, each paired host carries its roles in Settings → Connections → iPhone & iPad → Hosts: the switches Sessions and Tests and builds sit in the host’s row, below its name and connection state, and they apply to the host itself, for every Mac paired with it. Changing one needs the administer the host right on that host — without it the host refuses the change and vord shows the command to grant the right on the host (vord-headless devices grant <id> host-admin). While the host is offline, both switches are visible but cannot be switched; an online host with an older vord-headless shows “Host roles need a newer vord-headless on this host.” instead of the switches.

Builds on the host

A lead session on your Mac can start a build or test on a paired headless host. The host runs that job on its own build queue. It does not open an agent session for it.

The Mac needs the right to run builds. That right is off until you grant it on the host:

vord-headless devices grant <id> run-builds

The host role Builds (builds) has to be on as well. vord-headless status shows it as builds:on. Switching the role needs administer the host. Starting the run does not.

The host answers with the run_id, the exit code, a short excerpt of the log, and the path, size, and SHA-256 of the zipped xcresult. The full log and the zip stay in the run’s lane on the host. This version does not fetch them.

This version accepts only the destination platform=macOS and only the priority normal. There is no live log.

The host accepts only an allowlist of gate arguments. It does not take a shell command, a working directory, environment variables, or extra xcodebuild options from the Mac.

Handing a Mac build-gate run to a paired headless host is off by default. Leave VORD_BUILD_HOST unset or set it to off, and the gate runs on the Mac without starting the host client. Set it to auto or a host name to offer an allowed build or test to that host. If the host cannot take the run, the gate stays on the Mac and prints why.

Check status

Run vord-headless status to see the version, channel, roles, and work-root. Run vord-headless status --sessions to list session status. The cloud= field shows how the host itself is signed in to vord Cloud: off (not enrolled, no token), ok (signed in), unsupported (the store has no host route; retried every 6 hours), or error (the last attempt failed; retried every 6 hours). Older hosts without a value report cloud=unavailable.

Known limit

In vord 0.2.225 and earlier, restart vord once after pairing a new host for it to appear. Newer versions include the fix.