Installation

Kmila runs three ways: in your browser on this site (nothing to install), self-hosted (the web version on your own machine or server), or as a native app. The web version is Kmila.Web — a Blazor Server app on .NET 9 — and shares its code base with the native application.

Source coming soon. Kmila is open source (MIT), but the public repositories are still being finalized for the v1.0 release. The commands below use the final repository URLs; until the repos are public you can point the tooling at another source with the KMILA_REPO_BASE environment variable.

Option A — Try it in your browser

The fastest way: open the demo and start editing and simulating — no account and nothing to install. It runs the whole Kmila toolchain entirely in your browser (compiled to WebAssembly), so your code never leaves your machine.

First load downloads the engine (a few seconds). Your work is saved locally in your browser (IndexedDB) — it stays on this device and isn't synced. For unlimited, persistent use, install the native app or self-host (below). See Privacy.

Prerequisites (for self-hosting)

For	You need
Getting the code (always)	git
Native build	.NET 9 SDK (brew install dotnet-sdk, or the official installer; Linux also needs libicu)
Docker build	Docker + Compose

Kmila's code is split across six repositories — Kmila, Interpreter, Parser, Debugger, LibraryCompiler, TimeMachine — that must sit side-by-side in one workspace, so a single clone can't be built on its own. The scripts below do this for you.

Option B — One command (recommended)

The build scripts live in the Kmila repository (App/Kmila/). They clone all six repositories into a self-contained workspace, force the net9.0 target (so no MAUI workload is required), and build.

# macOS / Linux / Windows (Git Bash or WSL)
./build.sh                 # native build (needs the .NET 9 SDK)
./build.sh --docker        # build the Docker image (needs Docker)
./build.sh --native --run  # build, then serve on http://localhost:8080
# options: --workdir <dir>  --port <n>  --branch <b>   (env: KMILA_REPO_BASE)

# Windows (PowerShell)
./build.ps1                # -Mode native (default) | -Mode docker ; -Run ; -WorkDir ; -Port

Linux, as a service. install.sh (run with sudo) installs the dependencies, builds, and registers a systemd service on port 8080:

sudo ./install.sh              # native + systemd service
sudo ./install.sh --docker     # Docker container instead
sudo ./install.sh --no-service # install deps + build only
# → http://<host>:8080 ; manage with: systemctl {status|restart|stop} kmila

Option C — Manual build

If you'd rather not use the scripts, this is exactly what they do.

1. Clone the six repositories into the required layout (the Kmila repo goes in App/Kmila, its projects reference the siblings via ../../../<name>):

mkdir kmila-build && cd kmila-build
for r in Interpreter Parser Debugger LibraryCompiler TimeMachine; do
  git clone https://github.com/Kmila9s/$r.git "$r"
done
git clone https://github.com/Kmila9s/Kmila.git App/Kmila

2a. Native — publish the .csproj (never the .sln, which pulls in the MAUI head), forcing net9.0:

dotnet publish App/Kmila/Kmila.Web/Kmila.Web.csproj \
  -c Release -f net9.0 -p:TargetFrameworks=net9.0 -o publish
ASPNETCORE_URLS=http://+:8080 dotnet publish/Kmila.Web.dll   # → http://localhost:8080

2b. Docker — the build context must be the workspace root; stage the recipe from deploy/:

cp App/Kmila/deploy/Dockerfile App/Kmila/deploy/.dockerignore App/Kmila/deploy/docker-compose.yml .
docker build -t kmila-web .
docker compose up -d          # → http://localhost:8080  (logs: docker compose logs -f)
docker compose down           # stop (data kept); add -v to also wipe the volume

Option D — Native app

Native builds for Windows, macOS, Android and iOS are distributed from the project repository and the app stores. See the Download page — the mobile store releases are coming soon.

Configuration & data

• Port / binding: ASPNETCORE_URLS (e.g. http://+:8080); Docker maps it via the compose ports:.
• Where your data lives (SQLite DB, imported FPGA/dictionary/library packs, compiled-library cache):
  • native: ~/.config/KmilaData (Linux), ~/Library/Application Support/KmilaData (macOS), %APPDATA%\KmilaData (Windows).
  • Docker: the named kmila-data volume at /data — survives restarts and rebuilds; wipe it with docker compose down -v.
• Behind HTTPS: Blazor Server needs a persistent WebSocket (SignalR), so your reverse proxy must allow WebSocket upgrades. Terminate TLS at the proxy and set ASPNETCORE_FORWARDEDHEADERS_ENABLED=true.

Troubleshooting

• NETSDK1147 … workloads must be installed: android (or ios/maccatalyst) — you didn't force a single framework. Add -f net9.0 -p:TargetFrameworks=net9.0, and publish the .csproj, never the .sln.
• Clone fails / asks for credentials — the repositories are private until the public release; use KMILA_REPO_BASE to point the tooling at a source you can reach.
• Port already in use — change ASPNETCORE_URLS / --port (native) or the compose ports: mapping.
• Blank page / disconnects behind a proxy — WebSockets are being dropped; enable WS upgrades and ASPNETCORE_FORWARDEDHEADERS_ENABLED=true.

See the Getting started guide for your first project.