Runchat Docs

When the Runchat panel is open in a desktop app, that app is connected to your account through a bridge. Agents, scripts and workflows can then read the open document, run code in it and capture its viewport. There are three ways to use a bridge:

Canvas API and MCP. The tools on this page go through the Canvas API endpoint and the Runchat MCP server, like any other canvas tool.
Code nodes. A Code node with a CAD language runs its script in the connected app each time the workflow runs.
Rhino app tools. HTML apps installed in Rhino reach it through runchat.rhino.

POST https://runchat.com/api/v1/{runchat_id}/canvas
Authorization: Bearer {api_key}

{
  "tool": "run_rhino_command",
  "args": { "command": "_-Circle 0,0,0 5 _Enter" }
}

Over REST, the runchat_id comes from the URL path. Over MCP, pass it as an argument to every tool except install_cad_tool and uninstall_cad_tool.

Requirements

The app is open with the Runchat panel signed in to the same account as the API key or MCP connection. See the setup guides for Rhino, Grasshopper, Blender, Revit, ArchiCAD and SketchUp.
Tools that change the document need the panel’s run permission. Read-only tools do not.
Tools that change the document can only be used on runchats you own or share a team with.

Sessions

If you have several windows of the same app open, each is a separate session. Tools use the most recently connected one unless you pass session. When more than one is open, the tool result lists the session ids.

Supported apps

App	Tools	Code node languages
Rhino	`run_rhino_command`, `get_rhino_context`, `take_screenshot`	`rhino-python`, `rhino-csharp`
Grasshopper	`grasshopper_*`
Blender	`run_blender_command`, `take_screenshot`	`blender-python`
Revit	`take_screenshot`	`revit-csharp`
ArchiCAD	`take_screenshot`	`archicad-python`
SketchUp	`take_screenshot`

Rhino

`get_rhino_context`

A read-only snapshot of the open Rhino document. Use it before writing a script that needs to know what is in the model.

Parameter	Type	Required	Description
`session`	`string`	no	Session id to target

Returns units and tolerance, object counts by type and busiest layer, layers and the current layer, the selection (id, name, layer, type, bounding box), the active view’s camera and display mode, view and layout names, the block count, and toolbar_tools: the user’s installed CAD tools.

`run_rhino_command`

Runs a Rhino command, or a one-off Python or C# script, in the connected Rhino.

Parameter	Type	Required	Description
`command`	`string`	yes	A command in scripted syntax (`_-Circle 0,0,0 5 _Enter`), or the script source
`language`	`"command"` \| `"python"` \| `"csharp"`	no	What `command` holds. Default `"command"`
`session`	`string`	no	Session id to target
`reason`	`string`	no	A short note for the log

Returns success, message and any new console output.

Commands use the non-interactive _- form with _Enter. Avoid commands that open dialogs or ask the user to pick.
Python runs in Rhino 8’s CPython 3 with rhinoscriptsyntax and RhinoCommon. print() output is returned.
C# runs with System, System.Linq, System.Collections.Generic, Rhino and Rhino.Geometry imported. Console output and a runchat_result variable are returned. Needs plugin 0.3.77 or later on Rhino 8.

Grasshopper

The Grasshopper tools read and edit the definition open in Grasshopper. Grasshopper opens automatically if it isn’t already. Components are identified by their instanceGuid, which grasshopper_read_canvas and the create tools return.

Tool	What it does	Main parameters
`grasshopper_read_canvas`	Every component with its position and parameters, the wires and any labelled groups
`grasshopper_read_selection`	The components the user has selected
`grasshopper_search_components`	Searches the installed component library and returns component GUIDs	`query` or `queries[]`, `category`, `limit`, `offset`
`grasshopper_read_component_values`	The current input and output values of components	`instanceGuids[]`
`grasshopper_create_components`	Adds components, including sliders, panels and toggles	`components[]`: `id`, `guid` or `name`, `x`, `y`, `min`, `max`, `value`
`grasshopper_create_python_script_components`	Adds Python 3 script components, or updates one in place	`components[]`: `id`, `x`, `y`, `code`, `inputs[]`, `outputs[]`
`grasshopper_connect_components`	Adds wires	`connections[]`: `{ from: { component, param }, to: { component, param } }`
`grasshopper_configure_components`	Sets flatten/graft, simplify and reverse per parameter, preview, enabled, or bakes to Rhino	`components[]`: `instanceGuid`, `inputs[]`, `outputs[]`, `preview`, `enabled`, `bake`
`grasshopper_group_components`	Wraps components in a labelled group	`instanceGuids[]`, `label`
`grasshopper_layout_canvas`	Arranges components left to right by data flow	optional `instanceGuids[]`
`grasshopper_disconnect_components`	Removes wires	`connections[]`
`grasshopper_delete_components`	Deletes components and their wires	`instanceGuids[]`

All of them also take an optional session.

Creating and wiring components

Give each new component an id: a temporary reference that identifies it in the result, where you get the instanceGuid to wire it with grasshopper_connect_components.

{
  "tool": "grasshopper_create_components",
  "args": {
    "components": [
      { "id": "r", "name": "Number Slider", "x": 0, "y": 0, "min": 1, "max": 20, "value": 5 },
      { "id": "c", "name": "Circle", "x": 250, "y": 0 }
    ]
  }
}

Script components

For grasshopper_create_python_script_components, each input takes a name, an access of "item", "list" or "tree", an optional typeHint ("int", "float", "str", "bool") and optional. Outputs take a name and access. To update a script component, pass its instanceGuid as id: the fields you give replace the existing ones, and inputs and outputs replace the whole list. Run runchat use_skill --name grasshopper-canvas for the full reference agents use.

Blender

`run_blender_command`

Runs Python in the connected Blender, with bpy available.

Parameter	Type	Required	Description
`code`	`string`	yes	The Python source. `print()` output is returned
`reason`	`string`	no	A short note for the log

Returns success, message and the console output. Avoid code that blocks Blender’s main thread for a long time, such as renders or heavy loops.

Revit and ArchiCAD

Revit and ArchiCAD are scripted through Code nodes rather than a dedicated tool. Create a Code node with language set to revit-csharp or archicad-python (see create_code_node) and run it with run_nodes. The script runs in the connected app.

Screenshots

`take_screenshot`

Captures the viewport of a connected app. Over MCP the image is attached to the agent’s next turn so it can see the result.

Parameter	Type	Required	Description
`host`	`"rhino"` \| `"revit"` \| `"blender"` \| `"archicad"` \| `"sketchup"`	no	Which app to capture. Default: the most recently connected
`session`	`string`	no	Session id to target
`compare_to`	`string`	no	An image URL to attach beside the capture, such as a reference you are modelling from
`view`	`string`	no	Rhino: viewport, layout or named view. Default: the active view
`display_mode`	`string`	no	Rhino: `"Shaded"`, `"Rendered"`, `"Arctic"`, `"Technical"`, `"Wireframe"`, …
`camera_location`	`number[3]`	no	Rhino: camera position
`camera_target`	`number[3]`	no	Rhino: the point the camera looks at
`frame`	`string`	no	Rhino: zoom to `"all"`, `"selection"` or comma-separated object ids
`width`, `height`	`number`	no	Rhino: image size, 64 to 2048 pixels

In Rhino the settings apply to this capture only and the user’s view is restored afterwards. Set host after scripting a specific app, so the capture comes from that app rather than whichever connected last.

CAD tools

CAD tools are Rhino toolbar buttons published as artifacts. See Rhino tools.

Tool	What it does	Parameters
`install_cad_tool`	Adds a CAD tool to the user’s Rhino toolbar. It appears within a few seconds while the Runchat panel is open	`artifact_id`
`uninstall_cad_tool`	Removes it from the toolbar. The artifact is not deleted	`artifact_id`

Tools you create are installed for you already; use install_cad_tool for a teammate’s or a public one.

API Documentation

Endpoints

Canvas API

Bridges

CAD bridges

Requirements

Sessions

Supported apps

Rhino

`get_rhino_context`

`run_rhino_command`

Grasshopper

Creating and wiring components

Script components

Blender

`run_blender_command`

Revit and ArchiCAD

Screenshots

`take_screenshot`

CAD tools

​Requirements

​Sessions

​Supported apps

​Rhino

​get_rhino_context

​run_rhino_command

​Grasshopper

​Creating and wiring components

​Script components

​Blender

​run_blender_command

​Revit and ArchiCAD

​Screenshots

​take_screenshot

​CAD tools

Requirements

Sessions

Supported apps

Rhino

`get_rhino_context`

`run_rhino_command`

Grasshopper

Creating and wiring components

Script components

Blender

`run_blender_command`

Revit and ArchiCAD

Screenshots

`take_screenshot`

CAD tools