Skip to content

Configuration and settings keys

In short

  • Server settings are environment variables, read when ParleML starts. Change one, then restart the container.
  • Application settings are the Settings pages in the app. They apply at once and need an administrator.
  • An experiment's training configuration comes from its template and the launch wizard, not from the server.
  • Settings → Diagnostics shows what this installation is really running with: versions, hardware, job slots, sign-in mode and models.

This page lists the settings administrators most often change. The backend configuration reference lists every one, including those you will rarely touch. For running the container itself (volumes, backups, proxy, GPU), see Install and operate ParleML.

Where settings live

Kind Where Who changes it
Server settings Environment variables. In Docker, pass them with -e NAME=value or --env-file <file>. ParleML also reads a .env file in the directory it starts in; a variable in the environment wins over the file. Whoever runs the server
Application settings The Settings pages: agents, profiles, skill packs, connections, access, workspaces and data. They are stored under the data root, in config/. Administrators
Workspace and experiment choices The workspace's profile, an experiment's template and its run settings People working in the workspace

To set variables in Docker:

docker run -d --name parleml -p 8000:8000 \
  -v parleml-data:/app/data_root \
  -e PARLEML_MAX_UPLOAD_MB=2048 \
  ghcr.io/parleml/parleml:0.8.0

The Settings pages

Administrators see every page. Everyone else sees Access only: their own agent and how sign-in works.

Group Page What you change there See
AI Agents Nothing to edit: each agent CLI's status and sign-in, the model for each tier, the installation's session limits Settings and agents
AI Profiles What a workspace's sessions may do: startable sessions, agent, skill packs, auto-approval, limits, connections Profiles
AI Skill packs Edit shipped skills in place; create or import packs Add your own skill pack
Platform Connections Databases, MLflow, tool servers and embedding providers, with their secrets in the vault Connections
Platform Access API tokens, connected agents, ready configurations for your own agent Access, permissions and data
System Workspaces & data Lifecycle stage labels, Run EDA automatically after a dataset is added (off by default), the catalog Rebuild Workspaces and data
System Diagnostics Nothing: a read-only view of this installation

Data and storage

Variable Default What it does
PARLEML_DATA_ROOT data_root in the directory ParleML starts in; /app/data_root in the image Everything ParleML keeps: workspaces, datasets, experiments, models, documents, the vault, agent sessions and installation settings. Back it up as a whole.
PARLEML_CATALOG_PATH catalog.db in the data root The SQLite catalog, an index over the files that can be rebuilt from them. Settings → Workspaces & data → Rebuild recreates it.
PARLEML_SAMPLES_DIR the repository's sample_datasets; bundled in the image The datasets offered on Home. A sample whose file is missing is left out.
PARLEML_MODE dev dev, test or prod. In prod, the health check hides the data root and library versions from callers who are not signed in, and sign-in cookies are sent over HTTPS only. Set prod on a team server.

Limits and sizes

Variable Default What it does
PARLEML_MAX_UPLOAD_MB 512 The largest single upload (dataset, knowledge-base file or imported model), in MiB.
PARLEML_AGENT_MAX_ROWS 1000 The most rows a read-only SQL query returns.
PARLEML_AGENT_MAX_POINTS 2000 The most points per series in chart data returned to agents.
PARLEML_EDA_MAX_ROWS 1000000 The most rows an EDA profile reads, as a seeded random sample. 0 profiles every row.
PARLEML_MLI_MAX_ROWS 20000 The most rows an explanation run mines, as a seeded sample.
PARLEML_MLI_HOLDOUT_MAX_ROWS 50000 The most held-out rows used to test rules and other held-out checks.
PARLEML_MLI_CANDIDATE_MAX_ROWS 6000 The rows the first, quick pass of an explanation run computes on. Raise it for a deeper, slower pass.
PARLEML_MLI_UMAP_MAX_POINTS 20000 The most points the projection scatter sends to the browser.
PARLEML_SAMPLE_VALUES_PER_COLUMN 5 The sample values shown for each column.

Background jobs

Training, explanations, scoring and profiling each run in their own worker process. These settings cap how many run at once; the rest wait in a queue and say how many are ahead. Settings → Diagnostics → Job slots shows the effective numbers.

Variable Default What it does
PARLEML_JOBS_HEAVY_CONCURRENCY 0, meaning one per four CPU cores (at least 1) Experiment fits, explanation runs and batch scoring at once, server-wide. Each fit uses every core it gets, so more at once usually slows all of them.
PARLEML_JOBS_MLI_CONCURRENCY 1 Explanation runs at once. Explaining a large ensemble can take many GB of memory.
PARLEML_JOBS_BATCH_CONCURRENCY 2 Batch-scoring jobs at once.
PARLEML_JOBS_PROBE_CONCURRENCY 2 Signal checks at once. Each loads a sample and a foundation model.
PARLEML_JOBS_BUILD_CONCURRENCY 2 EDA profiles, leakage scans and model cards at once. These short jobs have their own slots, so they never wait behind a long fit.
PARLEML_JOBS_STALL_AFTER_S 900 A running job that makes no progress for this many seconds is stopped and marked stalled. Its log keeps the stack of every thread.
PARLEML_JOBS_RETENTION_HOURS 24 How long finished job records are kept.
PARLEML_JOBS_WORKER_LOG_MAX_BYTES 64 MiB The ceiling on one job's console log, which the Console tab shows.

Sign-in and addresses

Sign-in is off by default, so a local installation works without credentials. Set up single sign-on walks through turning it on.

Variable Default What it does
PARLEML_AUTH_REQUIRED false When true, every API and MCP call needs a signed-in person or an API token. Without an SSO issuer nobody can sign in, so only tokens minted earlier work.
PARLEML_OIDC_ISSUER unset Your OpenID Connect issuer. Setting it turns on single sign-on.
PARLEML_OIDC_CLIENT_ID, PARLEML_OIDC_CLIENT_SECRET, PARLEML_OIDC_REDIRECT_URI unset ParleML's registration with your identity provider. The redirect URI ends in /api/auth/callback.
PARLEML_OIDC_SCOPES openid email profile The scopes asked for at sign-in.
PARLEML_ADMIN_EMAILS empty Comma-separated emails that get the administrator role. Checked again at every sign-in.
PARLEML_SESSION_TTL_HOURS 4 How long a sign-in lasts. It renews while the person stays active.
PARLEML_SESSION_SECRET derived from the data root's key The key that signs sign-in cookies.
PARLEML_PUBLIC_URL each request's own address Where people open the web app, used in the links agents give back. An absolute http or https URL.
PARLEML_OAUTH_ISSUER each request's own address ParleML's public address for agent hosts that connect through OAuth. Set it behind a proxy that rewrites the host.
PARLEML_CORS_ORIGINS ["http://localhost:5173"] Browser origins, other than ParleML's own, allowed to call the API. It can never contain *: the server refuses to start.

Agents

These use the PARLEML_AGENTS_ prefix. Where the agent files live follows the data root and cannot be set on its own.

Variable Default What it does
PARLEML_AGENTS_HOST_ADAPTER codex-cli in the image (claude-cli from source) The agent used when a profile names none: claude-cli, codex-cli, gemini-cli or cursor-cli.
PARLEML_AGENTS_CLAUDE_BINARY, …_CODEX_BINARY, …_GEMINI_BINARY claude, codex, gemini The command to run, if it is not on the server's PATH.
PARLEML_AGENTS_MAX_TURNS 80 Turns one attempt may take. A profile or skill can change it.
PARLEML_AGENTS_WALL_CLOCK_SECONDS 86400 Time one attempt may take.
PARLEML_AGENTS_MAX_CONCURRENT_CHILDREN 5 Steps one session may run at once.
PARLEML_AGENTS_PREFLIGHT_TIMEOUT_SECONDS 10 How long a sign-in or connection check may take. An agent that doesn't answer in time reads as not signed in.
PARLEML_AGENTS_BUILTIN_TOOLS Read, Write, Edit, Glob, Grep The agent's own file tools, besides ParleML's. No shell and no web access by default.
PARLEML_AGENTS_USER_SETTINGS_ALLOWED false Whether a profile may start a CLI with the server account's own CLI settings. Those can carry instructions and permissions nobody reviewed, so keep it off on a shared server.
PARLEML_AGENTS_RUN_DELETE_ENABLED true When false, deleting a session is refused.
PARLEML_AGENTS_ADMIN_ENABLED true When false, the agent administration pages are refused.
PARLEML_AGENTS_MAX_UPLOAD_BYTES 25 MiB The largest file a person can attach to a session.
PARLEML_AGENTS_TOMBSTONE_RETENTION_DAYS 365 How long a deleted session's summary stays readable.

Agent credentials

Variable For
OPENAI_API_KEY, CODEX_API_KEY, CODEX_ACCESS_TOKEN Codex
GEMINI_API_KEY, GOOGLE_API_KEY Gemini CLI. For Vertex AI, also GOOGLE_GENAI_USE_VERTEXAI, GOOGLE_CLOUD_PROJECT and Application Default Credentials.
ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN Claude Code (extended image)
CURSOR_API_KEY or PARLEML_AGENTS_CURSOR_API_KEY Cursor (extended image). It works with a key only.

Set these in the container's environment. ParleML reads them from there, never from the vault, and never shows them in the app. To sign in with a subscription instead, see Run ParleML.

Networks, certificates and data files

Variable Default What it does
PARLEML_DISABLE_TRUSTSTORE unset 1 keeps Python's bundled certificate list. By default ParleML trusts the operating system's certificates, so a corporate proxy's root certificate works for model downloads.
MAXMIND_DB_DIR /data/maxmind in the image Where the MaxMind databases for IP geolocation are mounted.
HF_HOME a bundled cache in the image Where foundation-model weights are cached.

Explanation switches

Three switches skip parts of an explanation run, for a faster, thinner result. Each is on unless set to 0, false, no or off:

  • PARLEML_MLI_EDA: the data profile inside the run.
  • PARLEML_MLI_EXPLANATIONS: the explanation step.
  • PARLEML_MLI_RULES_ALL: rules for every class.
Details: the standalone MCP server

If you run the MCP server on its own (python -m parleml_mcp.server), it reads:

  • PARLEML_API_BASE: the ParleML server to call (default http://localhost:8000).
  • PARLEML_API_TOKEN: the token to use when the agent host passes none.
  • PARLEML_MCP_TRANSPORT: stdio (default) or http.
  • PARLEML_MCP_HOST and PARLEML_MCP_PORT: the address and port for http (default 127.0.0.1 and 8765).

The /mcp endpoint inside ParleML does not use these.

Experiment configuration keys

An experiment's training configuration comes from the template you choose and what you change in the launch wizard. The keys are documented with the libraries:

Next