Client and connector configuration

Configure your CLI profile and the connector accounts you own. Model wrappers receive job paths and scientific inputs; connector credentials remain private.

CLI profiles, precedence and private files

--profile defaults to default. --config PATH selects a different profile file. Without it the path is $XDG_CONFIG_HOME/enumeray/profiles.json, falling back to $HOME/.config/enumeray/profiles.json. Use commands to maintain it:

enumeray --profile production auth configure https://enumeray.example.org
enumeray --profile production auth login
enumeray --profile production auth whoami
enumeray auth profiles

A credential-free profile file has this shape:

{
  "profiles": {
    "production": {"api_url":"https://enumeray.example.org"},
    "local": {"api_url":"http://127.0.0.1:8080"}
  }
}

Login adds optional access_token, refresh_token and expires_at (Unix seconds). Do not distribute a logged-in file. On Unix, profile and retry-state files must be regular files without group/other permissions; use chmod 0600 PATH. Credential files cannot be symlinks. The CLI writes its managed files privately.

Profile changes, upload recovery, live-log checkpoints and secret-output creation use private .lock sidecars to prevent concurrent writers. If a command reports that its state is in use, let the other command finish and retry. Keep the sidecar files: their presence alone does not mean a lock is held, and the OS releases the lock when a command exits, including after a crash. Do not remove a live sidecar to bypass another writer.

--api URL overrides the selected origin, but saved profile credentials are not sent across API origins. ENUMERAY_TOKEN supplies an explicit noninteractive bearer token and takes precedence over the profile token. It is your responsibility to pair that token with its intended API. auth configure changing the profile origin clears old credentials. --timeout defaults to 60 seconds per HTTP request; --json emits compact JSON, including runtime errors on stderr. Argument parsing errors remain plain text on stderr and exit 2, even with --json.

A saved personal-token document can supply automation without placing its secret in an argument:

export ENUMERAY_TOKEN="$(python3 -c 'import json; print(json.load(open("automation-token.json"))["token"])')"
enumeray --profile production --json run list
unset ENUMERAY_TOKEN

Create that private file with auth token-create NAME --scopes ... --output automation-token.json; see the command reference.

Connector runtime settings

The connector’s run command requires --journal, --api-base-url, --connector-id and --token-file. Use absolute paths under its private service account. It does not read the API server’s environment for those settings.

Option	Default	Bounds and purpose
--max-workers	1	1–64 assignments reserving compute; pending Slurm allocations count
--max-transfer-workers	2	1–64 simultaneous bulk I/O subprocesses
--max-pending-assignments	64	1–64 retained unfinished assignments; must be at least max-workers
--unpublished-retention-seconds	Omitted	1–315360000; omitted retains finalized unpublished outputs indefinitely
--poll-interval-seconds	2	1–300 idle polling seconds
--shutdown-timeout-seconds	30	1–3600 drain seconds
--recovery-mode	manual	manual or exclusive-local; latter requires an unshared, uncloned local volume
--credentials-file	Omitted	Private JSON mapping SSH references to local private-key paths
--log-policy-file	Omitted	JSON capture/archive policy pinned per launch

--confirm-prior-process-stopped is an explicit assertion for manual session recovery after verifying all prior owners stopped, including on other hosts. Keep it out of ordinary unattended starts. --allow-insecure-http permits bearer tokens over trusted development/private-network HTTP; HTTPS is the ordinary deployment path. Neither setting changes the scientific replay boundary.

The SSH file shape is:

{"ssh":{"cluster-key":"/var/lib/enumeray-connect/.ssh/id_ed25519"}}

Context credential_reference selects the map key. OpenSSH/SFTP, batch authentication and trusted known_hosts are required. Credentials stay on the connector host. Execution context manifests and editable author publications are separate public configuration; see contexts and manifests.

Log-policy JSON

The complete default policy is:

{
  "segment_bytes":65536,
  "retained_segments":16,
  "archive_enabled":false,
  "archive_source_bytes":16777216,
  "archive_compressed_bytes":52428800,
  "archive_publication_seconds":86400
}

Segments are 4096–1048576 bytes, with 2–128 retained segments and at most 16 MiB live bytes per source. Archive source bytes must be at least live retention and at most 128 MiB. The compressed ceiling is at most 512 MiB and at least three source budgets plus 2 MiB framing. The publication deadline is 1–31536000 seconds. Set archive_enabled:true for raw archives. Policy changes affect new launches; recovered jobs retain their pinned effective policy. See connector operations for publication and retention behavior.