# Kaitoi projects, graphs and custom nodes

> Build Kaitoi workflows from Code, inspect real node schemas, distinguish inline runs from saved projects, and validate custom nodes before installation.

Source: https://kaitoi.io/docs/cli/kaitoi-workflows/
Section: Kaitoi CLI / Working with Kaitoi Code
Written for: Code users building or running Kaitoi workflows.
Prerequisites: A Kaitoi CLI login with access to the requested operations; A trusted workspace for local files and custom-node source
Last reviewed: 2026-10-24

---

Code can discover Kaitoi nodes, work with project documents, run workflows, and
develop custom node packages through the account's available tools. These are
scoped API operations. They do not automatically attach the CLI to a live
Studio canvas. This guide covers CLI **0.9.0**.

## Start from the actual catalog

Describe the desired inputs, processing, outputs, and constraints. Ask Code to
discover suitable node types and inspect their schemas before constructing the
graph. Pin names, data types, required fields, and provider availability come
from the current catalog; a remembered node name is not enough.

> Find available nodes for this workflow, inspect their inputs and outputs,
> and prepare a graph. Explain any unavailable dependency and the run's cost
> before asking to execute it.

Code can discover and describe supported public API operations when it needs a
less common capability. That tool surface does not grant arbitrary unrestricted
HTTP access. Account capabilities, scopes, ownership, and permissions still
apply.

## Decide whether the graph should become a project

An inline graph run can execute a one-off graph without saving a project. Use
that for a disposable experiment when a durable project is unnecessary. For
reusable work, ask Code to create or update a named project and preserve its ID.
State explicitly whether it should run now or only save the graph for review.


A graph document describes connected processing stages. Running it creates a
run with its own identity and status. A successful result can then take two
separate paths: apply outputs to a saved project, or download a file into the
local workspace. An inline run does not create a project automatically. A run
being accepted does not mean it completed, and neither result path implies the
other succeeded.

The authored book image passes through a grayscale operation into the same grayscale result. Its successful run receipt branches to project application and a local file. Toggling local download leaves the remote result unchanged.

*Figure: A graph, a completed run, persisted results, and a local file are separate deliverables.*

## Run, wait, and inspect

Review the graph and any available estimate, then approve the requested run
under its permission rules. Keep the returned run ID. **Accepted**, **queued**,
or **running** describes progress, not success; Code should wait for a terminal
result and inspect node errors and output identifiers.

For a saved project, applying successful run outputs is a separate persistence
operation. Ask Code to apply the run's outputs to the project when that is the
intended result, rather than patching displayed output values into the graph
document. Downloading a file into your workspace is another separate action.

Finish with evidence: project ID, run status, any failed nodes, persisted-output
status, and local paths actually saved. A signed URL or a running job is not a
completed local deliverable.

## Open the project in Studio

Inside Code:

```text
/studio
/studio <project-id>
```

The first form opens the latest project created or changed in this conversation.
The second opens the supplied project ID. This opens a project link; it does not
open a local folder or synchronize every action with an existing browser canvas.

## Create and install a custom node

Ask Code to inspect the current node policy and author source in the workspace.
Have it validate the file or package before installation, resolve the validation
errors, and show what the node accepts and returns. Source editing, validation,
remote installation, and a paid run are distinct steps.

The custom-node tools depend on login, account eligibility, and matching backend
features. Installation validates the package's Python files and requests the
appropriate permission. It does not prove that every external service call
will work. Once installed, inspect the node's catalog schema and test it with
a small, explicitly approved input before using it in a larger workflow.