> ## Documentation Index
> Fetch the complete documentation index at: https://docs.patch.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloud Blender

> Live Blender sessions and GPU renders on Patch's machines, driven by your coding agent through pch or Patch's MCP server.

Cloud Blender runs Blender on Patch's machines. Your coding agent starts a session, a live Blender 5.2 with no window, and drives it with `bpy` scripts. It can look at the scene as a picture, checkpoint and fork it, and render it on GPUs. You pay in credits, by the second, only while something runs.

Your agent does the work, through [`pch`](https://docs.patch.gg/cli) or Patch's [MCP server](https://docs.patch.gg/mcp-server.md). The app's `blender` area is where you watch it and step in: what's running, what it costs, pausing, stopping, going back to a checkpoint and downloading.

Anyone signed in to Patch can use it. Your own org comes with 500 starter credits. 1 credit is \$0.01.

## Connect your agent

The quickest way is to give your agent this prompt. If it doesn't have `pch` or Patch's tools yet, it sets them up first, and you sign in through a link it gives you.

```text theme={null}
Use cloud Blender on Patch (https://patch.gg/blender) to make something for me: start a session with `pch blender session start`, or the start_blender_session tool of Patch's MCP server, give it a short name, build the scene with bpy, and take a look as you go, so I can watch it on Patch. If you don't have pch or Patch's tools yet, read https://patch.gg/llms.txt and follow its setup steps first. Then ask me what I'd like to make before you start.
```

The same prompt is on the empty `blender` page in Patch, with a `copy prompt` button.

To set it up yourself instead, each way below gives your agent the same tools. Any agent works: Claude Code, Codex, Cursor, their desktop apps, or the agent in a Patch Desktop chat, which is already connected as you.

### With pch

Install [`pch`](https://docs.patch.gg/cli) and sign in:

```bash theme={null}
curl -fsSL https://patch.gg/install.sh | sh     # macOS, Linux and WSL
irm https://patch.gg/install.ps1 | iex          # Windows PowerShell
pch login
```

The installer adds Patch's MCP server to the coding agents on your PC (`pch agent install` does it again for one you add later). `pch login` makes a key that can spend credits (the `compute` scope), as well as read and publish. The commands are under `pch blender` and `pch jobs`. If `pch blender` isn't there, run `pch update`.

A key made before cloud Blender opened can only read: it can't start, change, stop or download anything, and those calls answer `missing_scope`. Sign in again with `pch login --scope read --scope publish --scope compute`, then restart your agent.

### With the MCP server

Apps that add an MCP server by address connect with your Patch account: add `https://patch.gg/api/mcp`, sign in to Patch when it asks, and press **Connect**. The sign-in screen says `use tools with your credits`, which means the app can spend credits.

To connect with an API key instead, make one with `compute` and give it to your agent as the [MCP server](https://docs.patch.gg/mcp-server.md#with-an-api-key) page shows:

```bash theme={null}
pch token create --name my-agent --scope read --scope publish --scope compute
```

Tell your agent to read the `guide` tool's Cloud Blender section first. It covers how to use the tools well and what they cost.

## A first session

The prompt above has your agent ask you what to make. To say it yourself, give your agent a prompt like this:

```text theme={null}
Use Patch's cloud Blender. Start a small session named "first scene", build a low-poly
lantern on a table with a warm light, and look at it after each change. Save it, render
frame 1 on a GPU with a max cost of 20 credits, download the frame, then stop the session
and tell me what it all cost.
```

What you'll see in Patch:

* **`blender`** is in the sidebar, under `analytics`, for everyone, signed in or not. While anything runs, it shows how many.
* **The area** at [patch.gg/blender](https://patch.gg/blender) lists your sessions and jobs, with the tabs `all`, `live`, `paused` and `stopped`. Each row has the scene's latest look, its state, its machine, who started it (your agent and its key) and when it was last active. Renders show under the session they came from.
* **A session's page** has its latest look, its checkpoints in a row with `restore` and `fork`, Blender's logs and the files in `/work`, plus what it's cost so far and what an hour of it costs. `pause`, `checkpoint`, `fork` and `stop` are at the top while it runs, and `resume` when it's paused.

## What an agent can do

Each step lists the `pch` command and the MCP tool. Run `pch <command> --help` for every flag.

| To | pch | MCP tool |
| - | - | - |
| Start a session, optionally sending a folder to `/work` and opening its .blend | `pch blender session start [folder]` | `start_blender_session`, then `upload_blender_files` and `open_blender_file` |
| Send files to `/work`, or list what's there | `pch blender files upload <session> <files>`, `files ls <session>` | `upload_blender_files`, `list_blender_files` |
| Open a .blend from `/work` in place of the scene | `pch blender open <session> <path>` | `open_blender_file` |
| See what's in the scene, as text | `pch blender inspect <session>` | `inspect_blender_scene` |
| Look at the scene as a picture | `pch blender look <session> -o look.png` | `look_at_blender_scene` |
| Run a `bpy` script | `pch blender run <session> script.py`, or `-c "<code>"` | `run_blender_code` |
| Run a shell command in `/work` | `pch blender exec <session> "<command>"` | `exec_in_blender_session` |
| Follow or stop a long run | `pch blender runs view`, `runs cancel`, `runs list` | `blender_run_status`, `cancel_blender_run`, `list_blender_runs` |
| Read Blender's log | `pch blender logs <session>` | `blender_session_logs` |
| Search Blender's Python API reference | `pch blender docs "<query>"` | `search_blender_docs` |
| Save the scene to a file | `pch blender save <session> <path>` | `save_blender_scene` |
| Keep a checkpoint, or go back to one | `pch blender session checkpoint`, `checkpoints`, `restore <session> v3` | `checkpoint_blender_session`, `list_blender_checkpoints`, `restore_blender_session` |
| Fork it into several sessions to try things side by side | `pch blender session fork <session> --count 3` | `fork_blender_session` |
| Pause and resume | `pch blender session pause`, `resume` | `pause_blender_session`, `resume_blender_session` |
| Keep it from pausing itself, up to a day | `pch blender session hold <session> <minutes>` | `hold_blender_session` |
| Render on a GPU | `pch blender render <blend> --frames 1-240 --max-cost <credits>` | `start_blender_render` |
| Follow a render | `pch jobs status`, `wait`, `logs`, `list` | `job_status`, `job_logs`, `list_jobs` |
| Fetch files | `pch blender files download <session> <paths> -o <folder>`, `pch jobs outputs <job> -o <folder>` | `download_blender_files`, `job_outputs` |
| Stop a session for good, or cancel a render | `pch blender session stop`, `pch jobs cancel` | `stop_blender_session`, `cancel_job` |
| See your sessions | `pch blender session list`, `view` | `list_blender_sessions`, `get_blender_session` |
| Rename a session or a render | `pch blender session rename <session> <name>`, `pch jobs rename <job> <name>` | `rename_blender_session`, `rename_job` |
| See prices and credits | `pch blender prices`, `pch credits` | `credit_balance` |

Some things to know about these:

* **Sizes.** A session is `small` (2 cores, 4 GB) unless you ask for `--size medium` (4 cores, 16 GB) or `--size large` (8 cores, 32 GB). `--gpu l40s` adds a GPU. A fork is the size of its parent unless you say otherwise, so you can try something on a small session and fork it onto a GPU.
* **One GPU: an L40S.** A session, a render or a batch script with a GPU has an `l40s`, which starts in seconds. Patch doesn't offer an L4 any more, since one took up to 10 minutes to start: asking for one is refused (`gpu_not_offered`), and so is forking a session that has one unless you say what the forks get, `--gpu l40s` or `--input '{"gpu":null}'` for none. Anything that already has an L4 keeps it until it's done.
* **Renders read saved files.** A render reads a .blend from your org's files, never a session's unsaved scene. So save the scene, then download it: each file a download fetches is also copied to your org's files as `sessions/<session>/<path>`, which is the path to render. Render one frame at low samples first and look at it before paying for the range.
* **A render's cost is known before it runs.** It renders the first frame to estimate the rest, and stops rather than pass `--max-cost`. Waiting running out never cancels a render, so don't start it again: follow it with `pch jobs status`.
* **A long run keeps going.** A run or a command can take up to an hour (`--timeout-s`). If the wait runs out first, pch exits 7 with the run's id. That isn't an error. Read how it ended with `pch blender runs view` rather than running it again.

### One script over many files

To run one `bpy` script over many files or sets of parameters, up to 1,000 items, use the API: `POST https://patch.gg/api/v1/blender/scripts`, with a key that has `compute`. There's no `pch` command or MCP tool for it yet. Each item runs in a fresh scene and gets `args` with its `params`, its `file` and `out`, a folder whose contents land in `jobs/job_…/<index>/` in your org's files. An item that fails doesn't stop the others. Items are charged at a session's price for their size and GPU, and `max_cost` is never passed. Follow the job as you would a render, with `pch jobs status` or `job_status`.

## Credits

Everything is charged by the second, while it runs, at these prices in credits an hour:

| What | Credits an hour |
| - | - |
| A session: small, medium, large | 50, 100, 200 |
| An L40S on a session | +200 |
| Rendering on an L40S | 250 |
| Making a video from a render's frames | 50 |
| An item of a batch script | A session's price for its size and GPU |

* **Prices can change.** `pch blender prices` gives today's, and a running session's own price is in its view (`cost.per_hour`).
* **Paused costs nothing.** A session is charged only while it runs.
* **Starting needs credits in hand:** 10 minutes of what everything you're starting and running costs, together. A render first holds its estimate, plus a fifth.
* **Starter credits.** Your own org gets 500, once: they're there the first time you or your agent looks at its credits or starts something. A team org doesn't get any, because its people's own orgs did.
* **More credits.** Buy more at [patch.gg/credits](https://patch.gg/credits), for your own org only, signed in to Patch on the site or in Patch Desktop: packs from 500 credits ($5) to 10,000 ($100), at \$0.01 a credit, paid through Stripe. A key or an agent can't buy them.
* **Whole credits.** Your balance moves a whole credit at a time, and what a session or job cost is rounded to the nearest credit when it ends.
* **Where to see it.** Your credits are at the top of your account menu, and `usage →` opens [patch.gg/usage](https://patch.gg/usage), which shows what they went on over the last 7, 30 or 90 days. `pch credits` shows the balance and every recent change. Each session and job shows what it's cost (`cost.spent`), and your agent should tell you when it's done.

## Limits

Each org can have **16 sessions running at once, 1 of them with a GPU**. Paused and stopped sessions don't count, and one you pause or stop frees its place straight away.

Past that, a start, resume, restore or fork starts nothing and answers `session_limit_reached`, saying how many are running and how many more would fit. For example: "`<org>` has 1 session with a GPU running, and can have 1 at once for now. Nothing was started: stop or pause one, or use one without a GPU, then try again. To run more at once, ask Patch." Any call to a paused session in a full org gets the same answer, since it would resume it. A fork that wouldn't all fit starts none.

An org's files hold 50 GiB: uploads, sessions' copies and render outputs together. Past that, uploads and new renders answer `storage_limit_reached`. Nothing deletes files yet, so to go past either limit, ask Patch in [Discord](https://discord.gg/W2VyyKxJy).

## Good to know

* **Sessions pause themselves.** After 5 minutes without a call, a session pauses and costs nothing. The next call that uses it (a run, a look, an inspect, an open, a save or a file transfer) resumes it in seconds. Reading a session, its logs or its checkpoints never resumes it. `--idle-pause-minutes` sets a longer wait, up to a day, and `hold` keeps it up while work goes on without calls.
* **What's kept.** A paused session keeps its files in `/work` and its saved scene for 30 days, and Python's variables for 7 days (not on a GPU session). A resume says `namespace: kept` or `fresh`. Checkpoints are kept for 30 days. One is made when you ask, as a session pauses, and after every 10 minutes of use, keeping the newest 3 automatic ones.
* **Stopping is for good.** A stopped session's `/work` goes with it, so save and download what you want first. Its checkpoints can still be forked for 30 days. Files copied to your org's files stay after it stops.
* **When credits run out**, running sessions pause and renders stop. What a render had finished is kept. New starts are refused (`insufficient_credits`) until there are enough credits for 10 minutes.
* **A crash loses little.** If a session's machine stops unexpectedly, the session is left paused at its newest checkpoint, so at most about 10 minutes of work is lost. The next call resumes it and says what was lost.
* **There's no window.** Screenshots and most viewport operators don't work. Your agent looks at the scene with `look` and works through `bpy.data`.
* **Files a session hands back are its own.** A download leaves out hidden files, agent instruction files and git's own files unless you name them by exact path. Treat what it fetches like any other download.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.