Self-Hosting Quick Start

This page takes you from nothing to a working Semantius platform on your own machine. It uses the built-in sign-in system, so there is nothing to register anywhere and no accounts to create first. Budget about five minutes, most of which is Docker downloading images.

This page covers the local-semantius-idp variant. For Microsoft sign-in, follow Microsoft Entra ID instead. For a Dokploy server, follow Dokploy. Choose or Build Your Variant explains the variants and how to choose.

Before you start, make sure Docker and Git are installed and Docker is running. On Windows and macOS that means Docker Desktop is open; on Linux it means the Docker service is running and you can run docker ps without an error.

Running this with a coding agent? It can do every step except step 4, which needs a person in a browser. The agent should stop there and hand the address to you.

1. Get the Files

Then move into the setup you want to run. For a first install, that is the local one with the built-in sign-in system:

Everything from here on happens inside that folder. The commands act on the files sitting next to them, so running them from anywhere else will not work.

2. Create Your Settings File

On Windows, run setup-env.cmd instead.

This writes a file called .env next to the others. It is your copy of the settings, it is never sent anywhere, and it is the only file in the folder you are meant to edit.

The important part is what it puts in there. Three values are unique to your installation: the database password, the password the API logs in with, and the key that protects your sign-in sessions. The script generates fresh random values for all three. The example file ships with obvious placeholder values, and copying that file by hand instead of running this script would leave you running on passwords that are published on the internet.

You can open .env and look it over now. For a local install you do not need to change anything in it.

3. Start Everything

On Windows, run create.cmd.

This downloads the images, creates a fresh database, and starts everything. The first run takes a few minutes because of the downloads. Later runs are much faster.

If you skipped step 2, create stops with “No .env” and tells you to run setup-env first. It never writes the settings file itself, because that would mean a start command quietly choosing your passwords.

While it runs you will see each piece report itself as healthy. The database takes the longest on a first run, because it is installing itself from scratch.

When a database already exists, create asks before deleting it. Scripts, agents and CI runs cannot answer that prompt, so they pass -y (or set ASSUME_YES=1 or CI=true) to skip it. A first install has nothing to delete, so it never asks.

To check that everything came up, run these two commands. The first should list every service as healthy, and the second should print a short JSON document:

4. Sign In and Create Your Account

This step needs a person in a browser. It cannot be scripted, because it creates the administrator account. An agent should hand over the address here and ask you to confirm when you are signed in.

Open http://localhost:3000 in a browser.

The app sends you to a sign-in page. Because the user list is still empty, this page doubles as the first-run setup page: fill it in, and the account you create becomes the administrator. You are then returned to the app, signed in.

There is no default account and no password hidden in a config file. Whoever sets up the account first is the owner of the installation, which is why you should do this step right after starting the stack rather than leaving it open on a shared network.

5. Look Around

You now have a complete platform running. A few places worth visiting:

• http://localhost:3000 is the app itself. The Northwind sample dataset is loaded by default, so there is real data to click through from the start.
• http://localhost:3000/api-docs/ lists every API endpoint your model generates, with a Test Request button on each one. Because you are already signed in, those test calls just work, with no key to paste.
• http://localhost:3000/idp/account is your own account: password, sessions, and API keys.

If you would rather start with an empty database, open .env, remove the NWIND=TRUE line, and run ./create.sh again. Sample data is only ever loaded when the database is created, so this has to happen before there is anything you care about in it.

6. Connect Your Coding Agent

Semantius is built to be worked on by agents as well as people. The semantius CLI is how a coding agent such as Claude Code reads your model, changes it, and works with your data.

Install the CLI. On Linux and macOS:

On Windows, in PowerShell, run irm https://raw.githubusercontent.com/semantius/semantius-cli/main/install.ps1 | iex and open a fresh terminal afterward.

Then point it at your stack:

The CLI reads /.well-known/semantius.json from your stack to find out where to sign in, then opens a browser so you can sign in once. After that, every command, and every agent using the CLI, works against your own installation. There is no API key or organization name to set: those belong to the managed service.

Finally, add the Semantius agent skills to your coding agent:

Restart your agent afterward so it picks up the new skills. Agent Skills Installation has more on the skills and on choosing which agents to install them for.

If Something Does Not Start

• Check what is running with ./status.sh (status.cmd on Windows). Each piece reports its own health, so this usually points straight at the one that failed.
• Port already in use. Something else on your machine is already on port 3000, 5434, or 6432. Open .env, change WEB_PORT, POSTGRES_PORT, or PGBOUNCER_PORT, then run ./up.sh.
• Start over cleanly. ./create.sh always rebuilds from scratch, so running it again is a valid fix rather than a last resort. It does delete the database, which on a fresh install costs you nothing.

Next Steps

• Running Your Stack: the everyday commands, backups, how to update, and how to reach the API from scripts.
• Going Live: move it to a real server with your own domain and HTTPS.
• Models: build out the semantic model that drives the app and the API.