Guides

Deploy the app

A workspace is your own Cascade app in your Sail account: the Sail app cascade-<name> with one sandbox, cascade-main, that runs the app and forks a sandbox per sim. Create it from the browser, or with cascade deploy from a checkout.

Get started in the browser#

Open Get started, pick a workspace name, and paste a Sail API key from the Sail dashboard. The page shows each step as it happens and ends with an Open my workspace link that logs you in, the token, the S3 endpoint and ready-made upload commands. Nothing to clone.

The key creates the workspace in your Sail account. Cascade doesn't store it. It is copied into the workspace, because the app needs it to checkpoint itself and fork sims.
The workspace boots the published image, ghcr.io/atoniolo76/cascade:latest, with the stand-in simulator. Set another public image under advanced.
Manage, at the bottom of the page, shows a workspace's status, pauses and resumes it, and deletes it.

Deploy from the command line#

cascade deploy does the same from a checkout. It is safe to rerun: it finds the workspace's sandbox, resumes it if it's paused, and prints the same URLs and token again.

bash

git clone https://github.com/atoniolo76/cascade.git
cd cascade
export SAIL_API_KEY=...
uv run --extra sail cascade deploy --workspace acme-lab

When the app answers, it prints what you need.

text

cascade-acme-lab: starting Cascade
cascade-acme-lab: healthy
sailbox:  <sailbox id>
app:      https://<app url>
s3:       https://<s3 url>  (bucket cascade, prefix accelsim-traces, path-style, unsigned)
token:    <token>
open:     https://<app url>/#token=<token>
logs:     /data/cascade-serve.log inside the sailbox

output	use it for
app (port 8000)	The web UI and the API. The `open:` link logs the browser in with the token.
s3 (port 9000)	Pass it to the profiler as `--s3-endpoint`. Traces upload here, unsigned and path-style.
token	The `CASCADE_TOKEN` for the UI, the API and your agent. Set `CASCADE_TOKEN` before the first deploy to choose it.

Deploy with a simulator image#

To simulate your traces instead of replaying the stand-in, build the app on top of a simulator image and tell it where things are inside it. --from-source builds this checkout's Dockerfile on Sail, which takes a few minutes the first time.

bash

uv run --extra sail cascade deploy --workspace acme-lab --from-source \
  --base-image <simulator-image> \
  --sim-cmd "/app/.venv/bin/cascade worker" \
  --accelsim-dir <path to accel-sim in that image>

cascade worker runs <accelsim-dir>/gpu-simulator/bin/release/accel-sim.out on the trace with the sim's config. If the image keeps the post-processor somewhere other than <accelsim-dir>/util/tracer_nvbit/tracer_tool/traces-processing/post-traces-processing, add --postprocess-cmd. Bring your own simulator lists what the image needs. The simulator settings are written once, when the workspace is first created. To change them, delete the workspace and deploy again.

Without --base-image, --sim-cmd and --accelsim-dir, every sim runs cascade worker --replay, which replays a real Accel-Sim run of facebook/opt-125m on SM90_H100 (20 vLLM kernels, from results/20261108-021007-opt125m-h100-accelsim/). It doesn't simulate your trace, and its numbers are the same for every trace. The image is plain ubuntu:22.04, so it has no post-processor. Upload traces that already contain traces/kernelslist.g, or they fail in processing.

Flags#

flag	default	what it sets
`--workspace`	required	3 to 32 lowercase letters, digits and hyphens. The Sail app is `cascade-<workspace>`, and the UI shows the name in its rail.
`--image`	`ghcr.io/atoniolo76/cascade:latest`	The public app image to boot.
`--from-source`	off	Build this checkout's `Dockerfile` on Sail instead of pulling `--image`.
`--base-image`	`ubuntu:22.04`	The Dockerfile's `BASE_IMAGE`. Only with `--from-source`.
`--sim-cmd`	`cascade worker --replay` on the OPT-125m H100 log	`CASCADE_SIM_CMD`, the command each sim runs.
`--accelsim-dir`	`/app/tests/fixtures/accelsim`	`CASCADE_ACCELSIM_DIR`. The default holds real Accel-Sim configs but no simulator.
`--postprocess-cmd`	derived from `--accelsim-dir`	`CASCADE_POSTPROCESS_CMD`.
`--disk-gib`	Sail's default	The app sandbox's disk limit. Sims fork this disk, so size it for your traces.

What's in the image#

The Dockerfile builds the web UI with Node 22, then layers the app onto BASE_IMAGE: rclone 1.76.0, uv with Python 3.12, the app at /app, and the Accel-Sim configs and logs from tests/fixtures. CI publishes it to ghcr.io/atoniolo76/cascade on every push to amani that changes the app. The app sandbox and every sim fork run this one image. Sail doesn't run the image's CMD, so the deploy writes the app's settings, including your SAIL_API_KEY, to /data/cascade.env (mode 600) and starts cascade serve --sims sail with them.

The sandbox has auto-sleep turned off, so the app keeps running while sims report in. Pause it from Manage on Get started when you aren't using it.

Configuration#

cascade serve reads these environment variables. The table is generated from cascade/settings.py.

variable	default	what it sets
`CASCADE_TOKEN`	required	The shared bearer token. The UI and every sim send it. The app refuses to start without it unless `CASCADE_NO_AUTH` is set.
`CASCADE_NO_AUTH`	false	Local development only. Set to `1` to turn off the token check: the API accepts any request, `/api/health` reports `auth: false`, and the web UI skips its token screen. Never set it on a deployment someone else can reach.
`CASCADE_ACCELSIM_DIR`	`/opt/accel-sim-framework`	Accel-Sim checkout. The app reads GPU configs from `gpu-simulator/gpgpu-sim/configs/tested-cfgs/*/gpgpusim.config` under it.
`CASCADE_OPENAI_WAIT_S`	`3600`	Seconds `/v1` and `/api/scenarios` wait for base-simulation step timing. A timeout returns 504 with the run/sim IDs; it does not cancel the simulation.
`CASCADE_S3_BUCKET`	`cascade`	The bucket the profiler uploads to. It is a directory under `$CASCADE_DATA_DIR/s3/`.
`CASCADE_DATA_DIR`	`/data`	Where the app keeps `cascade.db`, the S3 bucket directory `s3/`, sims' output files in `files/`, and scratch files in `work/`.
`CASCADE_SIM_CMD`	none	The command each sim runs. On Sail it runs through a shell. Locally it is split into arguments and run without one. Without it, every sim fails at launch.
`CASCADE_POSTPROCESS_CMD`	`$CASCADE_ACCELSIM_DIR/util/tracer_nvbit/tracer_tool/traces-processing/post-traces-processing`	Accel-Sim's trace post-processor. The app runs it once per trace as `<cmd> <trace>/traces -j <cpus>`.
`CASCADE_HEARTBEAT_TIMEOUT_S`	`60`	Seconds without a heartbeat before a sim becomes `lost`. After 10 times this, a `lost` sim becomes `failed`.
`CASCADE_RUN_S3`	`true`	Whether `cascade serve` starts `rclone serve s3` next to the app. Set `false` to run the S3 endpoint yourself.
`CASCADE_WORKSPACE`	none	The workspace's name. `/api/health` returns it and the web UI shows it in the rail. `cascade deploy` and the Get started page set it.
`CASCADE_SAMPLES`	`true`	Whether `cascade serve` seeds the bundled sample trace and run (`samples/`) into the workspace on startup. Set `false` to start empty. A sample already seeded stays.
`CASCADE_PUBLIC_URL`	`http://127.0.0.1:8000`	The URL sims use to reach the app. Each sim gets it as `CASCADE_MAIN_URL`.
`CASCADE_S3_PREFIX`	`accelsim-traces`	The key prefix traces live under. Each trace is `<prefix>/<run_name>/`.
`CASCADE_S3_PUBLIC_URL`	none	The S3 endpoint the profiler uploads to. `/api/health` returns it as `s3_endpoint` and the UI fills it into the send-a-trace command. `cascade deploy` sets it; a local `cascade serve` derives it from `CASCADE_PUBLIC_URL`'s host and `--s3-port`.

cascade serve takes --host (default 0.0.0.0), --port (default 8000), --s3-port (default 9000) and --sims. --sims local, the default, runs each sim as a subprocess of the app. --sims sail forks a Sail sandbox per sim.

The S3 endpoint accepts anonymous reads and writes. Anyone with its URL can upload a trace. The app's API and UI need the token.