Skip to main content
This page gets Aperium running locally end to end — API, worker, and UI against local infrastructure — using the dev command-line tool. If you only want to use a hosted deployment, you don’t need any of this; see the Admin Console.
Everything below assumes a checkout of the Aperium monorepo. The same dev CLI also drives downstream product repos that depend on it — see The dev CLI.

​
Toolchain

The repo pins its toolchain with mise via mise.toml, so a single mise install provisions everything at the versions the repo expects. The pinned tools include: You also need Podman or Docker for local infrastructure containers. The dev CLI auto-detects podman-compose, docker compose, or docker-compose.
If you don’t use mise, install Python, uv, Node 20+, and pnpm yourself at compatible versions. mise is the supported path because it keeps every contributor on the same toolchain.

​
First run

1

Create local config

Copy the templates. Repo-local files under config/ work as a fallback; you can also keep them in your OS config directory so multiple worktrees share the same settings.
credentials.yaml holds the local key-encryption-key (KEK) material and any LLM provider keys. Follow the comments in the example file to generate local KEK values — never commit real secrets.
2

Install dependencies

Syncs the Python workspace and installs UI dependencies for each registered UI.
3

Start the container runtime

First time only, initialize a Podman machine (skip if you use Docker Desktop or an already-running Podman machine).
4

Start local infrastructure

Brings up PostgreSQL and the other local services via compose.yml.
5

Apply database migrations

6

Run the stack

Starts the API, worker, and UI, streaming each child process through a colored, prefixed log multiplexer ([api] / [worker] / [ui] / [infra]).
When it’s up, open: The API port follows port in config/aperium.yaml (default 8090); the UI port follows VITE_FRONTEND_PORT (default 3002).
Two useful dev run variants: --external-infra (-x) runs only the app processes against PostgreSQL, Redis, Temporal, and Phoenix you started yourself; --overlay <name> (-o) runs a registered UI overlay instead of the default. See the dev run reference.

​
Local infrastructure services

compose.yml defines the local backing services. PostgreSQL always starts; the rest are gated behind Compose profiles so you only run what you need: uv run dev infra up starts the set the local stack needs; uv run dev infra down stops the containers while preserving their data volumes.
Locally, background jobs run on Temporal (jobs.runner_backend: temporal in aperium.yaml, with the Temporal UI at :8233). How orchestration is wired in a given production deployment is a deployment decision — see the Deployment overview. Verify against your target environment before relying on a specific orchestrator there.

​
Configuration model

Runtime configuration is file-layered, not purely environment variables. Values are resolved with this precedence (highest first):
  1. Process environment variables — an existing env var always wins.
  2. YAML files listed in APERIUM_CONFIG_FILE (e.g. config/aperium.yaml,config/credentials.yaml).
  3. Discovered default YAML when APERIUM_CONFIG_FILE is unset — the OS config directory, then ${XDG_CONFIG_HOME:-~/.config}/aperium/, then system config directories, then repo-local config/.
  4. Model defaults.
uv run dev run sets APERIUM_CONFIG_FILE for you when both config/aperium.yaml and config/credentials.yaml exist. Keys in the YAML map to typed aperium.config.Settings fields; unknown keys are silently ignored. Plugin configuration follows the <PLUGIN>_<FIELD> environment convention (for example ODOO_URL, ODOO_DB). For the full env-var catalog, see Environment variables.

​
APERIUM_ENV

The environment key (env var APERIUM_ENV) marks the deployment posture and drives the fail-closed boot gates: Local development leaves this at the implicit dev posture — uv run dev run exports APERIUM_ENV=dev, which the dev-only KEK provider requires. A real deployment must set it explicitly.

​
Next steps

The dev CLI

Every command group: run, check, infra, db, plugins, test, and more.

Build a plugin

Scaffold, validate, and smoke-test a new integration.