Skip to article

Linux installation

Agent CLI runs on the technician's Linux x64/glibc workstation, not the customer Daemon target. It is self-contained but needs OpenSSH client tools and explicit credential-provider setup. macOS is a separate technical preview.

Install and credentials

Download same-release verified archive/manifest from OpalSpan Downloads; browser attachment names are branded opalspan while signed stored names remain compatible. Install as the normal user, never root; keep complete companions and pinned trust. Use the returned data.path_directory for PATH. An explicit setup root takes precedence, followed by OPALSPAN_HOME and the compatible FORGE_HOME alias; relative XDG_DATA_HOME is ignored. Installer/launcher identities retain their separately managed locations.

Explicitly choose Secret Service or provisioned-key storage, without fallback. Secret Service requires DBUS_SESSION_BUS_ADDRESS for one unix bus, already running current-user service and an existing unlocked non-session collection; no automatic activation/unlock/prompt. Provisioned key is exactly 32 binary bytes with protected delivery/file permissions, distinct from stored tokens. See headless sign-in.

Configure the selected provider explicitly, then inspect its status:

opalspan credentials configure --provider secret-service --collection <existing-unlocked-collection-path>
opalspan credentials configure --provider provisioned-key --key-file <protected-32-byte-key-file> [--token-directory <protected-directory>]
opalspan credentials status

Choose one provider command, not both; configuration does not activate or unlock Secret Service and does not relax the protected-key requirements above.

Profile and credential adoption

Fresh defaults use $XDG_CONFIG_HOME/opalspan, $XDG_STATE_HOME/opalspan and $XDG_CACHE_HOME/opalspan, with ~/.config, ~/.local/state and ~/.cache fallbacks. Absolute XDG overrides remain independent; relative values are ignored. An existing Forge profile generation stays authoritative until explicit adoption. Explicit home roots remain at their supplied paths. CLI installation and system-service identities retain their own lifecycle. The canonical opalspan/secret-runtime state subtree stays at its original path with unchanged bytes through migration and rollback.

opalspan state status
opalspan state migrate --quiesced
opalspan state rollback --quiesced

Stop every CLI and transport process, including older binaries and other home/XDG contexts. Unset OPALSPAN_HOME/FORGE_HOME to move the default XDG generation. With a home override, the same command adopts only that home's pinned provider identities: its profile, cache, key and token paths remain unchanged. state status reports this provider-only mode. Current commands use a shared native flock; cutover takes its exclusive counterpart. Config/cache trees and the state profiles tree are renamed independently on their existing filesystems. Cross-mount moves, nested mounts, links, unsafe permissions, overlapping roots and conflicting generations fail before moving data. Owned session and connection paths and managed SSH references are repaired with exact Linux case. An interrupted transaction fences commands: state status identifies its direction and original XDG scope; repeat that same command/scope with --quiesced to finish.

The configured provider remains pinned. Collection, key and token-directory paths and original refresh-coordination locks stay in place, including an existing forge/credentials directory. They are provider storage, not a second active profile copy. A provider/key inside a moving profile or cache tree requires explicit external storage recovery first; cutover preserves that tree and reports the conflict. Secret Service keeps its existing collection and uses opalspan-cli item attributes for adopted identities; locked collections remain locked. Provisioned storage reads original-root FORGECR1 envelopes and writes authenticated OPALCR02 envelopes after adoption. No desktop keyring is required for a provisioned-key configuration.

Protected current values are verified before legacy identities retire on next use. Rollback restores current values, including rotations, to old-reader identities and compatible envelopes; it does not restore a stale backup or initiate sign-in. Finish rollback before starting a pre-migration binary. Preserve the stable key and provider metadata through either direction; loss of the original key cannot be repaired by renaming files.

Readiness and lifecycle

whoami checks live identity; doctor checks tools/artifacts/provider/workspace/server. Verified updates switch owned per-user generations, preserving profiles/pins. Repair/install requires archive and manifest; uninstall removes owned launchers/ activation and removable generations, retaining running/modified/foreign-containing ones. Inspect returned retained-generation facts. Close/disconnect active commands before removal. Sign-out across profiles is only when removing saved access is intended, not routine cleanup or complete profile erasure.