palaestrAI Web UI

About

The palaestrAI Web UI is a browser-based front-end to manage the full experiment lifecycle without touching the command line. It runs inside the same process as palaestrai serve — there is no separate service to install or configure. Under the hood it uses the REST API described in Running palaestrAI as a Service; anything the UI does can also be automated through curl or any HTTP client, and the two views always stay in sync.

The UI is styled with Pico.css and uses HTMX for its interactive partial updates. YAML editing happens in an in-browser CodeMirror editor with folding, tab-to-spaces, and dark-mode support. Everything is served from Python — no separate Node.js/webpack build step and no external CDN dependency at runtime.

Quickstart

Start the server the same way you would to expose only the REST API:

palaestrai serve

Then open the Web UI in your browser:

The service binds to all interfaces on TCP port 4247 by default; see Running palaestrAI as a Service for how to change host and port. To make the UI reachable from another machine, publish port 4247 and browse to http://<host>:4247/ui.

The service stays online until it receives SIGINT or SIGTERM (e.g., Ctrl+C). All four pages share a common navigation bar in the top-left corner:

  • Status — currently running and scheduled experiment-run instances, with a Cancel button per instance.

  • Templates — reusable snippets of experiment YAML that other pages can drop in with one click.

  • Experiments — arsenAI experiment documents; edit, generate runs from them, and schedule those runs.

  • Experiment Runs — individual experiment run documents; edit, save, or schedule.

Note

The Web UI writes to the same database as the CLI. Anything you save here (experiments, runs, templates) is visible to palaestrai experiment-start and vice versa. Started runs record the operating-system user name they were launched under (experiment_run_instances.user); UI-initiated runs record the user the palaestrai serve process is running as.

The pages

Status

The Status page lists every experiment-run instance whose lifecycle status is RUNNING or SCHEDULED; FINISHED and ERROR rows are intentionally hidden so the page stays focused on actionable state. Each row shows

  • the instance UID,

  • the parent experiment run,

  • the parent experiment,

  • the user that launched it (NULL for programmatic runs),

  • the current status, and

  • the wall-clock start time.

The Cancel button on each row issues DELETE /experiment_run_instances/{uid}, which asks the executor to shut the underlying run governor down gracefully. Cancellation is asynchronous and best-effort: by the time the request reaches the executor the instance may already have terminated, and there is no dedicated CANCELLED status — cancelled instances end up FINISHED (if they were queued) or as whatever the RunGovernor’s exit code maps to.

The row list auto-refreshes at a short interval via HTMX; there is no manual refresh button.

Templates

Templates are reusable YAML snippets — the recurring blocks that you’d otherwise copy-paste between experiment or run documents. They live in a dedicated templates database table and are typed by TemplateType (e.g. environment, agent, schedule phase); the type drives how the other pages surface them.

From the Templates page you can

  • create a new template by name and type,

  • edit an existing template in the CodeMirror YAML editor,

  • rename or copy a template via Save as…, and

  • delete a template.

The editor persists changes to the database on Apply. There is a dark-mode toggle in the editor toolbar.

Experiments

The Experiments page lets you work with arsenAI experiment documents — the design-of-experiments layer that expands one document into many concrete experiment runs.

For each experiment you can

  • edit the document in the YAML editor (with folding, section navigation, and snippet insertion from the Templates page);

  • generate the resulting experiment runs. POST /experiments/{name}/generate runs arsenAI’s generator in-process, writes the produced run documents to the database, and returns their UIDs. No files are written to disk.

  • schedule one or several of the generated runs: pick them in the right-pane list (multi-select) and click Schedule. Each scheduled run is queued through the same executor path as palaestrai experiment-start.

Generation errors surface as HTTP 422 responses with the underlying arsenAI diagnostic, so a malformed experiment document does not become a 500 in the UI.

Experiment Runs

The Experiment Runs page mirrors the Experiments page, but at the finer granularity of individual experiment run documents (the artefacts that palaestrai experiment-start and the REST API’s PUT /experiment_runs operate on).

For each run you can

  • edit the run document in the YAML editor;

  • save — either in place (Apply), or under a new name (Save as…), which stores a copy without overwriting the original;

  • schedule the run, optionally as a multi-select from the right pane. Scheduled runs appear on the Status page as soon as the executor picks them up.

Editing conventions

The YAML editor is the same widget on every page and behaves the same way:

  • Tab inserts two spaces.

  • Ctrl+/ toggles a line comment.

  • The gutter shows fold markers for every YAML block.

  • Section-level edits are cursor-based: the editor detects which top-level block your cursor is in and highlights matching lines, which makes surgical edits (e.g. changing a single phase) easy.

  • Save as… always makes a copy; use Apply to overwrite the document you are editing.

Under the hood: REST API

The Web UI is a thin HTMX layer over the REST API. Every action you perform in the UI maps to one of the endpoints in Running palaestrAI as a Service, augmented by the following additions:

  • GET /experiment_run_instances — list all active instances (RUNNING + SCHEDULED), ordered by creation time. Used by the Status page.

  • DELETE /experiment_run_instances/{uid} — cancel a running or scheduled instance. Sends an ExperimentRunCancelRequest to the executor.

  • GET|PUT|POST|DELETE /templates and GET|POST|DELETE /templates/{template_id} — full CRUD for reusable YAML snippets.

  • POST /experiments/{name}/generate — run arsenAI’s generator in-process against a stored experiment document and persist the resulting runs. Returns their UIDs.

Every mutating action from the UI hits an endpoint under the same authentication scope as the REST API, so if you already secure palaestrai serve behind a reverse proxy (TLS, HTTP basic auth, an identity-aware proxy, …) the Web UI inherits that same protection automatically.

Deployment notes

  • The Web UI ships as part of palaestrai and requires no extra install step. All static assets (Pico.css, HTMX, CodeMirror) are bundled under src/palaestrai/api/static/ and served from Python.

  • Runtime dependencies (FastAPI, Jinja2, uvicorn) are already pulled in by palaestrai serve; no additional packages are needed for the UI.

  • The Web UI writes to the same SQLite/PostgreSQL database configured in Runtime Configuration. Any Alembic migrations required by new UI features (e.g. the experiment_run_instances.user column, the templates table) are applied on server start.

  • When running behind a reverse proxy, make sure the proxy forwards the Upgrade/Connection headers on /ui if you use its auto-refreshing partials — HTMX itself is plain HTTP, but some proxies interfere with long-lived request patterns.