WORKSPACES.md

Workspaces

A workspace is the directory your own content lives in: the workflows you write, the prompt library they reference, the assets they read, and the files they generate.

<workspace>/
  workflows/    your workflows
  prompts/      the stored prompt library ('prompt:' references)
  assets/       input media
  outputs/      generated files

It keeps day-to-day work out of a checkout of this repository: the repo's workflows/ is a corpus of examples to read, copy and run, and generated media does not belong in a source tree.

Which directory is used

The workspace is resolved by dw.serve. python -m dw.run is a client of a running dw.serve, so it resolves no directory of its own: its jobs land in the server's workspace. First match wins:

1. --workspace <dir> on dw.serve
2. the DW_WORKSPACE environment variable
3. "workspace" in ~/.diffusers_helper/settings.json
4. the working directory, when it holds any of workflows/, prompts/ or outputs/
5. ~/diffusers-workspace

Rule 4 means a checkout serves itself: the repository root holds all three folders. Rules 1-3 are explicit; rules 4 and 5 are inferred, which matters for the prompt library (below).

Resolving creates nothing. dw.serve creates the workspace's workflows/ (unless --workflow-dir was given) and assets/ at start, and a run creates its output directory.

dw.run --workspace NAME is a different thing: it names one of the server's workspaces (the default one, or a named one beside it), not a directory. A path there is refused as a workspace name rather than resolved.

Overriding one folder

--workflow-dir, --prompt-dir, --asset-dir and --output-dir on dw.serve each override one folder of the workspace. dw.run takes none of them; every job it queues writes where the server does.

python -m dw.serve --workspace ~/studio --output-dir /mnt/big-disk/renders
python -m dw.serve --prompt-dir ~/shared-prompts

--output-dir is the usual one: video work fills disks.

Working in a workspace

mkdir -p ~/studio/{workflows,prompts,assets,outputs}
export DW_WORKSPACE=~/studio

# or, standing, in ~/.diffusers_helper/settings.json
#   { "workspace": "/home/you/studio" }

python -m dw.serve                       # serves ~/studio
python -m dw.run ~/studio/workflows/x.json   # queued on that server

An example from a checkout still runs by path, and writes into the server's workspace's outputs; dw.run itself does not read DW_WORKSPACE:

python -m dw.run ~/src/diffusers-workflow/workflows/templates/text-to-image.json

A file the server cannot read is sent to it inline, and its relative paths then resolve against the server's workflows/.

The server reports what it resolved at GET /api/server, under directories.workspace alongside the three folder paths.

The prompt library

dw.serve resolves the prompt library once at start and pins it for every job, first match wins:

1. --prompt-dir, then DW_PROMPT_DIR
2. the workspace's prompts/, when the workspace is explicit (rules 1-3), even if it does not exist yet
3. ./prompts in the working directory
4. the nearest prompts/ at or above the workflow directory
5. the workspace's prompts/

So a standing DW_WORKSPACE or "workspace" setting stops a checkout's ./prompts being found; an inferred workspace does not. See Prompt References.

Assets

assets/ is the input-media library. A workflow argument written as asset:name.ext (or asset:folder/name.ext) resolves to that file's path, rooted at the library rather than at the workflow file. --asset-dir overrides the folder. Browser uploads land in assets/uploads/ and come back as asset:uploads/<name>, served for preview under /inputs/ (the UI's own bundles own /assets/).

A generated file becomes an input the same way: Keep as asset in the gallery (POST /api/assets/keep, keep_output over MCP) links or copies it out of outputs/ into assets/ under a name you choose, so a later workflow carries asset:<name> rather than a run id that pruning would break. The copy stays inside the workspace — a hard link where the filesystem allows one, so keeping one frame of a large render costs no second copy of it. See Asset References.

Where workflows are read from, and written to

The server reads workflows from a search path and writes them to exactly one place — the front:

<workspace>/workflows/    yours, writable — every save lands here
<--examples-dir>          read-only, repeatable

A name found in an earlier root shadows the same name in a later one, so a workspace copy of an example is the one that runs. Reads — listing, opening, downloading, validating, running — span the whole path. Saves and deletes do not: PUT always writes into the writable root, and deleting something from a read-only root is refused with a 403 that says where it came from.

That makes "open an example, change it, save" do the obvious thing: the copy lands in your library and shadows the example from then on, and the example itself is never touched. It is also what stops an agent's saves landing in a checkout — point --workflow-dir (or --workspace) at your own directory and the repository's workflows at --examples-dir:

python -m dw.serve --workspace ~/studio --examples-dir ~/src/diffusers-workflow/workflows

GET /api/workflows reports the path as libraries ([{origin, root, writable}], in search order) and tags every entry in details with its origin and writable, which is how the UI knows to hide delete and how an MCP client can tell what it may change. The writable root is the libraries entry with writable: true and origin: "workspace"; a copy an example's name hides is listed under shadowed.

The prompts and assets an examples tree brings with it

An example workflow references the prompts and media that live beside its tree, not the ones in your workspace, so each --examples-dir puts those on the back of the two libraries as well: the prompts/ and assets/ folders beside the directory (or inside it, if that is where they are). Both libraries work exactly like the workflow path — your workspace's own is searched first and a name there shadows the example's, reads span everything, and writes only ever reach your own:

<workspace>/prompts/      yours, writable — every save lands here
<--examples-dir>/../prompts   read-only

<workspace>/assets/       yours, writable — uploads and "keep as asset" land here
<--examples-dir>/../assets    read-only

So the command above makes workflows/models/flux-dev.json's "prompt:flux/biomechanical_daffodil" resolve out of the checkout, without copying the prompt library into the workspace. GET /api/prompts and GET /api/assets report the roots as libraries, the same envelope as the workflow listing, and tag each entry with its origin and writable; deleting a prompt that came from a read-only library is refused with a 403, and saving one writes a copy into your workspace the way saving an example workflow does.

The packaged workflows in dw/workflows/ are not on the path: they are what a builtin: sub-workflow step names (GET /api/builtin-workflows lists them), not workflows to browse or run on their own.

Runs

Each execution writes its own directory under the output folder, named by the workflow and the run:

outputs/
  ltx2/Gyre/
    20260905-181530-a1b2c3d4/
      Gyre-still.0-0.0.png
      Gyre-video.1-0.0.mp4
      manifest.json
      workflow.json

The folder is the workflow's identity — its path under a workflows/ tree when it has one, its file name otherwise, its id for an inline definition. The run id is a timestamp plus a short digest of what actually ran, so two runs of the same workflow sort by time and a rerun of an edited workflow is visibly different; a second run of the same spec in the same second takes a counter rather than sharing a directory.

workflow.json is the realized workflow — the definition with this run's arguments, seed and stored prompts pinned into it, so the directory reproduces itself. manifest.json points at it and lists which prompts were inlined.

manifest.json records the run beside what it made — status, seed, arguments, device, dw version, and each step's files, named relative to the directory so it keeps describing itself if you move or copy it. It is written even when a run fails part way, since the files it did write are on disk either way. A sub-workflow is part of its parent's run: it writes into the same directory and rolls up into the same manifest.

A pipeline step that ran also carries timing in its manifest.json entry (and in the same entry of the job's manifest from the API or MCP get_job): load, encode, denoise, decode and save seconds. A reused, task or composed step has none. See Step timing.

An unchanged rerun still reuses the step cache: it writes no new files and its manifest reports the earlier run's, marked "reused": true. The cache is validated against the output root a run writes into, which is the pinned workspace's own outputs/ - so it is per workspace, not per workflow alone. A run in one workspace does not make validate_workflow's plan.cached_steps come back nonzero for a matching run sitting in another workspace, and deleting a workspace drops its cache entries along with its outputs/ directory. The cache itself is also per process: entries are held in memory by the running server, not read back from outputs/, so a dw.serve restart empties it even though every run directory is still on disk - a plan.cached_steps of 0 right after a restart is expected, not a lost run.

For the same reason, two dw.serve processes on the same workspace share no cache entries: a run on one server is a cache miss on the other, even though both read the same outputs/. To avoid recomputing, either use one server with --devices cuda:0,cuda:1, whose identity affinity sends a rerun back to the card that holds it warm (see SERVER.md Choosing the card), or, with two servers, split the work so each server only reruns what it ran itself: submit each arms file (or job set) to one server, and never resubmit another server's arms expecting hits.

A later workflow names what an earlier run made with an output: reference — output:ltx2/Gyre/latest/Gyre-still.0-0.0.png — so a multi-stage pipeline no longer needs files copied back by hand. See Output References.

Each step's entry in manifest.json records its role, final or intermediate (and role_declared when the step's result.role stated it), from that one run's data flow. The gallery reads across runs as well: a file a later run in the same workspace read - by an output: reference, or by an asset: that keep_output kept from it - lists as intermediate, so a project's shots, narration and score stop reading as finals once the assembly that cuts them has run. Nothing is rewritten; a role result.role declared final stays final, and a run from before roles stays unknown. See dw/roles.py.

To keep the previous layout — everything at the output root, with only a workflows/-mirroring subfolder — use --output-layout flat, DW_OUTPUT_LAYOUT=flat, or "output_layout": "flat" in settings. Scripts that glob the output directory are the reason to.

Step timing

A manifest entry for a pipeline step that ran - in GET /api/jobs/{id}, in MCP get_job, and on that step's step_end event - carries timing: where the step's time went. It is measured in the worker on its monotonic clock, not taken from event timestamps, because the job keeps only the last 200 events and the load and encode events are gone from a long job. Every _s is seconds to 0.1. A field whose mark never happened is null, never guessed.

Field	Meaning
load_s	Loading or fetching the step's pipeline, cached or not
load_cached	true if the pipeline came from the worker's cache, false if any part loaded fresh, null if the step loaded nothing
encode_s	Call start to the first denoiser forward (or a modular pipeline's denoise bar opening): prompt and reference encoding and preparation
denoise_s	First denoiser forward to the last pass's end. The whole call when the pipeline reports no passes; encode_s and decode_s are then null
passes	Denoise passes the pipeline actually ran: one per iteration of its denoise loop, so one per scheduler timestep. This is not always num_inference_steps: SD 1.5's default PNDM scheduler runs 21 passes at 20 steps (N+1 from 2 steps up). denoise_s ≈ first_pass_s + (passes − 1) × pass_s
first_pass_s	The first pass, which carries any compile warm-up
pass_s	Median of passes 2..n; null with fewer than two passes
compiled	The denoiser runs through torch.compile
decode_s	Last pass's end to the call's return: VAE decode and post-processing
save_s	Writing the step's files
segments	Pipeline calls summed into this timing. A chain step sums its segments into one timing with segments: N; a step that iterates counts each call. 1 for a plain step

A step that set a cache also carries timing.cache: {type, threshold, forwards, computed, skipped, hit_rate}. forwards counts denoiser forwards, not steps - classifier-free guidance runs two per step (cond and uncond), so it is a whole multiple of passes - and computed + skipped == forwards; hit_rate is skipped / forwards to 3 places. A chain sums the counts over its segments. Counted for first_block and mag (mag also reports num_inference_steps, max_skip_steps, retention_ratio, calibrate); taylorseer (with cache_interval, max_order), faster and text_kv keep no per-forward decision in diffusers, so they report type and their config keys with threshold and every count null. A step with no cache has no cache key. If the installed diffusers moved the hook state dw reads, the counts are null and one warning event with kind: "cache_stats_unavailable" is emitted; the run never fails for it. The same fields arrive live as a cache_stats event (SERVER.md). See Reading the skip counts.

A step served from the step cache (reused: true) has no timing, nor does a task step or a composed (sub-workflow) step. A failed or cancelled step has no manifest entry, so no timing. Job summaries and history are unchanged.

Host-memory history

Each finished job's history row records a memory_key: a digest of the run's pipeline identities (component_type, model_name, workflow of every pipeline step) and every quantization_config, offload and group_offload value, with the caller's arguments resolved. The workflow's name is not in it, so a renamed or inline copy of a template shares the template's history, and a different weights_dtype or offload is a different key. From it the server projects a run's host-RAM peak: observed (the largest job peak RSS among this machine's successful runs with the same key), else fit (the list-run projection from the workflow's own history), else no figure. A workflow's declared host_ram_gb is a floor under that figure (basis declared when it is the larger). Rows recorded before the column existed have no key and count as no data. Validate reports it as plan.host_memory.

Several workspaces on one server

Everything above describes one workspace. dw.serve goes one step further: the workspace root can hold several, and a client picks which one it is working in - dw.run --workspace NAME among them.

<workspace root>/
  workflows/  assets/  outputs/    <- the 'default' workspace
  prompts/                         <- shared by all of them
  loras/                           <- the LoRA catalog, shared by all of them
  common/assets/                   <- shared by all of them
  studio/
    workflows/  assets/  outputs/  <- the 'studio' workspace
  scratch/
    workflows/  assets/  outputs/  <- the 'scratch' workspace

The root's own three folders are the workspace named default. A named workspace is a sibling directory holding the same three folders and no prompts/: there is one prompt library, because a prompt: reference duplicated per workspace would resolve to different text depending on where a workflow was saved.

Reserved names, which no workspace can take: workflows, prompts, assets, outputs, exports (where POST /api/jobs/{id}/export gathers a job, <root>/exports/<job id>/), common and loras (the LoRA catalog, shared like prompts/). A pre-existing workspace named loras stops being listed, and the server logs a warning at start naming its directory.

The shared asset library. common/assets/ holds assets that belong to no single workspace, such as a recurring cast's portraits and voice clips. It sits on every workspace's asset search path behind that workspace's own library, so:

• asset:cast/priya.png resolves in the workspace first, then in the shared library, then in any read-only examples library — a workspace's own name still shadows a shared one
• GET /api/assets spans all of them and tags each entry's origin: workspace, common, or examples
• writes still land in the workspace unless they say otherwise: POST /api/uploads?shared=true, POST /api/assets/keep with "shared": true, and over MCP upload_asset(..., shared=True) / keep_output(..., shared=True)

It holds assets only. A prompt is already shared, and workflows and outputs belong to the work that made them.

Two agents can share the server's GPUs without sharing a namespace: each takes a workspace, and neither can save over the other's workflows or delete the other's renders. The queue is shared and the engine runs one job per GPU (dw.serve --devices), so their jobs run side by side when each fits a free card, and queue otherwise.

How a client picks one. Every scoped route takes an optional ?workspace=<name>; omitting it means default. GET /api/jobs spans every workspace unless one is named.

Client	How
Web UI	The sidebar lists every workspace; the selected one is named in the hash (#/ws/<name>/...), so a link and a reload both land where they say. The choice is remembered in localStorage as a fallback for a route that names none (Shared, Server), and Server → Status adds a filter over the all-workspaces queue — job history spans every workspace there and says which one each job ran in
MCP	list_workspaces, then use_workspace(name): a session default, so switching is one visible step in the transcript. Most tools also take workspace= per call; over a shared /mcp mount see REMOTE.md
HTTP	?workspace= on the route, or "workspace" in a POST /api/jobs body
Web UI (create/delete)	The sidebar's + new creates one; a workspace's own Overview page deletes it (disabled for default)

A job carries its own workflow, asset and output directories, so it stays in the workspace it was submitted from however many others the server serves while it runs — including through a rerun, and when its files are served back from history.

Creating and deleting. POST /api/workspaces (create_workspace over MCP) makes one; creating does not switch to it (over MCP, unless use=true). Deleting removes everything in it, so it refuses until acknowledged and answers first with what it would remove — file counts and bytes per folder. The default workspace cannot be deleted (it holds the shared prompt library, and there has to be somewhere to work), nor can one with jobs still queued.

A workspace is a namespace, not a security boundary. The API token is all-or-nothing: anything that can reach the server can name any workspace on it. Use them to keep work apart, not to keep it private.

Copying between workspaces

A run is self-contained on disk, so copying its folder into another workspace's outputs/ is what makes it resolvable there. copy_to_workspace (MCP) and POST /api/workspaces/{destination}/copy (SERVER.md) do that for runs, named <workflow>/<run id> or, for all of a workflow's runs, a bare <workflow>, and for assets, named as after asset: (cast/iris.png, or a folder such as proj/ for every file under it). An asset keeps its library-relative path, so uploads/ stays uploads/ and an asset: reference means the same file in both workspaces. Its note and its kept-shots entry (the folder's notes.json and manifest.json, including where it was kept from) are merged into the destination folder's own sidecars, which are written fresh: naming a sidecar directly is a 400, since it travels with its files.

Media is hard-linked, so a copy costs almost no disk, falling back to a real copy across devices. JSON sidecars (the manifest, workflow.json, notes, any .json) are always copied, never linked: they are edited in place, and a link would carry an edit in one workspace into the other. Nothing follows or creates a symlink.

The copy is all or nothing: every entry is checked before anything is written. A run whose run id the destination already has is the same run, so it is skipped and listed as already_present, and repeating a copy changes nothing. A run whose job is still queued or running is refused, since its manifest is not final. An asset the destination already holds with the same bytes is skipped as already_present too; a different file at that path is a conflict, never replaced. Every conflict, runs and assets alike, is named in one 409 before anything is written.

Because a copied asset is a hard link, nothing edits media in place: an upload over an existing name writes a new file and renames it into place, and keep_output and delete_asset unlink first, so an edit in one workspace never reaches the other.

A run keeps its vN unless the destination already uses that number for the workflow. Then this request's runs of that workflow are renumbered after the destination's highest, in run-id order, under the run lock so a concurrent run cannot take the same number. renumbered reports each from and to. Pinned output: references name run ids, so none of them break.

The reply carries warnings, not refusals: unresolved_output_refs (a run's output: input that does not resolve in the destination), absolute_paths (manifest paths that still point into the source workspace, reported relative to the source workspace's root) and no_jobs. A copied run has no job record, so it appears in the gallery and resolves as an output: reference, but not in list_jobs.

A move is a copy, then a delete of the source runs (delete_output, or DELETE on the gallery runs) and assets (delete_asset); there is no move that could lose a run halfway.

Running a sweep

A sweep answers one quality or speed question by rendering the same request under several configurations, changing one factor at a time, and keeping the results together. There is no sweep tool: every step is one call to a tool dw already has.

1. One workspace per experiment. create_workspace a workspace for it, then use_workspace. Put the question and the factor list in its workspace note, so the experiment explains itself to the next session: set_note("workspace:<name>", "Q: does steps change the face? factors: steps 4/8/12").

2. A base workflow with every factor as a variable. If a catalog template already exposes the factor as a variable (get_workflow(name, variables_only=true)), run the template. Otherwise get_workflow it, add a variable for each factor, put variable:<name> where the value was, and save_workflow the copy into the experiment's workspace. text-to-image fixes num_inference_steps at 25, so a steps sweep saves a copy with "steps": 25 under variables and "num_inference_steps": "variable:steps" in the step. A factor that is a dtype or a quantization name keeps its braces in the default, "{nf4}", so it reaches the pipeline as a string (Types and escaping). Keep the template's cost block in the copy, or plan.estimate has no basis to quote from.

3. Pin the seed, change one factor per variant. Every variant passes the same seed in arguments, and differs from the base in one factor only. A factor can change the cost, so validate_workflow each variant with its arguments, quote each one's plan.estimate, and get one go-ahead for the whole list.

4. One run_workflow per variant, with a note. The note's first line is the overrides, steps=8 or steps=20 attention=sage, so a listing that clips notes still shows which variant is which. Call wait_for_job until the variant finishes before submitting the next. The server holds a second large variant until the host can hold it beside the first (see SERVER.md), so waiting is for ordering, not for memory.

5. Only the latest run of a step is cached. The step cache holds one entry per workflow step: its most recent run. A variant whose step and seed match that run, such as the same variant submitted twice in a row, is served from the cache: its manifest marks the step "reused": true and lists that run's files (Runs). Going back to an earlier variant after another one has run renders it again. Each card's worker keeps its own cache, and a server restart empties them. Either way a re-render is expected, not a failed variant.

6. The results table. list_jobs(workspace=<name>) gives each variant's job id, status and note. get_job on each gives its arguments, step timing (Step timing) and files.

7. Assess each output with set_note. Put the note on the output file (its gallery name, as list_gallery gives it). The first line is the score and who judged it, then one key: value line per facet:

   score 4/5 · judged_by claude-opus-5-5
   faces: sharp, eyes aligned
   staging: matches the brief
   defects: none
   

   get_gallery_metadata returns the whole note. list_gallery and list_jobs clip a note to its first 200 characters, so keep the first line short: it is what a listing shows.

8. Keep the winner. keep_output the winning file under a stable asset: name, and put the conclusion (the answer, and the variant that gave it) in the workspace note.