Quick Start

This guide takes you from a clean checkout to a running Consystence server with a live, simulated process to explore. It assumes you have read the core concepts and have a development environment set up — see Installation for the full prerequisite list.

By the end you will have:

1. The server running on port 8080.
2. The demo organisation and site imported from its declarative tenant.yaml.
3. The opt-in Dam Water Transfer demo station, running against the built-in simulator.

Prerequisites

• .NET 10 SDK — the server is a single .NET 10 / Orleans application.
• Node.js 22+ — to build the front-end assets (Tailwind CSS v3 + esbuild bundle) into the server’s wwwroot/.
• PostgreSQL 16 (optional in development) — Orleans clustering and persistence. Development runs use in-memory storage by default, so you can skip this for a first look.

1. Start the server

Build the browser assets once, then run the server. From the repository root:

# Front-end assets → backend/Server/Consystence.Server/wwwroot/
cd frontend
npm install
npm run build:all

# Run the server (dev launch profile binds 0.0.0.0:8080)
cd ..
dotnet run --project backend/Server/Consystence.Server

The server listens on http://localhost:8080. A from-source build is a Site-mode server: the deployment mode is baked into the artifact at build time, not read from configuration. See the org and site model for what the modes mean.

Prefer a container?

Tagged releases will publish a Site-baked image, ghcr.io/consystence/site-server, listening on the same 8080 (the Cloud-baked image is never publicly distributed) — the first packaged release has not shipped yet, so build from source during the beta. See Deployment and Cloud (Azure).

Development does not auto-seed the Dam Water Transfer demo: on a clean checkout the server boots with no tenant (the development profile’s default bootstrap path is skipped with a warning when the file is absent). The next sections import the demo tenant and bring it to life.

2. How servers are activated

There is no setup wizard: the legacy Fresh Install Wizard and its /api/setup/wizard/* endpoints were retired. A site server that has not yet been activated renders a static “Server not activated” notice, and onboarding is code-keyed site activation — there is deliberately no interactive sign-in at the server. Activation codes are issued by the account plane against a site already declared in the tenant’s site registry (the registry is capped by the tenant’s licence tier). The installer presents the one-time code to POST /api/setup/site-activation; the server relays the code and its write-once install id to its cloud cell, which redeems the code at the account service, activates the specific pre-declared site the code was issued for, and returns the site’s org, site, and cloud-sync credentials:

flowchart LR
  A[One-time<br/>activation code] --> B[Site server<br/>POST /api/setup/site-activation]
  B --> C[Cloud cell<br/>POST /api/provision/site-activation]
  C --> D[Account service<br/>redeems code]
  D --> E[Site configured<br/>sync key issued]

The surviving setup surface is exactly GET /api/setup/status, POST /api/setup/site-activation, and POST /api/setup/reset (see the API reference). Identity lives in the account plane: sign-in is via Entra External ID (CIAM) at id.consystence.com, membership is keyed by the Entra oid, and organisations are keyed by an account-minted UUID (org_*). See Authentication for the full auth model.

Not yet generally available

Activation codes come from the account plane (account.consystence.com), where you can sign up, create an organisation, and provision a sandbox tenant — though sandbox and trial tenants are simulation-only and cannot activate a site server. The account plane runs in production behind launch gates; Consystence is in public beta, and new tenants can wait on operator approval.

For a local development run you skip activation entirely: pointing the server’s tenant bootstrap at a tenant.yaml (next section) both provisions the org and site and marks the install configured.

3. Import the Dam Water Transfer demo

The demo ships as a declarative tenant file, bootstrap/dam-pump-station/tenant.yaml, describing the Dam Water Transfer station — a single-pump dam transfer process, driven by the built-in deterministic simulator rather than real hardware.

To run it locally, point the server’s tenant bootstrap at the file. Set it in appsettings.Local.json — a gitignored overrides file the server loads on top of the built-in settings — in the server project directory:

backend/Server/Consystence.Server/appsettings.Local.json

{
  "Tenant": {
    "BootstrapPath": "../../../bootstrap/dam-pump-station/tenant.yaml"
  }
}

The path is resolved relative to the server’s content root. Then run the server as in step 1:

dotnet run --project backend/Server/Consystence.Server

On startup the server imports the org (demo) and its site (dam-pump-station), marks the install configured, and — because the Development simulation config auto-starts dam-pump-station — begins ticking the simulated process.

The station is composed of seven device instances — six process devices plus a PID controller — each an instance of a reusable device type (see the type system). Instances are per-site and identified by their asset number:

Asset	Device type	Role
PP-01	consystence.pump.centrifugal	Transfer pump
VL-01	consystence.valve.motorised	Inlet isolation valve
VL-02	consystence.valve.motorised	Discharge isolation valve
FT-01	consystence.sensor.flow	Discharge flow
PT-01	consystence.sensor.pressure	Discharge pressure
LT-01	consystence.sensor.level	Dam level
PID-001	consystence.pid.controller	Discharge pressure control

The tenant file also carries the station’s electrical model (incomer, transformer, MCC, and drives) alongside the process devices.

The simulator couples these instances so the process behaves realistically: a constant inflow fills the source dam (LT-01) and running the pump (PP-01) draws it down. The pump’s flow output feeds the flow sensor (FT-01) and its discharge pressure feeds the pressure sensor (PT-01), so starting and stopping the pump moves every reading on the scene.

Note

The local tenant bootstrap involves no licence at all. See Licensing for how licences work on activated installations — licensing degrades rather than kills, and never gates operator control writes.

4. Explore the demo site

Open http://localhost:8080. Once the install is configured, the server-driven UI lands on the overview view for the resolved site: a semantic UI tree rendered to your browser over SignalR, so the process scene updates live as the simulator ticks.

Things to try:

• Watch the dam level, flow, and pressure readings change as the simulated process runs.
• Open the pump (PP-01) and valves (VL-01 / VL-02) to issue start/stop and open/close commands and see the scene respond.
• Inspect a device instance to see its tags, data types, and physical roles — the building blocks described in Device types and Tags.

AI is advisory only

Consystence AI configures, queries, classifies, and explains — it never commands equipment. Control commands you issue in the demo come from you, not from the AI, and on real installations hard interlocks live in deterministic controller logic and hardwired safety relays — not in the server or AI path.

CLI alternative

To provision a running server declaratively rather than via its bootstrap config, use the csy CLI. Authenticate, then import an org-and-site definition from a YAML file into a target organisation:

csy auth login
csy tenant import tenant.yaml --org <org-slug>

tenant import resolves its target org from --org or the currently selected tenant (csy tenant select <slug>); with neither, it aborts rather than guessing. The tenant.yaml describes the organisation, its sites, controllers, and device instances in one file — the same shape that backs the Dam Water Transfer demo. This is also how platform administrators onboard tenants. For the underlying REST endpoints, see Provisioning and the API reference.

Next steps

• Core concepts — orgs, sites, device types vs instances.
• Device types — model your own equipment.
• Edge runtime — connect a real controller via the PLCnext border gateway.
• API — automate everything you just did by hand.