Machines

A Machine runs a lightweight Client under a dedicated Linux operating-system user. The Client authenticates outbound with an Ed25519 identity; the Server never opens a connection into the private network.

Enroll a Machine

Install the administration CLI on the target host:

npm install --global @odyshell/cli

Register the Agent first. Then open Machines, select Add Machine, and choose:

• a Machine name;
• the first Agent allowed by Local Policy.

Odyshell generates a command shaped like:

ods --server https://api.example.com up \
  --token <single-use-token> \
  --name production-api \
  --agent-id <agent-id>

Run it as the Linux user whose authority Commands should receive. The token expires after ten minutes, can be consumed once, and is never written to Client configuration. Enrollment fails closed if the Organization has no sovereign identity binding.

ods up writes a separate Client Profile, installs a systemd user service, verifies Server reachability, and starts the outbound connection. The terminal can then close. Use:

ods client status
ods down
ods up

Local Policy

The generated Profile advertises a Task Local Policy on every authenticated connection:

• exactly the selected Agent;
• Tasks up to one hour;
• one concurrent Task;
• one concurrent Command;
• Commands up to ten minutes;
• up to 1 MiB of transient output;
• remote human approval allowed.

The Server can grant less authority but cannot widen this ceiling. A mismatched Organization, Agent, duration, concurrency request, or Command bound is denied by the Client even if the Server is compromised.

The stored Client configuration is strict and Task-native. It contains one Machine identity and one Local Policy; legacy runner profiles, Session/Operation limits, remote sudo flags, and Removed tenant identifiers are rejected rather than interpreted.

An active Task provides arbitrary non-interactive shell authority as the Client's Linux user. It does not configure sudo, isolate the process, filter commands, or claim rollback. Use a dedicated user with only the filesystem, credential, network, and service access the Agent needs.

Client Profiles

Named Profiles keep separate Machine identities, state directories, Local Policies, and systemd services:

ods --server https://customer-a.example up --profile customer-a <enrollment-options>
ods --server https://customer-b.example up --profile customer-b <enrollment-options>
ods profiles ls

--profile and --config cannot be combined. Never copy a Client configuration between hosts; its private Machine key and local policy belong to that Profile.

Remove one local identity with ods profiles remove <name>. ods reset --yes removes every local Profile. Cloud records remain visible for audit until an administrator removes them.