Remote executors

A remote executor performs an action on a computer paired to the user instead of on the Metnos server. It can, for example, read a folder that exists only on a laptop or start an application on a Windows PC. The server decides; the paired computer executes.

Why remote executors exist

The Metnos server holds the core, its rules, and the activity record, but data may live elsewhere. A document may be on a work laptop, a photograph on another computer, and an application only on Windows. Remote executors bring a bounded capability close to the resource without installing a second Metnos server on every machine.

The paired computer does not listen to the conversation or plan. It cannot choose a different action from the one it receives. The server still identifies the user, selects the executor, applies policy and Vaglio, asks for any required confirmation, and records the outcome.

Server and local component

Each paired computer runs metnos-client, a small component that maintains contact with the server. The division of work is straightforward:

The client initiates the connection to the server. You do not need to open an incoming port on the PC. The device does, however, need to reach the Metnos server address over the intended network.

How to pair a computer

Pairing creates a stable identity for the device. It is more than signing in with a username and password.

1. In web chat, open Settings › System › Devices.
2. Choose the owning user, give the computer a recognisable name, and generate the temporary link.
3. Open the link on the computer you want to pair. On Windows, the guided flow downloads and installs the persistent client.
4. The client creates an Ed25519 key pair, gives the public key to the server, and pins the server's public key.
5. Return to Devices and check pairing, version, last contact, and any errors.

The initial link expires and can be used only once. After pairing, the device is recognised by signatures made with its persistent key; the initial link does not become a permanent credential.

The fingerprint shown in the interface is a shortened form of the public key. It lets you compare two identities without displaying the whole key. Revoking a device means that its identity is no longer valid for new work.

How Metnos chooses where to act

An executor may leave the server only when its signed manifest allows it. Metnos considers all of the following:

• the operating systems declared by the executor;
• its placement rule, including whether devices are allowed;
• the owner of the device;
• whether the computer is currently available;
• the capabilities, credentials, and dependencies required by the action.

If the user says “on office-laptop”, the name is matched against devices actually paired to that user. An IP address does not identify the computer: it may change, be shared, or belong to an intermediate gateway. If the name is missing or ambiguous, Metnos does not guess.

The conversation may briefly remember an explicit destination, so an immediate follow-up such as “zip it” can stay on the same computer. This is not a permanent preference and does not survive as general authority.

What happens during an action

1. The server creates a unique job identity, adds an expiry, and signs the executor, arguments, destination, and expected code hashes.
2. The client asks the server for its next job and verifies the signature, expiry, and device identity.
3. If the executor is not already in the verified cache, the client downloads its manifest and code. It checks the manifest signature and every file hash before use.
4. The client prepares an isolated working directory, applies the limits derived from the contract, and runs the executor.
5. The result is first saved locally, then signed and sent to the server. If the network fails, it remains queued for redelivery.
6. The server verifies the signature and job identity, records the outcome, and resumes the plan.

Is the executor deleted after the action?

No. In the current implementation, a verified executor remains in a local cache addressed by the manifest and code hashes. This avoids downloading the same bundle for every request. A different version receives a different cache location; a corrupt copy is discarded and downloaded again. The temporary working directory for one invocation is removed after execution.

The cache does not make the code autonomous. Every new action still requires a signed invocation, valid arguments, an acceptable expiry, and the server's ordinary controls.

What a heartbeat is

A heartbeat is a small, signed message that the client periodically sends to the server. In effect, it says: “I am still running; this is my version, and this is the isolation level I can provide.”

The latest heartbeat lets the interface show that the device was contacted recently. When no heartbeat arrives within the expected window, the device is shown as unreachable. Heartbeats run separately from executor work, so they can continue while an executor is busy.

A recent heartbeat does not prove that every executor will work. The computer may be on but lack a required dependency, enough storage, access to a particular path, or suitable sandboxing. To decide whether an action is possible, Metnos considers last contact, platform, declared capabilities, client state, and the executor contract together.

Isolation on Linux and Windows

A Job Object limits lifetime, resources, and the process tree, but does not by itself isolate files and network as AppContainer does. The client therefore reports the level actually applied, not the one desired. If a process exceeds its deadline, the client terminates the entire tree started for that invocation.

Network failures, duplicates, and revocation

Every job has a stable identity. The client records work it has started or completed, and the server recognises results it has already received. If the network fails after execution, the result is redelivered without running the action again. This matters particularly for writes, moves, and process starts.

The client also prevents two instances of itself from running at the same time on one computer. An independent watchdog observes invocation deadlines; if sandbox preparation or the executor gets stuck, the client exits in a controlled way and the operating-system supervisor can restart it.

Revocation is enforced on the server. From that point on, the device identity cannot receive new work or deliver valid heartbeats. The server does not rely on the old client behaving well; it simply stops recognising it.

What this design does not promise

• Pairing a computer does not authorise arbitrary commands.
• Compatibility depends on the individual executor, not just the operating system.
• A recent heartbeat proves contact with the client, not the health of every application or resource on the device.
• Linux and Windows offer different containment; the result must state what was actually applied.
• Undo for a remote action, where supported, runs on the same device that produced the effect.
• A backup used to undo remote deletion stays on the device; it is not silently moved to the server.

For the complete operational procedure, continue with Device pairing. For containment details, see the sandbox guide.