Configuring agents¶

In short

The agents' configuration is YAML under <data_root>/config/; their runtime state is under <data_root>/agents/. The Settings pages edit the same files.
A profile is the agent setup a workspace picks: the agent and its models, its caps, the skill packs, which sessions people can start and how decisions are answered. standard is written on first boot and is yours to edit.
A skill asks for a model tier (strong, default, fast); each agent maps tiers to its own models.
Edits apply to the next session without a restart. Running sessions keep the snapshot they started with.
Every PARLEML_AGENTS_* variable and its default is in Environment.

What the agent runtime reads lives in two directories with two lifetimes:

<data_root>/config/, the installation's configuration: what people edit in Settings, as YAML meant to be read and edited by people too.
<data_root>/agents/, runtime state: sessions, their work files, and ParleML's agent bookkeeping.

The Settings pages edit the same files, with ETag protection where two people may edit at once, and the runtime reads them fresh on every use, so an edit applies to the next session without a restart. Both locations follow PARLEML_DATA_ROOT; they cannot be moved separately.

The configuration folder¶

Path	Written by	What
`settings.yaml`	Settings → Workspaces & data, or you	The lifecycle `stages` catalog (frame · data · model · decide · operate), each stage `{id, label}`, and installation preferences such as `auto_run_eda_on_ingest`. Absent means the defaults; `stages: []` hides stage summaries without disabling session activity. A key nothing reads is refused at startup.
`connections.yaml`	ParleML (`parleml`), Settings → Connections, you	Every external system, each entry naming its `kind`: `database`, `mlflow`, `mcp` (a tool server a profile may grant) or `embeddings`. The runtime reads the `mcp` entries. ParleML writes `parleml`, its own `/mcp` with `auth: {type: minted, provider: parleml}`, whenever it is missing.
`vault.json`	Settings → Connections, ParleML	Every stored secret, Fernet-encrypted; connections refer to entries as `vault://<name>` (see Credentials & logins). ParleML also keeps its identifier-pseudonymisation key there (`installation/pseudonymisation-key`). Never written by the runtime.
`profiles/<id>.yaml`	ParleML once (`standard`), then Settings → Profiles or you	Agent profiles. The file name must equal the profile `id`.
`packs/<pack>/`	ParleML (`parleml-ml-lifecycle`), Settings → Skill packs, you, imports	Skill packs: `skills/<slug>/SKILL.md` with its `assets/templates/`, the manifests (`.claude-plugin/plugin.json`, the Cursor and Codex plugins, `gemini-extension.json`, `apm.yml`), optional `rules/` and `hooks/` (Host-native rules & hooks).
`skill-overrides/<pack>/<slug>/`	Settings → Skill packs	Your version of a shipped skill: `skill/` holds the effective folder, `base/` the shipped version it was based on, and `override.json` tracks the override. Edit through the skill editor; do not modify shipped files in `packs/`, which installation upgrades replace.

Details: configuration files outside config/

ParleML reads its configuration only from config/ and the vault. If it finds agents/connections.yaml, agents/profiles/, agents/packs/, agents/settings.yaml or agents/secrets.env, startup stops and says what to do with each file. scripts/migrate_data_root_2026_10.py in a source checkout moves them into config/ and the vault.

The runtime directory¶

Path	Written by	What
`workspace_profiles.json`	ParleML	Which profile each workspace picked. Only non-default choices are stored.
`provenance/<token_id>.json`	ParleML	One file per minted session token: the session, step, attempt, skill and person behind it (provenance).
`runs/<root_id>/`	runtime	The control plane of one session: `run.json`, `events.jsonl`, transcripts, uploads, sidecars (Data on disk). `runs/.runtime.lock` keeps a second process out.
`work/<root_id>/`	the agents	The session's work directory, shared by the orchestrator and its steps.
`tombstones/<root_id>.json`	runtime	What a deleted session was. Removed after `PARLEML_AGENTS_TOMBSTONE_RETENTION_DAYS`.
`.staging/imports/`	runtime	Pack and skill imports awaiting adoption; removed after 20 minutes.

Published documents do not live here: Publish copies a work file to <data_root>/workspaces/<workspace_id>/documents/<doc_id>/ (see Documents).

Profiles¶

A profile is the shared agent setup a workspace picks.

id: standard
name: Standard
skill_packs: [parleml-ml-lifecycle]
orchestrators: [ml-delivery, ml-investigate, ml-operate]
connections:
  parleml: {}
agent:                         # optional; every field falls back to the server defaults
  adapter: claude-cli          # claude-cli | codex-cli | cursor-cli | gemini-cli
  model: sonnet                # or {id: sonnet, params: {effort: high}}
  tier_models:                 # optional: remap a tier for this profile
    strong: opus
  max_turns: 120               # per-attempt caps (see Limits)
  wall_clock_seconds: 7200
  max_concurrent_children: 3
skill_agents:                  # optional: one skill on another agent
  ml-challenge:
    adapter: codex-cli
allowed_agents: [codex-cli]    # optional: other agents a person may pick at start
host_assets:                   # optional: what the packs' hooks and your own settings may do
  include_account_apps: false   # opt-in for Codex/Claude account app discovery
  run_hooks: {claude: true, cursor: false}   # per host; both default to true
  include_user_settings: false # default false; needs PARLEML_AGENTS_USER_SETTINGS_ALLOWED
auto_approval_default: false   # optional: new sessions decide routine questions themselves
annotations: during_sessions  # off | on_request | during_sessions | always
agents_accept_suggestions: false # let session agents apply existing AI suggestions
reference_paths: []            # optional: directories sessions may read, not edit

Orchestrators are the skills a person can start as a session. A skill must also declare parleml-orchestration-mode to be startable (Skill attributes).
Tiers. A skill asks for a tier (strong, default or fast), never a model. Each CLI maps tiers to its models: Claude Code to opus, sonnet, haiku; Gemini CLI to pro, auto, flash; Cursor to auto, auto, composer-2.5; Codex keeps its own model and sets the reasoning effort (high, medium, low). tier_models remaps a tier for the profile.
Pins. skill_agents runs one skill on another agent, for example ml-challenge on a second vendor for a fresh-context review. A pin names only what differs. A pin that changes the adapter drops the profile's model and tier_models, which name the other CLI's models. Preflight checks every pinned adapter and that each pinned skill is in the packs.
Picking the agent at start. The Agent menu and Home's Work with an agent offer the profile's own agent (agent.adapter, else the server default) and every agent in allowed_agents, each with the sign-in its CLI would use (Credentials & logins). The pick (POST /api/agent/runs with agent) must be one of them (422 invalid_payload otherwise, before anything is created) and is preflighted in place of the profile's agent. Like a pin, it keeps the profile's caps and drops its model and tier_models. It holds for the whole session: its unpinned steps and every resume run on it, and a skill's pin still wins for that skill. GET /api/agent/agents?scope_id= lists the agents for a workspace.
Account apps. host_assets.include_account_apps defaults to false. Codex and Claude Code exclude automatic account-connected apps unless the profile opts in, preserving explicit MCP connections and prompts. See context isolation.
Host assets. host_assets.run_hooks switches each host's hooks on or off; off, the hooks never reach the session's host-asset snapshot, so a session cannot run them. Rules are not affected. include_user_settings launches each CLI with the settings of the account that runs it as well (see Host-native rules & hooks); it is off by default, and a profile that turns it on is refused (on save, by preflight and at start) unless PARLEML_AGENTS_USER_SETTINGS_ALLOWED=true.
Reference paths are read-only for Claude Code (a scoped read grant and an edit deny per path; see Confinement) and Codex (its sandbox writes only in the work directory). Cursor, and Gemini CLI when the session may write files, can write wherever they read, so a session on them refuses to start with reference paths; both read a per-attempt copy of the skill's folder, never the shared packs.
Decisions. auto_approval_default is the one place the auto-approval default lives: on, a new session answers supported questions itself and records why. Each session can change it with Decide automatically. This can include releases, approvals and deletions. A rejected answer never supplies approval provenance. Missing or ambiguous proposals still ask a person. Paid external embedding services require a gate a person answered; an automatic approval is refused for that launch. Answering a gate does not grant promotion or deletion tools to the business MCP.
The default profile. standard is written on first boot and is yours to edit. It cannot be deleted, and a workspace whose chosen profile was deleted runs on it.
Deleting a profile is refused while any workspace uses it or any session started from it remains (409 still_referenced).

Which profile a workspace uses¶

A workspace's Agents page picks its profile (GET/PUT /api/workspaces/{id}/agent-profile); standard until it picks another. New sessions use the choice; running and paused sessions keep the snapshot they started with, and the page says how many there are before you save. Deleting a workspace forgets its choice.

A session records a hash of its profile and the connections it uses. If either changes, Resume says "The agent profile changed" and offers Continue with the current settings. Renaming a profile, editing a SKILL.md or rotating a secret does not count as a change.

Each attempt also records the profile version it ran on: the SHA-256 of the profile's file, the same value as the profile's ETag. The session header shows its first twelve characters next to the profile id, as the profile page shows its own version, so a session can be matched to the profile it ran on.

The ML pack¶

parleml-ml-lifecycle ships with ParleML: ml-delivery (guided: frame → framing approval → data → data approval → baseline → iterate → challenge → decide → release approval → release), ml-investigate and ml-operate (adaptive), and the seven steps ml-frame, ml-data, ml-baseline, ml-iterate, ml-challenge, ml-decide, ml-release.

Shipped pack metadata, rules, hooks and deletion are protected. Its skills can be edited directly in Settings → Skill packs: Save stores Your version under the same id, in config/skill-overrides/<pack>/<slug>/skill/. Reinstallation updates shipped files without touching your version. Review upstream changes, merge them into a draft, keep yours, or reset to shipped. New sessions snapshot the effective complete skill folders; live sessions keep their snapshot. Overrides do not change own-agent APM installs or pack exports. python scripts/build_skill_bundles.py --runtime-pack DIR writes the same pack for inspection.

Your own agent installs the same skills from the full parleml pack with APM (apm install … -t claude|cursor|codex|gemini); see Skills & packaging.

The Settings pages¶

Page	Who	What
Agents	administrators	The four CLIs: status, the installed version and the one the adapter was tested with, the sign-in each would use here (never the key), the default; Check again; where agents run; the model each tier picks on each CLI; the installation's caps (read-only: they come from the `PARLEML_AGENTS_*` caps below).
Profiles	administrators	One card per profile: packs, startable sessions, workspaces using it, live sessions; New profile. A profile page has Preview (the resolved profile and its checks), Preflight, Duplicate and Save (with the live sessions a change affects), and its sections: Decisions, the agent and its caps, the agents a person may pick, an agent per skill, tier overrides, the tasks people can start, skill packs, the tool servers it grants, and host assets: each selected pack's Claude Code and Cursor rules, the pack that provides each host's hooks with its Run its hooks switch, and Include my own settings (offered only where the installation allows it; Gemini CLI is marked as reading them either way).
Skill packs	administrators	The shipped pack with editable skills, your own packs, New pack, Import a pack; the pack page, the skill editor, and the template and host-file editors (Editing skills and packs).
Connections	administrators	Every connection with its kind, address, last Test and what uses it; Add connection picks a kind and sends the secret to the vault. A tool server can be added, edited or tested only by an agent administrator.
Access	everyone	Sign-in, your own agent's configuration per client, API tokens (minted by administrators), connected agent hosts.
Workspaces & data	administrators	The lifecycle stage catalog (see below), EDA on ingest, the data root and the catalog.
System	administrators	Versions, hardware, job slots, and the models on this server.

The agent runtime's admin routes (/api/agent/admin/…) need an administrator and return 403 when PARLEML_AGENTS_ADMIN_ENABLED=false. With sign-in off, only a request from the server's own machine counts as an administrator (why); the same holds for writing or testing a tool server in Settings → Connections.

AI annotations and suggestion acceptance¶

The profile's Decisions section also controls AI annotations on the objects of workspaces using that profile:

`annotations`	Behavior
`off`	Hides AI actions and previously written AI annotations; computed results remain available.
`on_request`	A person requests AI text from an object's page. No automatic jobs.
`during_sessions` (default)	Also queues annotations when a hosted session produces or finishes the object.
`always`	Queues annotations for eligible finished objects regardless of who produced them.

The automatic triggers are: dataset EDA → summary and column suggestions; clustering/anomaly fit → cluster name suggestions; explanations → narrative and field descriptions; knowledge-base load → descriptions and relationship suggestions; recipe creation → SQL explanation. Rule explanations, per-class deep dives, comparison summaries and SQL suggestions are requested explicitly. The profile page shows this trigger table. These are optional model calls through ask(); annotation failures do not invalidate the computed work.

Allow agents to apply existing AI suggestions (agents_accept_suggestions, default false) grants a hosted session's agent permission to apply matching suggestions through the ordinary object tools. It does not generate suggestions or accept them automatically. Without permission, a write matching an unaccepted suggestion returns 403; with permission, a successful write records the session step and the previous value so a person can revert it. This setting is separate from auto_approval_default, which answers session gates. Annotation policy and acceptance permission follow the workspace's current profile.

Every PARLEML_AGENTS_* variable, with its default, is listed in the backend configuration reference.

The stage catalog¶

Settings → Workspaces & data reads and replaces the runtime's part of settings.yaml (GET/PUT /api/agent/admin/settings, ETag-protected: a save against a version someone else replaced is refused with 412, and Reload shows theirs). The stage strip, in order: each stage has an id (lower-case words joined by hyphens, unique) and a label. Ordering arranges the display; it imposes no execution sequence, ownership or permissions. An empty catalog disables this display. A skill optionally names a stage by its id in parleml-stage; renaming or removing an id leaves the skills that name it unstaged on the strip, never failing. The skill editors offer the saved catalog. Running sessions keep the stages they started with.

Environment¶

The backend reads PARLEML_AGENTS_* variables from the same environment and .env as its own settings and builds the runtime's settings from them: one reader. Agent profiles and connections are never configured here, and where the runtime's files live is not either: PARLEML_AGENTS_PLATFORM_DIR, PARLEML_AGENTS_CONFIG_DIR and PARLEML_AGENTS_VAULT_KEY_FILE cannot be set under ParleML (startup refuses).

Variable	Default	Meaning
`PARLEML_AGENTS_MCP_HOME`	`.`	Base for a relative `cwd` of a stdio connection.
`PARLEML_AGENTS_SESSION_MCP_URL`	`http://127.0.0.1:8000/session-mcp/`	Where spawned CLIs reach the session MCP (trailing slash required). Its origin also decides the `parleml` connection URL (`<origin>/mcp`).
`PARLEML_AGENTS_HOST_ADAPTER`	`claude-cli` (the image sets `codex-cli`)	The CLI a profile without `agent.adapter` uses (`claude-cli`, `codex-cli`, `cursor-cli`, `gemini-cli`, `fake`).
`PARLEML_AGENTS_CLAUDE_BINARY`	`claude`	Claude Code executable.
`PARLEML_AGENTS_CLAUDE_PINNED_VERSION`	`2.1.270`	The Claude Code build the adapter's command line is verified against.
`PARLEML_AGENTS_CODEX_BINARY`	`codex`	Codex executable.
`PARLEML_AGENTS_CODEX_PINNED_VERSION`	`0.162.1`	The Codex build it is verified against.
`PARLEML_AGENTS_GEMINI_BINARY`	`gemini`	Gemini CLI executable.
`PARLEML_AGENTS_GEMINI_PINNED_VERSION`	`0.62.0`	The Gemini CLI build it is verified against.
`PARLEML_AGENTS_CURSOR_API_KEY` (or `CURSOR_API_KEY`)	—	Cursor's key; Cursor runs through its SDK (`cursor-sdk`), which the standard image does not include and the extended image adds (Which agents can run).
`PARLEML_AGENTS_CURSOR_HOST_ASSETS_ENABLED`	`false`	Let Cursor sessions use packs' Cursor rules and hooks.
`PARLEML_AGENTS_USER_SETTINGS_ALLOWED`	`false`	Let a profile's `host_assets.include_user_settings` launch CLIs with the running account's own settings. Only for a local, one-person install (why).
`PARLEML_AGENTS_CURSOR_DEFERRED_MCP_WAITS_ENABLED`	`true`	Cursor gets operation handles instead of long-held calls (Supervisor MCP).
`PARLEML_AGENTS_CURSOR_DEFERRED_WAIT_SECONDS`	`50`	One bounded `await_operation` slice for Cursor.
`PARLEML_AGENTS_MCP_TOOL_TIMEOUT_MS`	`86400000` (24 h)	How long a held `ask_gate` or `await_operation` waits on a blocking CLI.
`PARLEML_AGENTS_AWAITABLE_POLL_SECONDS`	`2`	How often a held `job:` wait polls the job.
`PARLEML_AGENTS_AWAITABLE_PROGRESS_SECONDS`	`30`	How often a held wait sends MCP progress.
`PARLEML_AGENTS_AWAITABLE_MAX_HOLD_SECONDS`	`900`	The longest one `await_operation` on server work (`job:`, `eda:`, `call:`…) holds on a blocking CLI; then it returns `pending` with how long the run has waited and how to stop the work.
`PARLEML_AGENTS_MAX_TURNS`	`80`	Default turns per attempt.
`PARLEML_AGENTS_WALL_CLOCK_SECONDS`	`86400`	Default wall clock per attempt.
`PARLEML_AGENTS_MAX_CONCURRENT_CHILDREN`	`5`	Default largest `run_skills` batch.
`PARLEML_AGENTS_BUILTIN_TOOLS`	`["Read","Write","Edit","Glob","Grep"]`	Built-in CLI tools granted besides MCP (JSON list). No shell or web fetch by default. Claude Code gets the file tools per directory (Confinement); any other built-in, such as `Bash`, by name and with its full reach.
`PARLEML_AGENTS_PREFLIGHT_TIMEOUT_SECONDS`	`10`	Bound on one preflight probe.
`PARLEML_AGENTS_SSE_QUEUE_SIZE`	`1000`	Outbound live-update frames buffered per browser connection.
`PARLEML_AGENTS_ACCESS_LOG_READS`	`false`	Also log successful reads in the access log.
`PARLEML_AGENTS_MODEL_ROUTING_ENABLED`	`true`	Ask or describe the work may call the model to pick a session type; off uses the local word scorer only.
`PARLEML_AGENTS_AUTHORING_ADAPTER`	`model`	Skill-attribute suggestions in the editor: `model`, or `fake` for tests.
`PARLEML_AGENTS_ASK_CONCURRENCY`	`2`	How many one-shot agent calls (annotations, routing, attribute suggestions) run at once; ParleML also runs at most this many annotation jobs at a time.
`PARLEML_AGENTS_ADMIN_ENABLED`	`true`	`false` makes every `/api/agent/admin` route return `403`.
`PARLEML_AGENTS_RUN_DELETE_ENABLED`	`true`	`false` makes deleting a session return `403`.
`PARLEML_AGENTS_MAX_UPLOAD_BYTES`	`26214400` (25 MiB)	Largest file a person attaches to a session.
`PARLEML_AGENTS_MAX_UPLOAD_FILES`	`20`	Most files one start may attach (at least 1).
`PARLEML_AGENTS_TOMBSTONE_RETENTION_DAYS`	`365`	How long a deleted session's tombstone stays readable (at least 1); applied at start and daily.
`PARLEML_AGENTS_FAKE_SCENARIO`	—	With `HOST_ADAPTER=fake`: a scripted session (`decide`, `slow`) for tests and demos without a CLI.

The CLIs' own login variables (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, …) are covered in Credentials & logins.

The links agents hand out. Every ui_url an agent quotes ("confirm it on the Leakage tab: …") is built on PARLEML_PUBLIC_URL, the web app's origin — unset, on the origin the agent's MCP call arrived at, which is the backend. In local development the app runs on Vite, so set it in the backend's environment (or its .env) before starting the backend:

$env:PARLEML_PUBLIC_URL = "http://localhost:5173"

Without it the links open http://127.0.0.1:8000/…, the API, not the app.

Finding the CLIs. Each *_BINARY is a name looked up on PATH (with PATHEXT on Windows) or a full path. On Windows npm installs Codex, Gemini CLI and often Claude Code as .cmd shims; the runtime runs the shim's Node script directly, so no argument passes through cmd.exe. Any other .cmd or .bat does run through cmd.exe and is refused an argument holding %, ^, &, |, < or >; point the variable at the executable instead. Stopping a session ends the CLI and every process it started.

Routing and authoring calls. Routing, skill-attribute suggestions and AI annotations use the shared ask() gateway: bounded, tool-free model calls with schema validation and one repair retry for malformed output. It tries the profile's agent, then its allowed_agents, then the other available agents on the server. All four adapters are supported; unavailable or quota-paused agents are skipped. If none answers, routing uses the local word scorer and authoring reports that suggestions are unavailable. Provider limits pause the affected agent until its reset time (15 minutes when no reset is given); the next call can use another ready agent.

Provenance¶

Whatever a session step creates records created_by_id = svc:<token_id>, the per-attempt token it worked with. GET /api/provenance/{actor_id} answers who that was:

`kind`	When	What it names
`agent`	`provenance/<token_id>.json` exists	The session and step, attempt, workspace, skill, CLI and model, and the person the session works for.
`token`	a `svc:` id with no such file	A token a person minted (Settings → Access).
`person`	anything else	A person.

The file is written when the token is minted, before the agent gets it (a token whose origin cannot be recorded is revoked, not handed out), and it outlives the token. After a session is deleted, the ids still resolve; the titles, CLI and model are then empty.

Save discipline¶

Details: how saves stay consistent

Configuration writes lock the resource across reading, checking its version, validating a private candidate and atomically publishing it. Settings and profiles use the same primitive. Pack and skill edits, native rules/hooks and session snapshots share a file lock; multi-file changes are staged and validated before the folder is published. Connection edits and deletion require the connection's If-Match version, including credential changes; failed saves restore the registry and encrypted vault. A stale save returns 412. Stdio tool servers store the executable and each argument separately, without parsing a display command back into configuration.

MLflow clients resolve the saved connection for each operation. Deployment MLFLOW_* values override saved values. Credentials exported for a backend operation are restored afterward; dedicated experiment workers keep their own resolved environment. Editing or removing a saved connection therefore does not leave a derived environment cache in the backend.

Local inference providers¶

The profile agent block also supports provider: {kind: ollama, endpoint: "http://127.0.0.1:11434"} with an installed model ID. Configure it in the Runtime profile editor. See Local models for Codex/Claude support, tier inheritance, provider-aware readiness and a full example.

Next¶

Skill attributes: the parleml-* keys a skill declares.
Credentials & logins: how each agent signs in.