Skip to main content
The dotbot studio is a visual editor for workflows. Instead of editing workflow.json by hand, you lay out a workflow as a graph: each task is a node, and dependencies are the edges between them. The studio reads and writes the same workflow.json that the runtime uses, so anything you design in the editor runs exactly as a hand-written workflow would.

​
What the studio is for

A workflow is a pipeline of tasks with dependencies, prompt files, and commit settings. Expressed as JSON, the relationships between tasks are hard to see at a glance. The studio renders the pipeline as a directed graph so you can see the dependency structure, add and connect tasks, and edit the prompt files attached to each task without leaving the page. It is a complement to the main dashboard, not a replacement: you design a workflow in the studio, then run and monitor it from the dashboard. The studio is a React and Vite single-page app that uses React Flow for the graph and a small PowerShell HTTP server for file access. It edits files only. All JSON parsing and validation happens in the browser, and the server reads and writes the workflow directory on disk.

​
Launching the studio

Run the studio from the CLI: 
dotbot studio
This starts the studio server and opens your browser. If a studio is already running, the command detects it from the recorded port file and opens the existing instance rather than starting a second one.
If the studio is not installed, dotbot studio reports that it is missing. Run dotbot update to install it.

​
Ports

The studio server picks a port at startup. It starts from the base port 9001 and searches upward until it finds a free one, trying the range 9001 to 9020. The chosen port is written to a .studio-port file in your dotbot home directory so the CLI can find a running studio and attach to it. If every port in the range is in use, the server reports the range it tried and suggests starting on a different base port.

​
Running the studio in development

For local development of the studio itself, use go.ps1 in the src/studio-ui directory. It installs npm dependencies on first run, then either builds and serves the production bundle or runs both servers with hot reload. 
pwsh go.ps1          # production or preview mode
pwsh go.ps1 -Dev     # development mode with hot reload
pwsh go.ps1 -Port 9100   # custom API port
In development mode (-Dev, equivalent to npm run dev), the Vite dev server runs on port 5173 and the PowerShell API backend runs on the API port, with both started concurrently. Vite proxies API calls through to the backend, so you work against http://localhost:5173 while the file operations run on the API server.
ServerDefault portRole
API backend9001 (searches 9001 to 9020)Reads and writes workflow files on disk
Vite dev server5173Serves the client with hot reload in development mode

​
How it relates to the dashboard

The studio and the main dashboard work on the same project but solve different problems:
  • dotbot studio opens the visual editor for designing and editing workflow.json, the graph layout, and the prompt files.
  • dotbot go launches the project runtime and the dashboard, where you start runs and watch tasks progress.
Both read the same workflow directory, so a workflow you design in the studio is immediately runnable from the dashboard, and changes the dashboard makes to a workflow are reflected the next time you open the studio.

​
What the studio reads and writes

The studio exposes its file operations under the /api/studio namespace. At a high level, the editor can:
  • List all installed workflows, including read-only workflows that come from enterprise registries.
  • Create a new workflow, or copy an existing one as a starting point.
  • Read a workflow’s workflow.json, its saved graph layout, and its prompt files.
  • Save edits back to workflow.json and persist the node positions to a .studio-layout.json file beside it.
  • List, read, and write the individual files in a workflow directory, such as the prompt templates.
Workflows that come from an enterprise registry are read-only in the studio. To customise one, copy it into your project first, then edit the copy.
The graph layout is stored separately from workflow.json in a .studio-layout.json file, so arranging the nodes in the editor never changes the pipeline definition itself.