Skip to content

Agent sessions

In short

  • An agent session is a coding agent that ParleML runs on its own server, on your subscription or API key, to do ML work in one workspace.
  • The standard image ghcr.io/parleml/parleml:0.8.0 includes Codex CLI and Gemini CLI; Codex is the default. Claude Code and Cursor come with the extended image, which you build on top of it (Which agents can run).
  • Start one from the ✦ Agent menu on any object, from Home, or from a workspace's Sessions page. The agent works through ParleML's MCP tools and never writes ML code.
  • Every decision that is yours arrives as a question with the agent's proposal first. You can type to the agent while it works; your message never interrupts a model turn.
  • Stop keeps everything resumable; jobs the session launched keep running.

An agent session is a coding-agent CLI (Codex, Gemini CLI, Claude Code or Cursor) that ParleML runs on its own server, on your subscription, to do ML work in one workspace. The agent works through ParleML's MCP tools — it never writes ML code — and asks you whenever a decision is yours.

A session is an orchestrator (one of ml-delivery, ml-investigate, ml-operate in the shipped pack) and the steps it starts (ml-frame, ml-data, …). Which CLI and models it uses comes from the workspace's agent profile.

Which agents can run

Agent In the standard image How to get it
Codex CLI yes, pinned to 0.162.1; the default agent nothing to install
Gemini CLI yes, pinned to 0.62.0 nothing to install
Claude Code no the extended image, --build-arg WITH_CLAUDE=1
Cursor (through Cursor's SDK) no the extended image, --build-arg WITH_CURSOR=1; needs CURSOR_API_KEY

Claude Code and Cursor's SDK carry no redistribution grant, so the standard image cannot ship them. The extended image is not published: you build it on top of the standard image, from the recipe the image carries at /opt/parleml/Dockerfile.extended:

docker run --rm ghcr.io/parleml/parleml:0.8.0 cat /opt/parleml/Dockerfile.extended   | docker build --build-arg BASE=ghcr.io/parleml/parleml:0.8.0 --build-arg WITH_CLAUDE=1 -t parleml-claude -

Add --build-arg WITH_CURSOR=1 for Cursor. Run parleml-claude in place of the standard image, with -e PARLEML_AGENTS_HOST_ADAPTER=claude-cli to make Claude Code the default agent (Run ParleML). Every agent still needs a sign-in on the server (Credentials & logins). A session on an agent the server lacks fails its preflight with "CLI not found".

Starting one

  • From an object (dataset, experiment, model, knowledge base): the ✦ Agent menu. Continue reopens this object's sessions; Suggested next steps come from the workspace brief, in lifecycle order (framing before data, data before any model); Tasks are the profile's orchestrator skills, each with its one-line parleml-summary; Agent picks which of the profile's agents runs it, each shown with the sign-in its CLI would use (which sign-in), or "not installed" for a CLI this server lacks; Ask or describe the work routes free text to the right skill and shows what would start ("nothing is created until you press Start") — once a task is picked, the same box reads Instructions for this task (optional).
  • From Home: Work with an agent — a question, a workspace, a task (or Let ParleML suggest), the agent, the route preview, Start.
  • From a workspace: Sessions → the start box.

You may attach files to the first message; they are stored with the session and the agent reads them from disk (25 MiB per file, at most 20 files). Before anything is created, preflight checks the profile: the CLI is installed and signed in, the packs load, the connections answer. A failed check refuses the start and says which check failed.

Following one

The session page shows:

  • the header: title, state chip, the agent (CLI · model · effort · where it runs), Stop and the ⋯ menu (Cancel, Archive, Follow in the side pane, Delete transcript); its meta line names the attached object, who started it and when, and the agent profile with the version it runs on (the first twelve characters of the profile's digest, as the profile page shows it);
  • the banners that say why it is not moving (stopped, provider limit, sign-in needed, the profile changed, lost process, a decision waiting elsewhere), each with its one action (Recovery & resume);
  • the Now line with Follow active (on by default: it keeps the conversation of the step doing the work on screen and, when the work ends, shows the run that finished last, usually the orchestrator); a session that has ended has no Now line — the header says how it ended. The stage strip groups activity under optional labels such as Frame · Data · Model · Decide · Operate. Labels and their display order do not assign ownership or constrain execution. A failed step is marked recovered only after a successful retry of the same skill under the same parent. and the flow map — steps, each titled by its skill, decisions and the objects each step created, as leaves under that step: a recipe, the dataset it materialised (named by its dataset name), an experiment (named by its experiment name; its live status, score, the score change against its parent — a run that only repeats its parent reads "±0 vs parent" — and pipeline), with an inspector (Open skill for an administrator, back to the session from the skill page), a list view and full screen. A map too large to read whole opens on the open, working or latest step at a readable zoom, and Follow active keeps the active step centred; full screen and the fit button show the whole map;
  • the conversation of the orchestrator or of one step, with evidence panels (the same panels an external MCP host shows), job cards that follow a training run or a scoring job live, an EDA finished card, recorded decisions, and the ids of the objects the session's calls returned turned into links to their pages;
  • the rail beside the conversation. It starts wide and its toggle narrows it (the choice is kept for the browser session). Its tabs:
  • Context: what the session is attached to and was asked, the workspace brief every step reads first (goal, datasets, the models in production and shadow, best, running, leakage, next-step hints), the open step's briefing, and the steps that run on a second agent;
  • Summary: the outcome, the model in production against the best comparable experiment, the decisions recorded and what each was approved against;
  • Files, switching between Documents (the agents' working documents, each with Publish; the workspace documents this session published; the evidence the agent showed) and Changes (what the session changed against the workspace as it found it — an experiment's settings and column roles against its parent, a recipe's SQL against the session start — each with its +/− counts and opening as a diff in the main column; then every object it created, changed or read, and Show its experiments in the experiment tree);
  • Status, and — behind Details — Usage (CLI version, model, attempts, tokens).

A single-agent session — one adaptive skill such as ml-investigate that answers a question itself and has started no steps — keeps these tabs, but its Context says what it is: the question, what it is about, the skill (adaptive, no steps), the access its token carries (its parleml-scope) and what it was briefed with; and its Summary is the answer (its reported outcome) with the decisions it asked, open ones first.

Opening a step, a decision or the Now line always shows the conversation: a file or a diff open in the main column closes on the way.

The session pane follows one session beside every page; when a step waits for a decision, the pane shows that step's conversation so the decision is answered in place. Collapsed, it is an edge tab "1 working · 1 waiting on an experiment · 1 needs you", and the page keeps the tab's width clear so it covers nothing. The Needs attention pill in the top bar lists every open decision and halted session.

The workspace's Sessions page has Needs attention, In flight, All and Archived tabs. The workspace header carries the ✦ Agent menu (start a session about the workspace) and, while a session is live, its stage strip and Now line. The Overview's Sessions lens offers Show its experiments, which highlights the experiments that session produced in the experiment tree.

Details: the API behind these views
  • The pill's counts come from GET /api/agent/runs/count, which takes the same filters as the session list (status, live, scope_id, attention, archived, …).
  • Show its experiments reads GET /api/workspaces/{id}/sessions/{root_id}/experiments.
  • Attachments go up with POST /api/agent/runs/with-uploads.
  • Publish calls POST /api/workspaces/{id}/documents/publish with the session, step and path.
  • The Changes diffs come from GET /api/workspaces/{id}/object-diffs with the experiments (experiment=) and recipes (recipe=<knowledgebase_id>/<recipe_id>) the session's calls changed and since (the session start): each experiment's settings (as JSON) and column roles against the parent it recorded at creation, each recipe's SQL against its newest version before since, as unified patches with their +/− counts.

Decisions

Every question puts the agent's proposal first, marked proposed and pre-selected (approvals are marked but never pre-selected). Or answer in your own words sends your text verbatim. An approval offers Approve with changes: you approve and write what should change, and the agent applies it and carries on — no need to decline in order to narrow a step. A decline asks for a reason, which the agent reads as its next instruction and revises. Decide automatically never approves with changes, and answers only when the agent proposed a complete answer, and records it as Auto-approval · System (details).

A delivery session asks you everything only you can settle as a question with an answer field, never as a paragraph to weigh: the template its framing proposes from your requirements (latency, explanations, compute) and the data's shape; each open question a step could not answer (how and when a column is filled, how the labels are made); a doubt about a top driver, before it iterates on it; and at the release, each condition of a pass with conditions challenge — confirm, or cannot confirm and its fallback. Your answers are recorded with the decision and carried into the model's notes.

The workspace's Decisions page lists every question asked across its sessions, open ones first with Review and answer, with the step that asked it, who decided (marked Approved with changes when they set changes) and how long it took, and what it was bound to: the snapshot it was approved against and its record in the conversation (GET /api/agent/decisions?scope_id=…).

Talking to it while it works

Type in the footer while the agent works and the message is queued (POST /api/agent/runs/{root_id}/messages): it never interrupts a model turn. The footer says who reads it and when (its delivery, below). It reaches the agent with the result of its next session tool — the end of a step, an answer, or a job wait, which a queued message ends early so the agent reads it now rather than after a three-hour training run. Until then you can remove it. A message to a step that ends first goes to the orchestrator. Messages to a stopped or failed session wait and ride along with Resume.

A message goes to the orchestrator unless you address a step. While the orchestrator waits on a working step it reads nothing until that step ends, so address a message meant for the step's work to the step. Delivered messages stay in the conversation, attributed to you. At most 20 can wait at once, 4,000 characters each.

Details: when a queued message is read

A message is addressed to a step by its run_id. Each waiting message carries its delivery: the run that will read it and when — next_tool_result, after_steps (with the steps it waits on), follow_up (it reopens a finished session) or on_resume (a person must resume first).

When a session has finished, the footer becomes Your turn: Send reopens it with your follow-up (a resume with a message), and messages queued as it finished are sent the same way automatically.

Stop, resume and limits

  • Stop halts the agents; jobs they launched keep running and open questions stay answerable. Resume continues; queued messages ride along.
  • A provider limit (the 5-hour window, a weekly cap) is shown as "Paused · provider limit · resets 17:30 (in 2h 14m)" when the CLI stated a reset time, names the agent whose account hit it, and says it is not a ParleML failure. Resume automatically when the limit resets (off by default) resumes it then; Resume now and Cancel session sit beside it.
  • Sign-in needed shows the fix, for example "run codex login on this machine".
  • An attempt limit (turns or wall clock) keeps what was done; retrying starts another attempt with a fresh budget (Limits).
  • A lost process (a server restart) is shown and resumes from the banner; nothing in the transcript is lost.

Documents

Publish in the Files tab or the reader copies a work file into the workspace. The document records the session, step and skill it came from and who published it, and outlives the session. Publishing the same path again adds a version (201); unchanged content adds none (200), though a new title still renames it. Documents are at most 5 MiB and are stored under <data_root>/workspaces/<id>/documents/. The workspace's Documents page lists them with their versions and a reader.

Archive and delete

Archive hides a finished or stopped session from the in-flight lists and keeps it whole; resuming brings it back. Delete transcript (a cancelled or finished session only) removes the conversation, its steps, its uploads and the agents' working files; experiments, recipes, models and published documents stay. A link to a deleted session shows what it was, how it ended and who deleted it, from its tombstone (GET /api/agent/runs/tombstones/{root_id}).

Where things are

Page What
Configuring agents The configuration folder, profiles, the ML pack, the Settings pages, environment variables, provenance.
Skill attributes The parleml-* keys in SKILL.md.
The session MCP The tools a session gets, questions, auto-approval, Cursor's deferred operations.
Recovery & resume What is authoritative, crash repair, resume vs retry vs follow-up, failures, delete and tombstones.
Limits Turns, wall clock, batch size, message, upload and file caps.
Host-native rules & hooks Pack rules and hooks per CLI.
Credentials & logins CLI logins, vault:// secrets, minted ParleML tokens.
Data on disk The files, what survives a restart, backing up, starting over.
Operations & security Pinned CLI versions, upgrades, recovery drills, security notes.
Local models Running Codex or Claude Code on Ollama or LM Studio.

Next