Security

Odyshell grants remote Agents same-user shell authority on customer-controlled Linux Machines. The Server and Client enforce identity, Organization isolation, policy, expiry, and resource bounds; an allowed Command can still change anything available to the Client's operating-system user.

Authorization path

A Command is accepted only when:

1. the OAuth access token is valid and bound to the Agent's Organization;
2. the Task belongs to that Agent and Organization and is active and unexpired;
3. the Task is bound to the requested Machine, Client Profile, and operating-system user;
4. the authenticated Machine identity matches that binding;
5. Local Policy still allows the Agent, duration, concurrency, timeout, and output ceiling;
6. Autonomy Policy authorized the Task or a permitted Human approved it;
7. the idempotency key and request fingerprint agree.

These checks run outside the model. Requests fail closed on an unknown identity, stale Task, cross-Organization ID, replay conflict, offline Machine, or policy mismatch.

Identity and enrollment

Odyshell Identity uses Better Auth with PostgreSQL for Human sessions, Organization membership, OAuth clients, and tokens. Authorization Code with PKCE serves interactive MCP installations; Organization-bound Client Credentials serve unattended Agents. Revocation blocks later access.

Machine enrollment tokens expire, work once, and are not persisted. Each Client Profile generates an Ed25519 identity and keeps its private key on the Machine with owner-only permissions. Profiles never fall back to another Server or identity.

Host authority

Commands run without a PTY as the Linux user running the Client. They can read that user's files and credentials, use its network and services, and make changes that outlive the Task. Odyshell does not configure sudo. Use a dedicated user with only the resources the Agent needs.

Graceful cancellation targets the Command process group. An abrupt Client crash can leave a detached process running; reconnect reconciliation records uncertainty and can quarantine the Profile rather than silently restore authority.

Audit and privacy

Durable Task audit binds Organization, Agent, Machine, Human decision, exact command, working directory, timeout, status, exit code when known, and timestamps. OAuth credentials, enrollment tokens, Machine private keys, stdout, and stderr are excluded. Output is a bounded, transient delivery buffer for Agent reconnect and should be treated as potentially secret while available.

Self-hosted deployments keep identity, policy, Task, Command, audit, and transient output data in their own PostgreSQL and storage boundary. Production operators must provide TLS, backups, retention, secret management, and log redaction.