Skip to content

Configuration

How to configure PyStator for library use, API server, and UI.

Starting from a config file (like PyCharter)

You can run pystator api and pystator db commands using variables defined in a pystator.cfg file, with no environment variables required. This follows the same pattern as PyCharter's pycharter.cfg.

  1. Copy the example: cp pystator.cfg.example pystator.cfg
  2. Edit pystator.cfg with your database URL and (optionally) auth settings.
  3. From the same directory (or a directory where the config is found), run:
  4. pystator api — API will use [database] and [auth] from the file.
  5. pystator db init, pystator db upgrade, pystator db seed — DB commands use [database] from the file.

Config file search order (same as PyCharter):

  1. Current working directory (./pystator.cfg)
  2. User home directory (~/.pystator/pystator.cfg)
  3. Project root (directory that contains alembic.ini, then pystator.cfg in that directory)

Environment variables override the config file when both are set. Priority: env first, then pystator.cfg, then defaults.

Library use (no config file)

When using PyStator as a library (StateMachine.from_yaml(), from_dict(), etc.), no global config file is required. Your FSM definition is the configuration. Optionally you can load YAML/JSON from paths or env-driven paths in your own code.

API server

The REST API (pystator api or uvicorn pystator.api.main:app) supports:

Environment variables

  • PYSTATOR_DATABASE_URL — Database URL for machines and persistence. If not set, the API may use a default SQLite path (e.g. pystator.db in the current directory). See the API’s startup logs.
  • PYSTATOR_AUTH_DISABLED — Set to 1, true, or yes to disable authentication. Can be set in env or pystator.cfg [auth]. Default: auth is disabled when no credentials are configured.
  • PYSTATOR_AUTH_INITIAL_USERNAME / PYSTATOR_AUTH_INITIAL_PASSWORD — Initial credentials for login when auth is enabled.
  • PYSTATOR_AUTH_JWT_SECRET — JWT secret for signing tokens when auth is enabled.
  • CORS_ORIGINS — Comma-separated list of allowed origins for CORS (default in non-production allows common localhost origins).
  • ENVIRONMENT — Set to production or development to influence CORS and error details.

Config file: pystator.cfg

Optional. Use pystator.cfg.example as a template (copy to pystator.cfg and edit). Searched in: current directory, then ~/.pystator/, then project root (where alembic.ini is).

Example:

[database]
PYSTATOR_DATABASE_URL = sqlite:///pystator.db

[auth]
PYSTATOR_AUTH_INITIAL_USERNAME = admin
PYSTATOR_AUTH_INITIAL_PASSWORD = secret
PYSTATOR_AUTH_JWT_SECRET = your-jwt-secret

With [database] set, the API and all pystator db commands use that URL. With [auth] set (and auth not disabled), the API will require login and Bearer tokens for protected routes.

UI server

When you run pystator ui serve, the UI server needs to know the API base URL. It typically defaults to http://localhost:8000. You can override with PYSTATOR_API_URL or the --api-url flag if you start the UI in a custom way.

The UI itself stores the API base URL in browser localStorage (Settings); that overrides the server default for the client.

UI theme

The global color theme (light / dark / system) can be set via:

  • Environment variable: PYSTATOR_UI_THEME — one of light, dark, or system (follow OS preference). Default: light.
  • Config file: pystator.cfg section [ui], key PYSTATOR_UI_THEME. Same values. Env overrides .cfg.

UI app name: The website name shown in the UI (nav bar, login, settings) can be set via PYSTATOR_UI_APP_NAME (env or pystator.cfg [ui]). Default: PyStator.

Database and default SQLite

When no database URL is configured (no env var, no pystator.cfg, no explicit argument), the API and worker use a default SQLite database at <cwd>/pystator.db. Any provided connection string (environment variable, config file, or explicit argument to the store/worker) is always respected. This mirrors PyCharter's behavior.

If the API is configured to use a database (e.g. for storing machines), run migrations or initialization (e.g. pystator db init). The exact steps depend on the version of the API; check the API README or source for db init / Alembic usage.

Summary

Context What to configure
Library Nothing required; pass FSM YAML/dict and context to process().
API auth Env: PYSTATOR_AUTH_* or file: pystator.cfg [auth].
API database Env: PYSTATOR_DATABASE_URL; run DB init/migrations as per project.
UI Env: PYSTATOR_API_URL or Settings in UI.
UI theme Env: PYSTATOR_UI_THEME or pystator.cfg [ui] PYSTATOR_UI_THEME (values: light, dark, system).
UI app name Env: PYSTATOR_UI_APP_NAME or pystator.cfg [ui] PYSTATOR_UI_APP_NAME (default: PyStator).