Run an allowlisted command
The web console is a small, opt-in power-user surface. It composes one of five allowlisted WS4 commands from typed fields and launches it as an argv array. It is not a shell, a terminal, or a Python evaluator.
Enable it only on a trusted or loopback service:
export WS4_CONSOLE_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
ws4 serve --dataset build/compiled --runs runs --targets targets.yaml \
--allow-console --console-root /path/to/instance --allow-runs
The token is required on every console endpoint as Authorization: Bearer <token>.
The browser stores it in sessionStorage for the current tab; it is never placed in a
URL or written to an audit record. Without --allow-console the console API does not
exist and the browser does not show the Console workspace. --console-token may
also be supplied directly; the environment variable is preferred so the secret stays out
of the process argument list.
On the public portal, setting WS4_CONSOLE_TOKEN enables the same console for every
mounted instance. Leaving it unset keeps the public demo read-only and the Console
workspace absent.
What is allowed
Sandboxed Python tier
--allow-console-python adds a second, explicitly reviewed tier for WS4 Python API
scripts. It requires --allow-console and a host with Landlock and unshare
(--console-root still defines the read-only inputs). On the public portal,
WS4_CONSOLE_PYTHON=1 enables it alongside WS4_CONSOLE_TOKEN.
ws4 serve --dataset build/compiled --runs runs --targets targets.yaml \
--allow-console --allow-console-python \
--console-token "$WS4_CONSOLE_TOKEN" --console-root /path/to/instance
The browser shows a script editor, an input-path field, and a required I reviewed this script checkbox. The API equivalent is:
response = requests.post(
"http://127.0.0.1:8000/api/console/python/jobs",
headers={"Authorization": f"Bearer {token}"},
json={
"script": "from ws4.opt.objective import load_targets\nprint('reviewed')\n",
"inputs": ["/srv/instance/config/ws4/targets/evenflow.yaml"],
"reviewed": True,
},
timeout=10,
)
The script can read the selected inputs, the mounted dataset, the installed WS4 package, and its own scratch directory. It can write only scratch. The worker applies:
Landlock filesystem rules (the policy denies everything not explicitly allowed);
a new user, PID, and network namespace through
unshare;no inherited console token or host credentials;
address-space, CPU, file-size, process, and open-file resource limits;
the console’s wall-clock, output, concurrency, and rate limits.
If Landlock or a functional unshare cannot be demonstrated, the job is refused. There is no unsandboxed Python fallback. This tier does not install packages, allow network access, or run an interactive terminal; assistant-authored scripts still require the review flow before submission.
Assistant-staged scripts
The embedded assistant may end a reply with a stage_script chip. That chip carries
bounded Python source to the browser, opens the Console workspace, and fills the script
editor. It deliberately clears the review checkbox and does not call the job API. The
user must read the code, tick I reviewed this script, and select Run reviewed
script before the Landlock sandbox starts it.
The chat agent cannot inherit WS4_CONSOLE_TOKEN or WS4_CONSOLE_PYTHON from the
service environment, so it cannot call the console API on its own. Staging is a
convenience only; it is not approval.
The console can launch these command families:
Command |
Typed inputs |
|---|---|
|
schedule CSV, years. |
|
targets, initial schedule, years, iterations, time limit, seed, engine, islands, and LNS weights. |
|
targets, candidate index or candidate cache, initial schedule, seed state, years, iterations, period width, watched accounts, and LNS weights. |
|
targets, seed schedule, effect table, cache directory, seeds, years, population, generations, and device. |
|
an existing run directory and optional targets. |
Every command writes into a fresh runs/console-<timestamp>-<id>/ directory. The
console supplies --out, --out-dir, --json-out, --schedule-out, and
--summary-out; a caller cannot choose the output path. Artifacts are listed and
downloadable from the Console panel.
The console does not run ws4 serve, package installation, arbitrary Python, raw
bash, pipes, redirection, command substitution, or network clients. Those remain
outside this tier; the Python sandbox is a separate, later boundary.
Security boundary
Requests are typed and unknown fields are rejected before launch.
Inputs are resolved with
strict=Trueand must stay inside the configured read-only roots. Path traversal, missing inputs, and unknown flags are rejected.Output paths are server-owned scratch paths.
The child process is launched with
shell=False, a cleaned environment, and its own process group. There is no shell interpretation of any field.One job runs at a time by default; the sliding-window limit is six starts per minute.
Each job has a 180-second wall clock limit and a one-megabyte captured-output limit. Exceeding either terminates the process group and marks the job failed.
Each completed job appends one line to
runs/console-audit.jsonlwith the workspace, command, argv, dataset fingerprint, start/end time, exit status, and artifact paths.
The token is an access gate, not a multi-user account system. Run the service behind the host’s normal authentication and network controls. The allowlisted CLI tier does not provide a kernel sandbox or network namespace; do not enable it on an untrusted public host. That stronger boundary belongs to the Python job-runner tier.
Trying it in the browser
1. Open Console. The workspace is visible only when the service exposes the feature.
2. Enter the token and select Connect. The command picker and typed fields load.
3. Pick ``report``, leave the newest run directory in the field, and select Run job. The output appears in the Console panel, and the report CSV/JSON files appear under Artifacts. A rejected field, such as a path outside the configured roots, returns a validation message before any process starts.
From Python, the same contract is a JSON request:
import requests
headers = {"Authorization": f"Bearer {token}"}
response = requests.post(
"http://127.0.0.1:8000/api/console/jobs",
headers=headers,
json={"command": "report", "run": "/srv/runs/run1"},
timeout=10,
)
job = response.json()
Poll /api/console/jobs/{id} for status, /api/console/jobs/{id}/output?offset=N for
captured output, and /api/console/jobs/{id}/artifacts for the scratch files.