adagio-server

adagio-server

Licensed under the MIT License. This covers the server package only; it does not change the license of the hosted Adagio application or sibling projects.

adagio-server is Adagio's outbound execution runner. It claims jobs over HTTPS, executes them with the existing adagio-cli, and reports status and artifact paths. It never requires an inbound network port. The initial server platform is Linux with Python 3.11+ and user-level systemd; Docker is needed for container-backed pipeline actions.

Before marking a claimed job running or starting adagio runtime, the local runner performs a lightweight preflight for the selected nodes and their upstream dependencies. Docker must be reachable (with a 10-second timeout); Conda needs an executable, an existing environment, and an executable Python interpreter; Apptainer/Singularity needs an executable and a readable local .sif image. Known runtime failures are collected into an actionable job error and leave the pipeline CLI unstarted. Checks are registered by runtime kind in adagio_server.agent.preflight. Unexpected preflight errors are logged and defer to the CLI, preserving its configuration validation. Checks run only for the standard CLI command using the adapter's Python interpreter and the local executor; custom CLI commands and external executors defer to the CLI. This avoids checking a different installation or execution host. These checks apply to Desktop and Runtime Server jobs; standalone adagio-cli execution is unchanged. They do not install dependencies, start Docker, or validate plugins and image contents.

Each claimed job starts independently, even while other jobs are running. Adagio does not impose a job-count limit or decide whether the host has spare CPU or memory; the server owner manages resource usage. The outbound handoff is not a resource scheduler. Slurm/SGE integration is separate future work.

Install the server in a persistent virtual environment, then use the enrollment token and deployment URL shown under Settings → Runtime Servers in Adagio:

python3 -m venv ~/.local/share/adagio-server-venv
source ~/.local/share/adagio-server-venv/bin/activate
python -m pip install adagio-server
adagio-server --version

export ADAGIO_ENROLLMENT_TOKEN='<code from Adagio>'
adagio-server install --url https://app.adagio.run

The install command exchanges the short-lived token for a machine credential, stores that credential with user-only permissions, then installs and starts the systemd user service. Jobs execute with the same Unix filesystem permissions as the user who installed it, including supplementary groups used for shared data. Docker-backed actions also run as that user. Images that require root during startup are therefore unsupported on a Runtime Server. Granting someone permission to use a server grants code execution as its Linux account. An account with access to a rootful Docker daemon can administer the host; this is a trusted execution environment, not a sandbox for untrusted users or plugins. Supplementary groups are preserved for shared-data access. Do not assume UID flags or dropped container capabilities isolate a Docker socket made accessible through mounted paths. Docker socket isolation needs separate review. The command prints a note when an administrator may need to enable systemd user lingering for service operation after logout.

Install the package in a persistent virtual environment (or with pipx) rather than an ephemeral uvx environment. The systemd unit records the interpreter path that performed the installation.

New installations select a stable loopback port from the Linux user id so different users on a shared host do not contend for port 8760. Pass --port 23456 to choose an explicit port. The listener remains bound to 127.0.0.1 and requires a per-process bearer token.

For an interactive foreground process, use adagio-server start. Plain HTTP and disabled TLS verification are refused unless install --insecure is passed for a development deployment.

Updates and reporting

Contract mismatches stop with exit code 42 and an update-required message; credential rejection uses exit code 41. Neither condition should restart the same configuration repeatedly. After upgrading an existing installation, rerun adagio-server install with a fresh enrollment token to update its systemd unit (older units only suppress restarts for code 41).

Telemetry uploads have bounded text, metadata, and batch sizes. Large logs are sent in small batches with continued long lines; full logs remain on the server. Oversized optional event/provenance data is replaced by a telemetry_truncated marker rather than losing the job's lifecycle report. These limits do not apply to input/output file sizes or job counts.

Pipeline inputs and data artifacts never leave the server. The one file it sends is a visualization (.qzv), and only when the user who ran the job opens it in Adagio Desktop: Adagio asks for that file, the server uploads it, and Adagio relays it to the app without keeping it. Whatever path is asked for, the server sends only a .qzv inside that job's own output directory.

This revision requires the adapter-schemas 0.5.0 release. Source builds use the exact commit recorded in vendor/adapter-schemas/VENDOR_PIN; publication and release-tag verification must be completed before package-index installation.

Release operators and QA testers should follow RELEASING.md in the repository.