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

Open Machines, select Add Machine, and choose a Machine name.

Odyshell generates a command shaped like:

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

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 Session Local Policy on every authenticated connection:

• Sessions up to 24 hours, with selectable 15m/1h/2h/6h/8h/24h durations;
• one concurrent Session;
• one concurrent Command;
• Commands up to ten minutes;
• up to 1 MiB of output retained in the Organization timeline;
• remote human approval allowed.

The Machine is an Organization resource and Local Policy never names Agents. The Server can grant less authority but cannot widen this ceiling. A mismatched Organization, duration, concurrency request, Session identity, or Command bound is denied by the Client even if the Server is compromised. The Organization authorizes Agent-to-Machine access only through a temporary Session.

The stored Client configuration is strict and Session-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 Session 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.