Advanced Setup

The Installation guide gets you running with sensible defaults. This page is the reference for everything you can tune: configuration sources, every environment variable, alternate databases, execution and scheduler tuning, and a production deployment outline.

Configuration sources & precedence

The backend (Settings) reads configuration in this order — later wins:

1. Built-in defaults (shown below).
2. .env file in the backend working directory.
3. Environment variables (prefixed CIAREN_).
4. ciaren serve flags (e.g. --port, --db-url, --engine, --execution-mode, --data-dir, --no-scheduler), which are applied as env vars before the app loads.
5. Settings page overrides for a small editable subset (marked UI below). Saved in Ciaren's database, applied immediately, and re-applied on every startup — so once a value is edited in the UI, it wins over the environment until you press Reset on that setting.

Scaffold a commented file with ciaren init, confirm the resolved values with ciaren info, and validate the environment with ciaren check.

The Settings page

The gear icon in the header opens Settings — runtime configuration editable from the browser: default engine, execution mode, run timeout, upload size, dataset retention, scheduler tuning, and the ML guardrail limits. Each setting shows where its current value comes from (default, environment, or a saved override) and what Reset would restore. Changes apply to the whole server and persist across restarts; the few marked "takes effect after restart" are consumed once at startup. Overrides are designed for the standard single-process ciaren serve; if you run multiple server processes, a change applies live to the process that handled it and to every process after restart.

Everything else is deliberately environment-only: bootstrap values the server needs before the database is up (DATABASE_URL, DATA_DIR, …), secrets (API_TOKEN, WEBHOOK_SECRET, NOTIFY_WEBHOOK_SECRET), the failure-webhook URL (Ciaren sends the webhook secret to that URL, so only someone with access to the environment may point it somewhere), and the security guards (CORS/CSRF, secret allowlists, storage confinement, plugin enforcement). The Settings page and its API are reachable by exactly the audience those guards constrain, so exposing them there would let that audience weaken its own guardrails — changing them requires access to the server's environment.

Environment variables

All settings use the CIAREN_ prefix.

Booleans accept true/false; lists (like CORS_ORIGINS) are JSON. Variables marked UI can also be edited at runtime from the Settings page; a saved override takes precedence over the variable until reset.

Database

Ciaren uses async SQLAlchemy, so the URL must use an async driver.

# backend/.env
CIAREN_DATABASE_URL=postgresql+asyncpg://ciaren:secret@localhost:5432/ciaren

The schema is created automatically on startup — there is no separate migration step. ciaren check verifies the driver is async and that the database is reachable.

Data directory

CIAREN_DATA_DIR (default .data) is where uploaded files, run outputs, and previews are written. In production, point it at a persistent, writable volume — ciaren check confirms it's writable. The database stores metadata; the data dir stores the actual files.

Execution tuning

Ciaren runs synchronous dataframe work off the event loop so the API stays responsive. CIAREN_EXECUTION_MODE (also editable on the Settings page) chooses how that work is offloaded. This section is the practical guidance on which mode to use; for the engine (polars/pandas) side of performance, see Engines.

thread vs process: which to use

Stay on thread (the default) unless a symptom below pushes you off it. For the typical setup — one person, one run at a time, the polars engine — it is simpler, fully featured, and just as fast: polars compute is multithreaded Rust that releases the GIL, so a single run already uses every core in either mode. process pays off in specific server scenarios, not in general.

Switch to process when:

• Ciaren is a long-lived shared server running scheduled jobs — crash isolation and a timeout that really reclaims CPU matter more than precise cancellation.
• You raised SCHEDULER_MAX_CONCURRENT_RUNS above 1 and your flows are pandas-heavy — the one case where the GIL actually serializes work.

Stay on thread when:

• You use Ciaren interactively on your own machine (the install default): full cancel support, plugin node hooks, no spawn overhead.
• Your flows run on polars — process adds moving parts without adding speed for a single run.

Practical notes

• Neither mode is a security boundary. A process worker has the same privileges and filesystem access as the server; it isolates crashes, not code. For untrusted Python Transform scripts see CIAREN_PYTHON_TRANSFORM_STRICT and the security docs.
• Switching the mode at runtime (Settings page) is safe: it applies from the next run.
• SCHEDULER_MAX_CONCURRENT_RUNS also sizes the process pool, and the pool is created once — that setting needs a restart to fully apply.
• CIAREN_RUN_TIMEOUT_SECONDS (0 = no limit) abandons an over-running run in both modes; process mode gets the CPU back (the pool is recycled) as soon as no other run still shares it — immediately if this was the only one, otherwise once the others finish. Pair a timeout with process on unattended servers.
• A permission revocation or plugin disable/uninstall reaches already-spawned process workers on their next task, not only after the pool is recycled — each submitted task carries the current plugin-state generation, and a worker behind it re-syncs before executing.

# a shared box running scheduled jobs: isolation + a 5-minute cap per run
CIAREN_RUN_TIMEOUT_SECONDS=300 ciaren serve --execution-mode process

Scheduler tuning

The background scheduler runs inside the API process. See Scheduling for behavior. Relevant settings:

• CIAREN_SCHEDULER_ENABLED — master switch (or ciaren serve --no-scheduler).
• CIAREN_SCHEDULER_POLL_INTERVAL_SECONDS — lower = more responsive, more wakeups.
• CIAREN_SCHEDULER_MAX_CONCURRENT_RUNS — cap on simultaneous scheduled runs.
• CIAREN_SCHEDULER_MAX_CONSECUTIVE_FAILURES — auto-disable threshold.

CORS

When the frontend is served from a different origin than the API, add that origin to CIAREN_CORS_ORIGINS (a JSON list):

CIAREN_CORS_ORIGINS=["https://ciaren.example.com","http://localhost:5173"]

Production deployment

Ciaren is local-first, but you can host it. A typical setup:

Backend

python -m pip install ciaren
# bind to all interfaces, no reload, info logs
ciaren serve --host 0.0.0.0 --port 8055 --log-level info

• Set CIAREN_ENVIRONMENT=production.
• Use a managed PostgreSQL/MySQL via CIAREN_DATABASE_URL.
• Put the data dir on a persistent volume.
• Run it under a process manager (systemd, Docker, etc.).
• Set CIAREN_LOG_FORMAT=json to emit one JSON object per log line (level, logger, message, timestamp, plus any structured fields) for a log collector. The default auto prints human-readable lines.
• Point your orchestrator's liveness probe at /health and its readiness probe at /ready (the latter returns 503 until the database is reachable). See REST API conventions.

Frontend

The React app is a static build that calls the API at the path /api on its own origin (there is no runtime API-URL variable — only the dev-server proxy). So in production you serve the built files and reverse-proxy /api to the backend, typically behind one web server:

cd frontend
npm ci
npm run build         # outputs static files to frontend/dist/

Serve frontend/dist/ and route /api/* to the backend. Example nginx:

server {
  listen 80;
  server_name ciaren.example.com;

  root /srv/ciaren/dist;            # frontend build
  location / { try_files $uri /index.html; }

  location /api/ {                      # proxy to the backend
    proxy_pass http://127.0.0.1:8055;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  }
}

Because the browser then talks to a single origin, you usually don't need to touch CORS_ORIGINS for this layout.

Frontend dev overrides

For local development against a non-default backend, the dev server (not the production build) honors:

• VITE_PORT — change the dev server port (default 5173).
• VITE_API_TARGET — where the dev proxy forwards /api (default http://localhost:8055).

VITE_PORT=3000 VITE_API_TARGET=http://localhost:8001 npm run dev

Verifying

ciaren info     # print resolved settings (DB password redacted)
ciaren check    # data dir writable? async driver? DB reachable? engines present?

See also

• CLI Reference — every command and flag
• Engines — polars/pandas, execution mode, timeouts
• Scheduling — the background scheduler
• Installation — the basic setup