Skip to content

Commit 377dfaa

Browse files
georgigeorgi
authored
Merge pull request #5606 from nodetool-ai/docs/readme-creative-onboarding
2 parents 6c2897b + b7606c1 commit 377dfaa

1 file changed

Lines changed: 78 additions & 81 deletions

File tree

‎README.md‎

Lines changed: 78 additions & 81 deletions
Original file line numberDiff line numberDiff line change
@@ -7,26 +7,34 @@
77
[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](LICENSE.txt)
88
[![Powered by Atlas Cloud](https://www.atlascloud.ai/oss-program/powered-by-atlas-cloud.svg)](https://www.atlascloud.ai/?ref=PW9AD2)
99

10-
![NodeTool: one sentence becomes a storyboard, rendered stills and clips, a cut on the timeline, and a finished film](marketing/public/hero-project-poster.webp)
11-
1210
**You are the director. The agent is your crew.**
1311

1412
Create and edit AI images, video, audio, and text in NodeTool, an open-source
15-
creative studio. Connect models into repeatable workflows on a visual canvas.
16-
Agents can wire the graph, run it, and repair failures. Your project
17-
file keeps the graph, inputs, assets, and edits together.
13+
creative studio. Let agents build and revise your work, then inspect and edit
14+
it yourself in the workflow canvas, storyboard, or timeline.
1815

1916
**[Download NodeTool Studio](https://github.com/nodetool-ai/nodetool/releases/latest)** ·
2017
**[Quick start](#first-run-in-studio)** ·
2118
**[Documentation](https://docs.nodetool.ai/)** · **[MCP setup](#mcp)** ·
2219
**[Contribute](#contributing)**
2320

21+
![NodeTool: one sentence becomes a storyboard, rendered stills and clips, a cut on the timeline, and a finished film](marketing/public/hero-project-poster.webp)
22+
23+
## Why NodeTool
24+
25+
- Inspect intermediate results, swap a model, and rerun the changed part of a
26+
workflow. Agents can wire the graph, run it, and repair failures within the
27+
limits you set.
28+
- Keep the graph, inputs, assets, and edits together in your project. Export
29+
`.nodetool` bundles to reopen in another NodeTool installation.
30+
- Run repeatable workflows from the studio, CLI, or an external agent through
31+
[MCP](#mcp).
32+
2433
Studio is free and runs on macOS, Windows, and Linux. Cloud model requests go
2534
to the provider you connect, billed to your account at provider rates. Local
2635
models run through supported engines such as Ollama, MLX, and llama.cpp, with
2736
hardware requirements that depend on the model. Offline work requires local
28-
models and assets. Export `.nodetool` bundles to reopen in another NodeTool
29-
installation. [NodeTool Cloud](https://nodetool.ai/cloud) is in alpha and uses
37+
models and assets. [NodeTool Cloud](https://nodetool.ai/cloud) is in alpha and uses
3038
hosted storage and cloud providers rather than your machine's local models.
3139

3240
## First run in Studio
@@ -36,60 +44,32 @@ hosted storage and cloud providers rather than your machine's local models.
3644
[installation guide](docs/installation.md) for requirements and per-OS steps.
3745
2. Open Studio and press **+** on the workspace tab bar, then choose
3846
**New storyboard…**.
39-
3. Choose one of the example storyboards listed as **already rendered**. Open
40-
its shot cards to inspect the existing images and clips without generating
41-
new media or adding a provider key.
42-
43-
To create your own footage, follow the [film quick start](docs/getting-started.md).
44-
It explains connecting providers through **Settings → Models & Providers**,
45-
writing a brief, approving stills before generating clips, and assembling a
46-
cut. Those generation steps use paid provider calls. No GPU is required when
47-
you use cloud models.
48-
49-
## First run from source
50-
51-
This deterministic example uses the repository's
52-
[`hello_input_output_cli.json`](examples/workflows/hello_input_output_cli.json)
53-
template. It does not call a model, so it needs no API key:
47+
3. Choose the **Lighthouse Keeper** opening, listed as **already rendered**.
48+
Open its shot cards to inspect the existing images and clips.
49+
4. Press **Preview**, then play the board to watch its shots in sequence.
50+
Exploring this example does not require a provider key or new generation.
5451

55-
```bash
56-
git clone https://github.com/nodetool-ai/nodetool.git
57-
cd nodetool
58-
nvm use # Requires nvm and Node.js 22.22.1
59-
npm install
60-
npm run build:packages
61-
npm run workflow -- ./examples/workflows/hello_input_output_cli.json \
62-
--input text='hello from NodeTool'
63-
```
52+
Connect providers through **Settings → Models & Providers** when you are ready
53+
to generate new media. Cloud generation uses paid provider calls and needs no
54+
GPU.
6455

65-
The input node named `text` connects to a `Reroute` output node. The command's
66-
JSON summary includes `hello from NodeTool` in its outputs. Change the `text`
67-
input and run it again to see the new value. See
68-
[`examples/workflows/README.md`](examples/workflows/README.md) for more
69-
examples and expected behavior.
56+
## From brief to editable film
7057

71-
To run an agent or a model-backed workflow, configure a provider first. For
72-
example, obtain an OpenAI key, export it in the shell, and use the checked-in
73-
OpenAI example:
58+
Write a brief and ask the agent for a storyboard. Approve the stills before
59+
spending on video generation, then assemble the clips on a timeline. Trim and
60+
reorder the cut, add narration, and export an MP4. Revise an individual shot
61+
without regenerating the rest of the film.
7462

75-
```bash
76-
export OPENAI_API_KEY='your-key'
77-
npm run workflow -- ./examples/workflows/agent_openai_basic_cli.json \
78-
--input prompt='Write one sentence about workflow testing.'
79-
```
63+
![NodeTool storyboard](marketing/public/surface-storyboard-poster.webp)
8064

81-
This makes a paid provider request. The example selects GPT-4o. Access and
82-
billing depend on your provider account. See
83-
[Models and Providers](docs/models-and-providers.md) and
84-
[Provider Guides](https://docs.nodetool.ai/developer/providers/) for other
85-
providers and local setup. Do not add a key to a committed file.
65+
The [film quick start](docs/getting-started.md) walks through each step,
66+
including model setup and export.
8667

8768
## Recipes
8869

8970
These recipes link to downloadable workflows and describe their outputs and
9071
limitations. Whether the result is an editable timeline or an exported video
91-
depends on the workflow you choose. Cloud model runs require your provider
92-
keys and are billed by those providers.
72+
depends on the workflow you choose.
9373

9474
| Example | Output | Link |
9575
| --- | --- | --- |
@@ -103,27 +83,20 @@ contact sheet for each run.
10383

10484
## Agents and workflows
10585

106-
Describe a pipeline and an agent can plan steps, select nodes, connect a graph,
107-
run it, and repair failures within the limits you set. Workflows are editable:
108-
inspect every input and intermediate result, substitute a model, and rerun the
109-
changed part. The same canvas supports:
86+
Beyond the film workflow, the studio supports:
11087

11188
- image generation and editing, audio and speech, video, and text
11289
- storyboards, scripts, and multi-track timelines
11390
- JavaScript scripts and mini apps on top of a workflow
11491
- custom TypeScript and Python nodes
11592
- local inference or provider APIs, where the relevant model is available
11693

117-
The film workflow is the showcase: storyboard shots, generate approved clips,
118-
voice a script, and assemble a timeline that remains editable. Read the
119-
[Creative Agent guide](https://docs.nodetool.ai/creative-agent),
94+
Read the [Creative Agent guide](https://docs.nodetool.ai/creative-agent),
12095
[Video Editor guide](https://docs.nodetool.ai/video-editor), and
12196
[Sketch Editor guide](https://docs.nodetool.ai/sketch-editor).
12297

12398
![NodeTool workflow canvas](marketing/public/screen_workflow.webp)
12499

125-
![NodeTool storyboard](marketing/public/surface-storyboard-poster.webp)
126-
127100
## MCP
128101

129102
The installed CLI registers NodeTool's local toolbelt with Claude Code, Codex,
@@ -146,16 +119,50 @@ The MCP server can drive workflows and creative editing surfaces. See the
146119
[MCP production guide](docs/mcp-production.md) and
147120
[agent architecture](docs/AGENTS.md).
148121

149-
## CLI
122+
## First run from source
123+
124+
This deterministic example uses the repository's
125+
[`hello_input_output_cli.json`](examples/workflows/hello_input_output_cli.json)
126+
template. It does not call a model, so it needs no API key:
127+
128+
```bash
129+
git clone https://github.com/nodetool-ai/nodetool.git
130+
cd nodetool
131+
nvm use # Requires nvm and Node.js 22.22.1
132+
npm install
133+
npm run build:packages
134+
npm run workflow -- ./examples/workflows/hello_input_output_cli.json \
135+
--input text='hello from NodeTool'
136+
```
150137

151-
Install the CLI with `npm install -g @nodetool-ai/cli` using Node.js 22.22.1.
152-
From the repository checkout, run the same no-key example:
138+
The input node named `text` connects to a `Reroute` output node. The command's
139+
JSON summary includes `hello from NodeTool` in its outputs. Change the `text`
140+
input and run it again to see the new value. See
141+
[`examples/workflows/README.md`](examples/workflows/README.md) for more
142+
examples and expected behavior.
143+
144+
To run an agent or a model-backed workflow, configure a provider first. For
145+
example, obtain an OpenAI key, export it in the shell, and use the checked-in
146+
OpenAI example:
153147

154148
```bash
155-
nodetool workflows run ./examples/workflows/hello_input_output_cli.json \
156-
--params '{"text":"hello from NodeTool"}'
149+
export OPENAI_API_KEY='your-key'
150+
npm run workflow -- ./examples/workflows/agent_openai_basic_cli.json \
151+
--input prompt='Write one sentence about workflow testing.'
157152
```
158153

154+
This makes a paid provider request. The example selects GPT-4o. Access and
155+
billing depend on your provider account. See
156+
[Models and Providers](docs/models-and-providers.md) and
157+
[Provider Guides](https://docs.nodetool.ai/developer/providers/) for other
158+
providers and local setup. Do not add a key to a committed file.
159+
160+
## CLI
161+
162+
Install the CLI as shown in [MCP](#mcp), using Node.js 22.22.1. The
163+
[CLI package guide](packages/cli/README.md) covers running workflows with the
164+
installed command.
165+
159166
To serve the API, run `nodetool serve` in a separate terminal. Commands that
160167
support remote execution accept `--api-url` or `NODETOOL_API_URL`.
161168
For interactive agent chat, connect a provider first as described in the
@@ -167,27 +174,17 @@ See the [CLI reference](https://docs.nodetool.ai/cli) and
167174

168175
## Development setup
169176

170-
The source checkout contains the backend packages, web UI, Electron desktop
171-
shell, and mobile app. Use the recommended bootstrap path first:
177+
After the [source quick start](#first-run-from-source), start the API and web
178+
UI from the prepared checkout:
172179

173180
```bash
174-
git clone https://github.com/nodetool-ai/nodetool.git
175-
cd nodetool
176-
nvm use
177-
./start.sh full # installs, builds, then starts API and web UI
181+
npm run dev
178182
```
179183

180-
`./start.sh full` serves the API and web UI. It does not package or launch the
181-
Electron desktop app. To start only the API, use `./start.sh`; to inspect the
184+
For an automatic install, build, and launch from a fresh checkout, use
185+
`./start.sh full`. To start only the API, use `./start.sh`; to inspect the
182186
environment without changing it, use `./start.sh doctor`.
183-
184-
For a manual setup, run these commands from the checkout root:
185-
186-
```bash
187-
npm install
188-
npm run build:packages
189-
npm run dev # API and web development servers
190-
```
187+
These commands do not launch the Electron desktop app.
191188

192189
In a separate terminal, launch the desktop shell with `npm run electron` from
193190
the prepared checkout. Node.js 22.22.1 is pinned in

0 commit comments

Comments
 (0)