LoRA Training

​

train_prepare_dataset

• action:“prepare” — Stage training images + captions into a dataset dir the trainer consumes. Each item is an image (absolute path, OR a ComfyUI ref {filename,subfolder?,type?} resolved against the connected ComfyUI’s output/input dirs — how phone/panel pickers hand over selections) with an optional caption (a missing caption falls back to defaultCaption — typically the trigger word). Requires name + items. Returns the datasetPath to pass to train_start (action:“start”). Character LoRA guidance: 10-30 varied images; caption what changes between images, keep the trigger word constant.
• action:“list” — List staged datasets, newest-first, with image/caption counts. Read-only, takes no other parameters. Pair with action:“detail” to see one dataset’s images + captions.
• action:“detail” — Show ONE staged dataset by name: its dir (datasetPath — reusable as train_start’s datasetPath) and every image with its caption (null when uncaptioned). Images render via action:“file”. Read-only.
• action:“update” — Edit a staged dataset by name: set/replace per-image captions (setCaptions) and/or delete individual images with their caption files (deleteImages). Refuses while a running/queued job trains from it. Returns per-file warnings for unknown files. This is the SURGICAL edit — it removes only the filenames you list, leaving the dataset itself in place.
• action:“delete” — DESTROY a whole staged DATASET by name: every image and every caption under it. Irreversible, and the images are typically hand-curated and unrecoverable — confirm with the user first. Refuses while a running/queued job trains from it. THIS DELETES A DATASET, NOT A TRAINING JOB: to delete a finished job’s record and checkpoints use the separate train_start tool with action:“delete”, which is keyed by id rather than name. To remove only SOME images, use action:“update” with deleteImages.
• action:“file” — Fetch an image under the training root (dataset image, job sample) by absolute path as an inline image — the tunnel-safe way for a phone/panel to render training files it can’t reach over /view. Bounded: image files only, ≤ 2MB.
• action:“caption_image” — Caption ONE image by absolute path with the user’s own Claude subscription (one vision turn through the Agent SDK — not a paid API). Returns the bare caption and does NOT write it — review, then save with action:“update”, or use action:“caption_dataset” to write directly. Optional guide steers the style; optional trigger is prepended by the model.
• action:“caption_dataset” — Caption a whole staged dataset by name (or the only subset) with the user’s own Claude subscription and WRITE the captions into its .txt files (one vision turn per image, sequential). Captioning ALWAYS runs through Claude (Agent SDK) regardless of the panel’s active backend, so it needs a logged-in Claude Code session (or ANTHROPIC_API_KEY). Use after gathering images, before train_start (action:“start”). Per-file transient failures are reported without stopping the batch, but a persistent auth/credential failure stops immediately with an actionable error rather than failing every image. Optional guide steers all captions; optional trigger is prepended to each.

​

Parameters

​

Example

{
  "tool": "train_prepare_dataset",
  "arguments": {
    "action": "prepare",
    "name": "aria_character",
    "items": [
      {
        "path": "/photos/aria_01.png",
        "caption": "ohwx person, side profile, window light"
      }
    ],
    "defaultCaption": "ohwx person"
  }
}

​

train_start

• action:“start” — Start a LoRA training job: target ‘local’ builds the config and launches the GPU trainer container (docker run —gpus all); target ‘pod’ ssh-drives pod-native training on a connected RunPod pod (pod_id, or the connector’s currently connected pod). Requires name + datasetPath. Returns a job id for action:“status”/action:“cancel”. Long-running — returns immediately; poll action:“status”. On completion the LoRA is delivered per deliverTo (pod/local/both) and cataloged when local. Run train_doctor first if unsure the image/docker/GPU (local) or bootstrap (pod) are ready.
• action:“status” — Check training progress: pass an id for one job (step/total, loss, recent samples, log tail, result paths when done) or OMIT id for all jobs newest-first. Read-only.
• action:“cancel” — STOP a RUNNING job (docker stop) by id and mark it cancelled. Nothing is erased: checkpoints already saved stay in the job’s output dir; no LoRA is handed off to models/loras, so the run can be inspected afterwards. Returns ok:false when the container could not be confirmed stopped (the job reverts to running). This is the RECOVERABLE stop — use action:“delete” only when you also want the artifacts gone.
• action:“delete” — DESTROY a finished job by id: its record AND its output dir with checkpoints/samples, unless keep_outputs is true. Irreversible — confirm with the user first. The delivered LoRA in models/loras is NOT removed. Running/queued jobs must be cancelled first (action:“cancel”). THIS DELETES A JOB, NOT A DATASET: to delete the staged images and captions a run consumed use the separate train_prepare_dataset tool with action:“delete”, which is keyed by name rather than id.
• action:“list_flows” — List the LoRA training flows and base models the local trainer supports (phase 1: character LoRA on FLUX.1-dev), with the default training params. Read-only, takes no other parameters — call this first to see what action:“start” accepts.
• action:“job_config” — Show the effective settings a job ran with by id (steps/lr/rank/resolution/batch/saveEvery/sampleEvery/quantize), read back from the ai-toolkit config.yml it consumed, plus flow/model/trigger/datasetPath — everything needed to run the job again with tweaks. Read-only.
• action:“preview_config” — Show the RAW ai-toolkit config.yml action:“start” WOULD write for these settings (the ostris-UI ‘raw config’ view) — no side effects, nothing is written or started. Requires name + datasetPath. Use it to review a run before launching; pass the same params to action:“start” to execute.

​

Parameters

​

Example

{
  "tool": "train_start",
  "arguments": {
    "action": "start",
    "name": "aria_character",
    "datasetPath": "/home/me/.comfyui-mcp/training/datasets/aria_character",
    "trigger": "ohwx person"
  }
}

​

train_doctor

• action:“doctor” — Preflight the local trainer: docker daemon reachable, --gpus all GPU passthrough working (NVIDIA Container Toolkit), trainer image built. Read-only, takes no other parameters. Returns per-check booleans + setup hints. Also reports the training data root and whether HF_TOKEN is set (needed to download FLUX.1-dev on first run), the native (dockerless) bootstrap status, and the connected pod. Run this first when a training start fails.
• action:“bootstrap” — Set up the NATIVE (dockerless) trainer on this machine (target ‘local’, the default) or on a pod (target ‘pod’, optional pod_id): clone ai-toolkit at the pinned commit, create its venv, install torch + requirements. One-time per machine/pod (~10 min fresh, idempotent; a pod’s /workspace persists it across restarts). Needed before a target ‘pod’ train_start on a fresh pod (no docker there). Long-running.
• action:“build_image” — Build the headless GPU trainer image (comfyui-mcp-trainer:latest) from docker/trainer/Dockerfile — one-time, several minutes (CUDA + torch + ai-toolkit). Requires a reachable docker daemon. aiToolkitRef pins the ai-toolkit commit/tag for reproducibility. The docker alternative to action:“bootstrap”.

​

Parameters

​

Example

{
  "tool": "train_doctor",
  "arguments": {
    "action": "doctor"
  }
}