
Making an app
Ask the agent: “make an app for sketching voxel furniture”, “build a terrain designer I can sculpt and send to the scene”. It writes the app into an HTML Code node, splitting larger apps into several files, and checks how the app looks before handing it back. To see an app at full size, select its node and choose Asset in the switch at the top of the editor.
Shared state
Shared state is where an app keeps its document: the strokes of a painting, the voxels of a model, the parameters of a building. It is stored with the workflow, not in your browser, so:- Everyone sees the same app. Open the workflow in two tabs, or alongside a teammate, and changes show up in both straight away.
- The agent can read it. Ask “how many voxels are there?” or “what pitch is the roof?” and the agent reads the answer from the app’s state.
- It’s saved with the workflow. State is backed up with the canvas, restored with earlier versions, and kept when you copy the workflow. Copying and pasting an app node copies its state too.
Commands
Commands are the actions an app offers:add_voxels, paint_stroke, set_params, add_to_scene. The app’s own buttons call them, and the agent calls the same commands with the same arguments, so whatever you can do by clicking, the agent can do by asking.
To drive an app, ask the agent in plain terms: “add a table top two voxels thick”, “paint a sunset over the hills”, “make the barn 24 m long with a zinc roof”. The agent reads the app’s commands and current state, runs the commands that fit, and looks at the result. Its changes appear live in the app.
Commands run on Runchat’s servers, not in your browser, so an agent can use an app even when nobody has it open. Each command costs 1 credit.
Commands need the workflow to be saved. Only the workflow’s owner and their
teammates can run commands that change an app; anyone who can view the
workflow can read it.
Apps and the scene
Apps can build in the workflow’s Scene. A command can add simple shapes, or generate a full mesh with materials and textures, which Runchat saves as a model file and places in the scene. Each app keeps its objects in its own group, and can read everything else in the scene, so a planting app can scatter trees on the terrain another app made. A good pattern for these apps is the design tool: the app works on one design at a time in its own preview, and only places it in the scene when you choose Add to scene (or Publish to scene). Placed designs can then be moved, replaced or removed later.
Building apps yourself
You can write apps by hand, or with a coding agent such as Claude Code, using the Runchat CLI:init scaffolds an app with an index.html, a src folder for the interface and a commands.js. deploy uploads the folder to the canvas as an HTML Code node; pass --node_id to update an app you deployed before. Apps are bundled with esbuild, so you can split code into ES modules and add npm packages in a package.json.
State in the browser
The app’s page talks to Runchat through thewindow.runchat object, which is already there when the page loads:
apply accepts.
Writing commands
Commands live incommands.js (or commands.ts). Each one has a description and a JSON schema for its input, written for an agent that has never seen the app, and a run function that takes the arguments and the current state and returns the changes to make:
commands.js
result goes back to whoever ran the command. Commands run in a sandbox without a page, so keep them to plain calculation: no DOM, no three.js scene. Put shared maths in your own modules and import it from both the commands and the interface, so the preview and the commands always agree.
Two commands are worth adding to every app: a read-only describe that summarises the state, and an export that returns the app’s geometry or data in plain units, so agents can move work between apps.
To build in the scene, a command can also return scene (edits in the same form as the edit_scene tool) and meshes (vertex data that Runchat turns into a model file). The html-code skill has the full reference: run runchat use_skill --name html-code.
Driving an app from the CLI
The same commands are available to external agents through the CLI and the MCP server:
Every tool takes
node_id for an app on a canvas, or artifact_id (with an optional scope) for a published app or a Rhino tool.
Working alongside other writers
Each app’s state has a revision number that goes up by one with every change, so an agent that works on an app for a long time can stay in step with people and other agents:read_appreturns the currentrev. A laterread_appwithsince_revreturns only the keys changed or removed since then.- A command reads the state and writes its changes in one step. If someone else changed the app in between, the command is run again on the new state, so two callers never overwrite each other with results worked out from the same old state.
edit_app_statetakes an optionalif_rev: the write only happens if the app is still at that revision.app_commandandedit_app_statetake an optionalrequest_id. Repeating a call with the same id never applies it twice, so a call that timed out is safe to retry.
Limits
- Each state key holds up to 256 KB. Split large documents across several keys.
- Up to 1,000 keys and 32 MB per app, and up to 200 changes in one step.
- On a published app, each signed-in person has their own state, and shared state can only be written by the app’s owner. The Scene is only available to apps on a canvas.