Skip to content

CLI run control and server setup

For everyday Console tasks, use first run, monitoring, existing runs or recovery. This page owns CLI control and server configuration.

These commands operate on a validated project or a specific run directory. Replace my-project, my-runs and my-run with your paths. Keep the actual run directory printed by the command; do not guess the generated run ID.

Start and inspect

For a first Console walkthrough, choose Load Example → EX06 · Evaluation baseline. This microsatellite concept exercises the actual solver and assessment workflow with complete inputs; model warnings remain visible. New Console workspaces select it by default. EX12 · Tight-envelope diagnostic deliberately fails its launch-width check; EX13 changes that one limit and demonstrates the corrected result.

Validate checks the saved inputs and reports configuration gaps before any solver runs: unsupported solver inputs, architecture definitions, incompatible subsystem selections and missing required ADCS hardware. Inputs valid means the input contract is valid; it does not guarantee physical feasibility. Clicking Run also performs these checks. New warnings open Before you run and pause launch; correct the configuration or choose Run with warnings to investigate a partial design. Schema/reference errors still prevent launch.

Placement, sizing, energy balance and engineering margins need solver results. A completed run can therefore still fail engineering checks: Evaluation shows Not ready to score, a visible list of blocking findings with suggested actions, and Inspect checks for the full captured evidence. Correct the relevant inputs and run a new design; the previous run and its assessment remain available.

In the Console, each new run retains its own inputs and results automatically. On Configure, open an editable project and enter optional Run name and Tags above the run controls before clicking Run. Separate tags with commas. The labels are saved with the new run, without changing or saving the YAML. Pending labels stay with that project while navigating within the Console; they survive a failed launch attempt and clear after a successful launch. Refreshing before launch clears these unsaved labels.

Use the Edit run pencil icon in Run monitor, a result header or a comparison card to change them later, including for imported runs. Names may contain up to 80 characters; use up to eight tags of 32 characters each. Clear the name to restore its default display label. Renaming applies to Console-launched and imported runs.

Names and tags appear in run history and the comparison chooser; comparison charts use the run names. Choose designs → Find designs searches names, tags and run IDs. Open existing run also shows names for registered bundles.

These labels persist in this Console's local database across restarts. They do not rename result folders, change captured inputs or scores, or invalidate saved comparison links. They are not included in exported run bundles; retain the Console database if you need to preserve them. If a second tab changes a label first, reload the latest details before saving again.

If Console cannot read its workspace, follow Console store recovery. Preserve the current state before trying a backup; an older backup may not contain recent changes.

sindri validate-project my-project/study.yaml
sindri run my-project/study.yaml --output-root my-runs --timeout 300
sindri status my-run
sindri status my-run --json

The optional timeout is a positive monotonic execution deadline in seconds, not a mission duration or part of the study's engineering intent. The run command returns a nonzero status for failed, incomplete or cancelled outcomes. Preserve its bundle and diagnostics instead of ignoring the exit code.

status reads the last committed execution state. It reports information from the verified bundle, not an uncommitted live value. A stale heartbeat does not by itself mean the writer process is dead. An unreadable/corrupt bundle is an integrity problem, not a result to reinterpret as a failed engineering constraint.

Monitor a run

Use the Console's bottom monitor for recorded stage activity, cancellation and optional logs. Follow monitor progress and logs for the visual workflow. Status reads and logs do not establish engineering feasibility.

Open an existing run

Follow find and open an existing run for saved locations, folder navigation, scoped search, naming and read-only opening.

For a remote server, set SINDRI_CONSOLE_RUN_ROOTS to the directories you intend to share before starting Console (separate multiple paths with : on POSIX). Without configured locations, remote folder browsing is unavailable. Saved locations outside the current allowlist are retained but hidden and cannot authorize discovery or reopening imported runs. A shared token cannot expand that allowlist. Configured locations cannot be forgotten in the picker.

Request cancellation

sindri cancel my-run --reason operator_requested

Cancellation is cooperative: it records a request for the running local writer to observe at supported control points. It is not an immediate process kill. Inspect status again and retain the terminal bundle. Do not delete lease or control files to force an alternate execution outcome.

Resume an interrupted run

sindri resume my-run --timeout 300

Resume applies only to an interrupted running format-2 bundle with an exact compatible execution fingerprint and a stale eligible lease. A live same-host writer cannot be displaced simply because its heartbeat is old. A cancellation request or incompatible graph, resources, application/executors, seed, checkpoint schemas or relevant tools can prevent recovery.

Preflight refusal is read-only. Compatible recovery uses verified JSON checkpoints/safe points in the same run; it is not a general cache. If terminal journal state was already committed but manifest finalization was interrupted, recovery only finalizes the manifest rather than rerunning the solvers.

A terminal failed or cancelled run is not resumed in place. Inspect the reason; use a new corrected project run, or replay a compatible terminal snapshot when that is the intended experiment.

Replay a terminal snapshot

sindri replay my-run --output-root replay-runs --timeout 300

Replay verifies a terminal format-2 source snapshot and required captured resources, creates a fresh lineage-linked bundle, and executes the work again. It does not copy old results or checkpoints into a new success. The source stays unchanged. Runtime/resource incompatibility may be refused; replay is not an automatic migration to arbitrary future software.

Troubleshooting route

Observation Next step
Project rejected Read the field/reference/resource diagnostic and validate again after correction
Run completed but assessment failed Inspect the owning result's checks and method assumptions
Result skipped Follow unsatisfied prerequisites to the first relevant failure
Result absent/partial Preserve that availability state and inspect the journal/issues
Bundle integrity rejected Preserve the original files and seek the correct complete bundle; do not edit digests
Recovery refused Read the compatibility/lease/cancellation reason; do not force a claim

See EX05 for an executed failure diagnosis and bundle semantics before sharing partial results.

Use the Console from another machine

The same Console serves both the web UI and every run/evaluation action. For local use, run sindri console and open the private URL printed by the launcher. Its operator credential authorizes local writes for that server session; the browser removes it from the address bar. A server restart requires the new launcher URL. Local reads remain available without it.

To share it over an encrypted VPN (including Tailscale) or a trusted private network, run on the server:

sindri console --host 0.0.0.0 --allow-http --project-root /path/to/projects

On that server, retrieve its persistent token:

sindri console token

Open http://SERVER-IP:8765 in your browser, paste the token into Connect to Sindri, and click Connect. Remember this browser keeps the connection for 30 days; unchecked, it lasts at most 24 hours with a session cookie. There is no separate API address or user account. Configure, naming, launch, cancellation, evaluation, comparison, saving and evidence downloads all use this connection. The token grants access to the server's configured workspace and trusted roots. It is a shared workspace, not separate accounts or roles.

Use Disconnect in the top bar to revoke this browser's session. If a session expires, reconnect and retry the last action; the current page and unsaved edits stay in place. Actions are never replayed automatically. To revoke every session and issue a new token, run sindri console token --rotate; no restart is needed.

The server automatically creates a private token file in its state directory (~/.local/state/sindri/console.token on a default Linux setup). It reuses that token across restarts. --token-file /private/server.token selects a different file for both the server and token command. An existing token must have 32–256 printable ASCII characters; prefer the generated random value. Keep credential files private (permissions 600 on Unix).

Optional setup:

  • Add --allow-client 192.168.1.25 or --allow-client 192.168.1.0/24 to restrict allowed client IPs; repeat for multiple addresses/networks. A token is still required. IPv6 addresses/CIDRs are supported. Client IP comes from the socket, not forwarded headers.
  • For direct HTTPS, replace --allow-http with --ssl-certfile cert.pem --ssl-keyfile key.pem and use the HTTPS address. Plain HTTP sends the token and session without transport encryption; use it only on a trusted network or encrypted VPN.
  • To keep a service configuration, set SINDRI_CONSOLE_HOST, SINDRI_CONSOLE_TOKEN_FILE, SINDRI_CONSOLE_ALLOW_HTTP=true and optionally comma-separated SINDRI_CONSOLE_ALLOW_CLIENTS in its environment, then run sindri console. Leave these unset for default local-only use.
  • Behind a same-origin HTTPS reverse proxy, bind Sindri to 127.0.0.1, set --public-origin https://sindri.example (or SINDRI_CONSOLE_PUBLIC_ORIGIN), and preserve that Host header. Token authentication still applies. Restrict the proxy's clients at the proxy/firewall: Sindri's IP filter sees the proxy's socket address. Automatic forwarded-header trust is disabled.

Files and result paths always refer to the server. Existing filesystem-root and engineering checks still apply after connecting. Binding a network address never creates an unauthenticated server; missing/invalid access settings fail closed.