One-line runtime installer
Installs the aiswmm CLI runtime and prepares the local Agentic SWMM command
surface.
curl -fsSL https://aiswmm.com/install.sh | bash
Get started · stable v0.9.4
Choose the path you can reproduce.
Pick the path that fits your work — a one-line installer for the full local runtime, the aiswmm Python package, or the pinned Docker image for reproducible runs. The current stable point release is v0.9.4. Installer checks cover macOS, Linux, Windows x64, and Windows on ARM.
5 minguided local setup
10LLM provider routes
3routes with no API key
Dockerpinned solver environment
Install
Start with the one-line installer for your operating system. Python and Docker are available for package-managed or containerized workflows. Every command below has a copy button.
One-line runtime installer
Runs the Windows bootstrap path for the same local aiswmm runtime.
irm https://aiswmm.com/install.ps1 | iex
Install the aiswmm package
Use this path when Python 3.10 or newer is already available. The package supplies the CLI; local modelling also needs the SWMM solver, plus Node.js for MCP servers.
pip install aiswmm
Pin the exact version for any work whose results you intend to cite:
pip install aiswmm==0.9.4
Preview builds need an explicit opt-in:
pip install --pre aiswmm
Optional extras cover the Word report, the GIS stack, and bbox synthesis. Install all three at once with:
pip install "aiswmm[full]==0.9.4"
To update an existing pip-managed environment:
python -m pip install --upgrade "aiswmm==0.9.4"
Reproducible container
Bundles the EPA SWMM solver and Python environment in a fixed container — the recommended path for reproducible or production runs.
docker pull ghcr.io/zhonghao1995/agentic-swmm-workflow:v0.9.4
Run the acceptance benchmarks, mounting a local directory for the artifacts:
mkdir -p agentic-swmm-runs docker run --rm -v "$PWD/agentic-swmm-runs:/app/runs" ghcr.io/zhonghao1995/agentic-swmm-workflow:v0.9.4 acceptance
After installation
The installer hands over to the setup wizard. It lists every provider route and detects what is already running on the machine — you are not asked to supply an API key before you can see the options:
aiswmm setup aiswmm doctor
Then launch the interactive runtime and describe the SWMM task in a sentence:
aiswmm
With SWMMCanada enabled in setup, try the published Kelowna request inside the interactive shell:
Do the whole job for downtown Kelowna BC, rainfall period November 1 to November 4 2023: get the model, run it, audit it and write the report, in one go.
The request fetches a model from the configured service and asks for approval before sending the area. Inspect the published case, model, and evidence limits before interpreting the output. For the interactive shell with the safe permission profile:
aiswmm --safe
Ten routes, three of them keyless
OpenAI, Anthropic, OpenRouter, DeepSeek, Groq, Gemini, local Ollama, local LM Studio, OpenAI-compatible gateways, and custom endpoints. If you already pay for a ChatGPT plan, a local gateway fronts it and no API key is needed:
aiswmm gateway login
The gateway build is chosen for the running OS and architecture, verified against the release’s own checksums, and a mismatch writes nothing. For a route that takes a key directly, see API key configuration.
Record the provider and model identifier alongside the software version. A fixed model snapshot reduces changes in planning behaviour; byte-identical reproducibility is a claim about the verified SWMM execution path, not the LLM conversation.
Keep API keys outside the conversation. Configure them during setup or in your shell
environment. Never paste an API key into the aiswmm conversation, and rotate any
key that is accidentally pasted into an agent prompt.
If something goes wrong
Three ways in — one-line installer, Docker, or pip — are compared side by side in
choosing
an install path. When an install fails on a real machine, the
install
and troubleshooting guide gives the reason behind each failure rather than a ritual, and
names which platforms are covered by an install job in CI.
Review the installer first
The one-line installers pipe a remote script straight into your shell. To see what runs before it runs, fetch the script first — these commands download the installer without executing it:
Review the macOS / Linux installer script
curl -fsSL https://aiswmm.com/install.sh
Review the Windows PowerShell installer script
irm https://aiswmm.com/install.ps1
For a reproducible install, pin a release tag before running:
curl -fsSL https://aiswmm.com/install.sh | AISWMM_INSTALL_REF=v0.9.4 bash
Agent runtimes — Codex / Claude / OpenClaw / Hermes
Beyond its own aiswmm runtime, the Agentic SWMM workflow can be driven by external agent
runtimes — Codex, Claude Code, OpenClaw, or Hermes. The repository's MCP servers and Skills work
across these orchestration targets.
For an agent-orchestrated run, preload the agent/memory/ package and point the runtime
at the top-level entry skill skills/swmm-end-to-end/SKILL.md, which decides which
workflow path to take, which QA gates must pass, and when to stop rather than invent missing
inputs.
Install the repository's portable skills into Codex, Claude Code, OpenCode, or another skills-aware runtime:
npx skills add Zhonghao1995/agentic-swmm-workflow
The skills carry workflow and evidence contracts. Pair them with the project install above for the executable aiswmm, SWMM solver, and MCP toolchain.
See the Codex runtime path and the OpenClaw execution path for the full tool-call sequence.
Releases and documentation
Browse the changelog, download release artifacts, or read the full installation and CLI guide.