Install Guides

Prerequisites

Check these before you start — the installer verifies most of them and stops with an error rather than fixing them for you.

Elevated privileges. The installer configures system services, so it needs root on Linux (run the one-line command with sudo) and Administrator on Windows (the PowerShell installer self-elevates via a UAC prompt).
.NET 10 runtime. The ASP.NET Core Runtime 10.0 (Microsoft.AspNetCore.App 10.x) must already be installed. The install scripts check for it and stop if it is missing — they never install it. Get it from dotnet.microsoft.com.
Free ports. By default the instance services listen on 5005 (Application Service), 5006 (Workflow Service) and 5007 (management UI), plus an internal service port derived as app port + 100. All three are configurable — on the ports step of Setup.UI, or with --app-port / --workflow-port / --management-port on the CLI. The installer checks the ports and fails with SETUP-E005 if one is already taken or the same port is given twice. The web portal additionally uses 80/443.
Linux: a systemd-based x64 distribution, plus curl or wget. macOS and non-x64 architectures are not supported.
Windows: 64-bit Windows on x64. The CMD bridge additionally needs curl and PowerShell to be available.

Running behind nginx? The instance resolves its site by the Host header. Add proxy_set_header Host localhost; to the proxy location block that forwards to the instance — without it the site match fails and the browser shows an empty page.

Linux one-line install

Run as root. Everything after -- is passed to Setup.Bootstrapper unchanged:

curl -fsSL https://store.createrun.ai/installer/install.sh | sudo bash -s -- --accept-eula --instance-name Prod --mode prod

A fuller, non-interactive example (this is the same shape the script prints as its usage):

curl -fsSL https://store.createrun.ai/installer/install.sh | sudo bash -s -- \
  --json --accept-eula --mode prod --environment Prod \
  --install-dir /opt/createrun --instance-name Main01 \
  --organization <org> --account <email> --license-key <key>

What the script does

Resolves the current version from /installer/latest.
Reads /installer/{version}/manifest.json and takes the linux-x64 package checksum.
Downloads setup-{version}-linux-x64.tar.gz and verifies its SHA-256 against the manifest — a mismatch aborts the install.
Extracts the package and runs Setup.Bootstrapper, forwarding your arguments as-is.

Root is required because the installer creates systemd services and service users. Calling the script with no arguments prints a usage example and exits with code 1 — the script deliberately invents no installation arguments on your behalf.

The script works with either curl or wget; jq is used when available but is optional.

Windows PowerShell

Run from any PowerShell window — elevated or not:

& ([scriptblock]::Create((irm https://store.createrun.ai/installer/install.ps1))) --accept-eula --instance-name Prod --mode prod

The flow mirrors the Linux script: latest version → manifest → download setup-{version}-win-x64.zip → SHA-256 verification → extract → run Setup.Bootstrapper.exe with your arguments unchanged.

UAC self-elevation. If the shell is not running as Administrator, the script saves itself to your TEMP folder and relaunches through a UAC prompt, forwarding your arguments and returning the elevated run's exit code. Approve the prompt to continue; declining it cancels the install.

Select the destination with --install-dir. Running cd does not change the default root (C:\Createrun). Quote paths containing spaces:

& ([scriptblock]::Create((irm https://store.createrun.ai/installer/install.ps1))) --accept-eula --instance-name CRCOM --mode prod --install-dir "C:\Fix\Project\Createrun Instances\CRCOM"

Add --iis to provision the public portal through IIS. The management console runs independently of IIS. Choose a free --web-port when another site already uses port 80.

Installation errors. The one-liner leaves PowerShell open and sets $LASTEXITCODE. The transcript path is printed when available. If Windows reports a virus or potentially unwanted software, keep protection enabled and check Windows Security > Protection history. Report the installer version, detection name and package SHA-256 to the publisher; the package needs investigation before installation can continue.

Windows CMD

A thin bridge for plain cmd shells: it downloads the PowerShell installer and runs it, forwarding all arguments unchanged. PowerShell and curl must be present on the machine.

curl -fsSL https://store.createrun.ai/installer/install.cmd -o install.cmd
install.cmd --accept-eula --instance-name Prod --mode prod

Networks that block revocation checks. Some (typically corporate) networks block the endpoints Windows uses to check TLS certificate revocation, which makes the download fail with schannel errors 0x80092012 / 0x80092013. The bridge detects this and retries once with --ssl-revoke-best-effort — the soft-fail behavior browsers use. A certificate that is known to be revoked is still rejected.

GUI installer (Setup.UI)

Setup.UI is the desktop installer for people who prefer a wizard over a terminal. It drives the same install engine as the CLI and reads the same configuration, so the result is identical. Download it from the Download & Install page — if no Setup.UI package is listed there, a GUI build has not been published for the current version yet.

The wizard walks through four steps:

License agreement — review and accept the EULA.
Paths, license & ports — install directory, license key, and service ports (pre-filled with 5005 for the Application Service, 5006 for the Workflow Service and 5007 for the management UI; edit them here if those ports are taken).
Instance role & environment — whether this is the main instance, and the target environment.
Install — progress and result.

Setup.UI also offers a Remove & reinstall flow for an existing instance; the headless equivalent is the uninstall sub-command. Like the CLI, the GUI must run elevated.

CLI reference (Setup.Bootstrapper)

Setup.Bootstrapper owns every installation parameter. The install scripts above have no flags of their own — every argument you give them is handed to the Bootstrapper as-is, so this table is the complete reference for all install paths.

Argument syntax. Flags take the form --key value (a space between key and value). --key=value is not supported. Keys are case-insensitive. Boolean flags work by presence alone (e.g. --json). A value can never start with --; if a flag is given twice, the last value wins.

When a terminal is attached, the Bootstrapper prompts interactively for any core value you did not pass (license key, product, version, install folder) and asks you to confirm the EULA. The base URL is not among them: the install scripts always supply --base-url for the Store that served them.

Without an interactive terminal, --accept-eula is required. This covers --json, CI pipelines and any piped invocation. Acceptance is never assumed on your behalf, so the run stops with code EULA_REQUIRED and exit code 2. If you invoke Setup.Bootstrapper directly instead of through a script, the same rule applies to --base-url (code MISSING_ARGUMENT) — it is never silently defaulted, because a wrong Store address would install the wrong thing.

Failures never print a stack trace. Every error reports a one-line reason, a machine-readable code, a correlation id and the path of the log file that holds the full detail. Exit codes: 0 success, 1 install failure, 2 usage/argument error.

Flag	Default	Description
--json	off	Machine-readable mode: progress as JSONL lines on stdout plus one final result record. No interactive prompts.
--accept-eula	off	Accepts the license agreement. Required whenever stdin is not an interactive terminal (`--json`, CI, any piped run); without it the run exits `2` with `EULA_REQUIRED`.
--base-url	added by the install script	Base URL of the Store the installer talks to. The served scripts add it automatically, pointing at the Store you downloaded them from — pass it only to override. Calling `Setup.Bootstrapper` directly without a terminal and without this flag exits `2` with `MISSING_ARGUMENT`.
--license-key	(none)	License key used for activation and instance registration. Optional: activation is non-fatal, so a missing key only logs a warning.
--no-interactive-auth	off	Skips the interactive sign-in used to register the instance with the Store. Implied automatically when there is no terminal.
--register-client-secret	(none)	Machine-to-machine credential for unattended registration, for CI and air-gapped installs. Also readable from `CREATERUN_REGISTER_CLIENT_SECRET`. Interactive installs do not need it — they authenticate you instead.
--product-id	createrun	Product to install.
--version	1.0.0	Framework version to install.
--install-dir	C:\Createrun / /opt/createrun	Installation root (Windows / Linux defaults).
--instance-name	Default	Name of the instance being installed.
--app-port	5005	Port the Application Service listens on. It also determines the internal service port, derived as app port + 100 (5105 by default). A non-numeric or out-of-range value fails with `INVALID_PORT`; a port already in use — or one repeated across the three port flags — fails with `SETUP-E005`.
--workflow-port	5006	Port the Workflow Service listens on. Invalid values fail with `INVALID_PORT`; an occupied or duplicated port fails with `SETUP-E005`.
--management-port / --mgmt-port	5007	Port the instance management UI is served on. Invalid values fail with `INVALID_PORT`; an occupied or duplicated port fails with `SETUP-E005`.
--mode	prod	One of `dev` \| `test` \| `prod`. Selects runtime endpoint and activation defaults only; package signing and license validation are unaffected. An invalid value fails with `INVALID_MODE`.
--tier / --edition	community	One of `community` \| `professional` \| `enterprise`. Seeds the edition stamped at registration time; does not change the shipped binaries. An invalid value fails with `INVALID_EDITION`.
--environment	installer default	One of `Development` \| `Test` \| `Production`. Sent to the Store at registration for per-environment install quota.
--organization	(unset)	Owning organization the instance is paired with.
--account	(unset)	Owning Store account (email or account id) the instance binds to at registration. When absent, binding falls back to the license key.
--domain	(unset)	Public domain for the installed instance.
--template	(unset)	Path to a reference instance root. Seeds the new instance by copying that tree instead of downloading framework packages (container-style provisioning).
--db-host	(unset)	Re-points the database host in the seeded configuration; used together with `--template`.
--offline	off	Skip the Store and install directly from a local payload.
--online	off	Store only — disables the offline fallback.
--payload	(unset)	Path to an offline payload archive used by offline installs.
--force / --overwrite-existing	off	Reinstall over an existing framework version directory. Without it, installing an already-present version fails with `SETUP-E010`.
--skip-license	off	Development only: bypasses license activation. In release builds it is honored only when the environment variable `CREATERUN_SETUP_DEV_BYPASS=1` is set; otherwise it is ignored with a warning.
--skip-services	off	Skips system service registration (systemd / Windows services).
--telemetry-disable	off	Disables installer telemetry (for air-gapped or offline scenarios).
--otel-endpoint	http://localhost:4318	OTLP/HTTP endpoint installer telemetry is sent to.

Sub-commands

Command	Description
retry-register	Runs one retry pass over pending Store registrations from the persisted retry queue. Use it when the Store was unreachable at install time and the instance is not yet registered.
uninstall --instance <name> [--install-dir <dir>] [--delete-files] [--json]	Removes the instance's services (and its IIS site on Windows). Files on disk are removed only with `--delete-files`; without it they are kept.

./Setup.Bootstrapper uninstall --instance Main01 --delete-files

In --json mode the final result record carries a code field: OK on success, or EULA_REJECTED, INVALID_MODE, INVALID_EDITION, INVALID_PORT, INSTALL_ERROR, HEALTH_CHECK_FAILED on failure. On success the record also includes the installed version and the local portal URL.

After the install

A successful install continues automatically through this chain:

Registration. The instance registers with the Store and receives its instance token. If the Store is unreachable, the registration is queued — run Setup.Bootstrapper retry-register once connectivity is back.
Base applications. CRPortal is downloaded from the Store and verified before use: package SHA-256, ECDSA P-256 signature, and per-file checksums.
Services. The instance services are (re)started.
Management UI. Open the instance management UI at http://localhost:5007 — or whichever port you passed to --management-port.

Troubleshooting

Symptom	Cause	Fix
Windows service fails to start with error 1053, or sc.exe fails with code 5	Installer ran without elevation, or the deployed service is missing its runtimes/ native libraries	Re-run elevated (approve the UAC prompt the PowerShell installer shows). If the service still fails with 1053, re-run the installer so the package is deployed completely.
SETUP-E005	A port is already in use, or the same port was given twice across the three port flags	Pick different ports — on the Setup.UI ports step, or with --app-port / --workflow-port / --management-port — and re-run the installer. Freeing the conflicting port (stopping the process bound to it) also works.
Empty page behind nginx	Missing Host header — the instance matches its site by host name	Add proxy_set_header Host localhost; to the nginx location block and reload nginx.
Cannot reach the Store: connection timeout vs connection refused	Timeout usually means a provider/cloud firewall; refused usually means a local firewall (e.g. ufw)	For timeouts, open outbound HTTPS in your provider's firewall. For refused, check local firewall rules (ufw status) and allow the traffic.
A server hosting both the Store and an instance cannot reach its own public domain	Hairpin problem: the public domain resolves to the machine's own public IP, which the host cannot loop back to	Map the domain to loopback in /etc/hosts (e.g. 127.0.0.1 store.example.com).
Setup is killed mid-run, exit code 137	Out of memory — the kernel OOM killer terminated the installer	Free memory (or use a host with more RAM) and run the installer again.
SETUP-E010	The framework version is already installed in the target directory	Re-run with --force to overwrite the existing version directory.

Known limitations

An honest snapshot of what the installer does and does not do today.

Supported today

Linux x64 (systemd) and Windows x64 installs via script, GUI, or CLI.
Checksum-verified package download; signature-verified base application install.
Headless automation with --json (JSONL progress + final result record).
Service-level uninstall via the uninstall sub-command (file removal opt-in).

Not yet supported

Automatic database bootstrap on a fresh Linux host. The installer does not yet create or seed the PostgreSQL databases — they must be prepared before installing on a machine that has none.
Compiler service on Linux. The Compiler service is not part of the Linux install today.
Re-registering on reinstall. Reinstalling into the same instance has a known limitation: the instance's Store registration token is not automatically re-issued.
macOS and non-x64 architectures.