Workbooks
A workbook is a shared project with files, executable code, and saved outputs. People and connected agents work with the same material, and it stays available whether or not compute is running.
What a workbook holds#
| Content | Details |
|---|---|
| Files | Markdown or MDX documents, source code, inputs, media, and outputs, browsable in Files. |
| Code cells | Editable cells that you, or an agent you connected, can change and rerun. |
| Execution history | One record each time code runs: submitted inputs, the code and declared source files it used, its environment, logs, status, and separate outputs. |
| Retained results | Outputs kept with an execution so they remain inspectable after compute stops. |
| Compute | An optional CPU or GPU runtime that you start and stop explicitly. |
A workbook is created explicitly and stays independent of any captured session. Recipes create a workbook with a tested starting structure; a blank workbook starts lightweight and holds whatever you add.
Documents are files#
Use Markdown or MDX files for plans, explanations, decisions, and handoffs. Create them from Files, edit them in the browser, or ask a connected agent to read or update the same path through MCP. A document is ordinary workbook material rather than a separate note or brief type.
When code executes#
Each time code executes, Consoles keeps a separate history entry rather than overwriting the previous one. It records the submitted inputs, code and declared source files, environment, logs, status, and outputs. You can open an earlier execution to see what produced a result and download the files it saved.
Outputs only persist if they were saved into the workbook or declared as artifacts. See Files & compute for limits and retention behavior.
How compute relates#
Compute is a capability a workbook can use, not the workbook itself. Creating a workbook or a recipe does not start paid compute; you start a CPU or GPU runtime explicitly, and starting one may incur charges.
Stopping a runtime releases its processes and memory, including GPU memory. The workbook's files, code, execution history, and retained results stay available, and you can inspect or download them without starting compute again. A runtime badge such as CPU or Linux summarizes the selected capability rather than naming a vendor, distribution, or package set. Files & compute has the full lifecycle and storage detail.
How agents relate#
An agent works in a workbook through MCP, with access scoped to what you approve: read for inspection, write for files and cells, execute for runs and starting or stopping compute. Choosing All workbooks instead of This workbook can also include managing workbooks across your account.
The Connect agent panel lists the agents connected to the workbook and lets you disconnect them. Granting MCP access does not capture that agent's local session, and it does not start compute on its own. See Connect an agent.
How sessions relate#
Captured sessions are separate objects in Sessions. Creating a workbook does not start capture, and capture does not create a workbook.
When both describe the same work, you can link them. The link is a reference only: it does not copy content in either direction, does not merge ownership or permissions, does not grant access to either object, and does not start compute. Removing a link preserves both the workbook and the session. See Sessions.
Related#
- Quickstart creates a workbook and keeps a first result.
- Files & compute covers persistence, limits, and runtime lifecycle.
- Sessions explains captured evidence and links.