Connect your first compute resource

For the guided development or managed journey, use guided connector setup. It saves your selections, coordinates approved host preparation and continues through a candidate trial. The manual Linux process/direct procedure below remains available for site operators.

This walkthrough connects one Linux host using the process driver. Run host setup as a host administrator, enumeray commands as the connector owner, and connector commands as its dedicated service account. For a cluster or remote host, follow context setup after enrollment.

You need a working CLI login, enumeray installed at /usr/local/bin/enumeray, and outbound HTTPS to your API. File models also need versioned storage provided by Enumeray. Replace https://enumeray.example.org with your service origin. lab-connector and lab-cpu are example resource IDs; choose unique IDs and keep them consistent in every file and command.

For trusted experiments under your existing regular OS account, use the single-user development recipe. It needs an explicit development context and connector startup opt-in. The managed account separation below remains the default.

For reviewable Linux/macOS configuration and checks before any publication, use configuration generation and host preflight.

1. Prepare two host accounts

The connector account holds its bearer token and journal. The execution account owns job directories and runs model code. They must be different accounts. On a Linux host with useradd, create them and their directories:

sudo useradd --system --user-group --create-home --home-dir /var/lib/enumeray-connect \
  --shell /usr/sbin/nologin enumeray-connect
sudo useradd --system --user-group --create-home --home-dir /var/lib/enumeray-model \
  --shell /usr/sbin/nologin model-runner
sudo install -d -m 0700 -o enumeray-connect -g enumeray-connect \
  /var/lib/enumeray-connect /var/lib/enumeray-connect/credentials
sudo install -d -m 0700 -o model-runner -g model-runner \
  /var/lib/enumeray-model-work
sudo install -d -m 0755 /opt/enumeray/models

Use existing site accounts if they already satisfy this separation. Both accounts need execute access to the unified executable. Installed releases go under /opt/enumeray/models; authors need an agreed deployment route there, and the execution account needs read/execute access to each complete release. Keep the connector’s home and journal inaccessible to model-runner.

Create /etc/sudoers.d/enumeray-runner using sudo visudo -f /etc/sudoers.d/enumeray-runner and add:

enumeray-connect ALL=(model-runner) NOPASSWD: /usr/local/bin/enumeray compute-runner *

This permits the credential-free compute-runner command under the model account. Review the rule with your host administrator. The direct launcher adds an action and job directory and requires passwordless sudo -n. Runtime CPU, memory and account isolation remain host policy. Separate contexts/accounts can isolate models from each other.

2. Create the connector and save the enrollment

On the owner’s CLI machine:

umask 077
enumeray auth configure https://enumeray.example.org
enumeray auth login
enumeray auth whoami
enumeray connector create lab-connector --label 'Lab connector' \
  --max-outstanding-assignments 4 --output enrollment.json

connector create makes your account the owner of this compute resource and reports success only after saving a validated private one-time enrollment document. A single connector needs no group, additional resource name or grouping identifier. It does not start a daemon. Enrollment expires after 15 minutes. An existing output path is preserved and refused before any request.

If creation loses its reply or cannot confirm saving, retain the same connector ID and settings. The CLI makes one read-only inspection; an inspection failure leaves the outcome unknown. A creation replay can confirm registration but cannot recover the original secret, so it exits unsuccessfully without writing an enrollment file. Inspect the connector and, if no usable file was retained, explicitly request a replacement into a new file:

enumeray connector get lab-connector
enumeray connector enrollment lab-connector --output replacement-enrollment.json

Replacement invalidates earlier unused enrollment documents. A failed save may still have published a file; preserve and inspect it privately before requesting another secret. The CLI never automatically issues a replacement. Transfer enrollment.json to the host through your approved private route, then install it for the connector account (use replacement-enrollment.json instead if replaced):

sudo install -m 0600 -o enumeray-connect -g enumeray-connect \
  enrollment.json /var/lib/enumeray-connect/enrollment.json
sudo -u enumeray-connect /usr/local/bin/enumeray connector enroll \
  --directory /var/lib/enumeray-connect/credentials \
  --api-base-url https://enumeray.example.org \
  --enrollment-file /var/lib/enumeray-connect/enrollment.json

Successful enrollment leaves a private token and retained machine identity in the credentials directory. If the request or reply is interrupted, repeat this exact enrollment using the same directory and enrollment file, even after the original deadline: a committed enrollment can return its original receipt while its connector credential remains active. A new directory creates another identity. If an unused enrollment expires, the owner issues another into a new output file using the replacement command above. An identity that never enrolled can use that replacement with the same directory. After successful enrollment, use the credential rotation procedure with a new private credential directory and the original execution journal. Store or remove consumed copies according to your secrets policy.

3. Register a complete context

Save this as context.json on the owner’s CLI machine. It has the same shape as the downloadable local context:

{
  "manifest_version": 1,
  "kind": "execution-context",
  "spec": {
    "id": "lab-cpu",
    "connector_id": "lab-connector",
    "definition": {
      "driver": {
        "kind": "process",
        "scratch": {
          "max_bytes": 1073741824,
          "max_entries": 10000,
          "max_depth": 32,
          "scan_interval_ms": 1000,
          "cache": "per_run",
          "symlinks": "forbid"
        }
      },
      "installation_roots": ["/opt/enumeray/models"],
      "work_root": "/var/lib/enumeray-model-work",
      "max_outstanding_assignments": 4,
      "connection": {
        "kind": "direct",
        "launcher": ["/usr/bin/sudo", "-n", "-u", "model-runner", "--",
          "/usr/local/bin/enumeray"]
      }
    },
    "metadata": {
      "location": "Research lab",
      "disclosure": "Research-owned machines process submitted model data."
    }
  }
}

enumeray connector context create lab-connector --file context.json
enumeray connector context list lab-connector

The response should list lab-cpu attached to lab-connector with the reviewed roots, driver and metadata. Registration stores configuration. When an author registers an installed publication, the connector checks the actual release, runner identity and backend readiness. A registered context alone does not prove that a scientific model can run. Execution settings are immutable; use a new context ID when changing roots, identity or backend.

4. Start a durable connector service

For a foreground check, run as the connector account:

sudo -u enumeray-connect /usr/local/bin/enumeray connector run \
  --journal /var/lib/enumeray-connect/journal \
  --api-base-url https://enumeray.example.org --connector-id lab-connector \
  --token-file /var/lib/enumeray-connect/credentials/token \
  --max-workers 4 --recovery-mode exclusive-local

Stop it with SIGINT before installing the service. exclusive-local is suitable only for one installation on an unshared, uncloned local volume. Otherwise leave the default manual recovery mode and follow recovery.

Save this Linux systemd example as /etc/systemd/system/enumeray-connector.service:

[Unit]
Description=Enumeray lab connector
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
User=enumeray-connect
Group=enumeray-connect
WorkingDirectory=/var/lib/enumeray-connect
UMask=0077
ExecStart=/usr/local/bin/enumeray connector run --journal /var/lib/enumeray-connect/journal --api-base-url https://enumeray.example.org --connector-id lab-connector --token-file /var/lib/enumeray-connect/credentials/token --max-workers 4 --max-transfer-workers 2 --max-pending-assignments 64 --recovery-mode exclusive-local --shutdown-timeout-seconds 30
Restart=on-failure
RestartSec=5
TimeoutStopSec=40

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now enumeray-connector
sudo systemctl status enumeray-connector
sudo journalctl -u enumeray-connector -n 50 --no-pager
enumeray connector diagnostics lab-connector

Only one process may own the journal. Keep this state directory through upgrades and restarts. The direct sudo launcher needs privilege switching; a unit with NoNewPrivileges=true would prevent it. Configuration acknowledgements should catch up to the connector generation; inspect failed publications if they do not.

5. Give an author compute and installation instructions

Ask the author for the user_id from enumeray auth whoami, then substitute that UUID below:

enumeray connector grant create lab-connector --context lab-cpu --user MODEL_OWNER_UUID \
  --max-queued-runs 100 --max-outstanding-assignments 4
enumeray connector grant list lab-connector
enumeray connector get lab-connector

The grant permits that account to publish on the context with the stated limits. It creates no host login and installs no files. Give the author the context ID, approved installation root, execution account, deployment route and runtime requirements. The author runs enumeray connector grant available, installs an immutable release, then follows publication. Registration finds the author’s active grant and pins it on the publication. Reissuing a grant does not move old publications to it.

The first usable handoff is a publication reported ready by the connector, followed by a test run that reaches a verified terminal result. Keep the owner available to investigate launcher, permissions or readiness failures with the author.