---
title: "File Formats"
description: "What .cerevisor, .cerevisor-world, and .opaal files contain, how they load, and when to use each."
slug: reference/file-formats
section: reference
canonical_url: https://cerevisor.com/docs/reference/file-formats
last_verified: 2026-05-18
last_verified_version: "1.2.0"
updated_at: 2026-05-18T15:08:18.053416+00:00
---

Cerevisor uses three file extensions. All three are plain JSON; you can open them in any text editor, diff them in Git, email them to a colleague.

## `.cerevisor`: a single workflow

The default format for a one-workflow file. Created when you click **Save** with one workflow open.

**What's inside:** A JSON-serialized `Workflow` document, agents, columns, connections, settings, viewport state, version field `"1.0"`.

**When it's used:** Most Cerevisor files. If you're working on one workflow at a time, this is what you save.

**Backward compat:** Opens transparently as part of a one-workflow workspace.

## `.cerevisor-world`: a workspace of N workflows

The format for multi-workflow workspaces (World View).

**What's inside:** A JSON-serialized `Workspace` document: a list of `WorkspaceWorkflow` wrappers, each containing a full workflow plus its frame placement on the world canvas, accent color, folder path, and version field `"1.0"`.

**When it's used:** When you've added more than one workflow to a workspace, or when you explicitly start with a `.cerevisor-world` save.

**Auto-wrap:** When you open a single-workflow `.cerevisor` file, Cerevisor wraps it into a one-entry workspace in memory. Saving still writes back to the original `.cerevisor` unless you Save As.

## `.opaal`, legacy single-workflow

The original extension used during the Opaal codename era (pre-rebrand). Identical structure to `.cerevisor`.

**When it's used:** Only for backward compatibility. New saves always write `.cerevisor` unless you explicitly type `.opaal` in Save As.

**Loading:** Transparent. Drag a `.opaal` file onto the Home Screen drop zone, or use Ctrl+O. It loads identically to a `.cerevisor` file.

## What's inside (high level)

If you open any of these in a text editor, you'll see a JSON object with these top-level fields (single-workflow files; workspaces wrap this inside a `workflows[]` array):

```json
{
  "id": "uuid",
  "name": "My Workflow",
  "description": "What this workflow does",
  "version": "1.0",
  "createdAt": "2026-05-17T10:00:00Z",
  "updatedAt": "2026-05-17T11:30:00Z",
  "columns": [ /* phases / waves */ ],
  "agents": [ /* each agent's config */ ],
  "connections": [ /* edges between agents */ ],
  "settings": {
    "preamble": "...",
    "executionMode": "sequential",
    "includePermissions": true,
    "nativeMode": true,
    "permissions": { /* permission flags */ }
  },
  "metadata": {
    "viewport": { "x": 0, "y": 0, "zoom": 1 }
  }
}
```

The `id` is a UUID. The `version` field is the *file-format* version, not the Cerevisor version. Cerevisor handles older file versions transparently, new optional fields use defaults when missing.

## Saving

| Action | Shortcut | Behavior |
|---|---|---|
| **Save** | Ctrl/Cmd+S | If the workflow has a path, overwrite it. Otherwise prompt for a path. |
| **Save As** | Ctrl/Cmd+Shift+S | Always prompt for a new path. |
| **Auto-save (draft)** | (automatic) | Every 30 seconds, the in-memory state is saved to a hidden draft. If Cerevisor crashes or is force-closed, the next launch offers to recover the draft. |

When saving a workspace, the file format defaults to `.cerevisor-world`. If you'd rather keep working with the legacy single-workflow format, use Save As → type `.cerevisor` extension.

## Loading

Three ways:

1. **Drag a file onto the Home Screen drop zone.**
2. **Ctrl/Cmd+O** to open the file picker.
3. **Click a card in the Recent Workflows** section of the Home Screen.

Cerevisor detects the format from the JSON structure, not the filename, renaming a `.opaal` to `.cerevisor` (or vice versa) makes no functional difference.

## Sharing a workflow

You can share `.cerevisor` files freely; they contain no API keys, no model credentials, no personal data. They contain:

- Your agents (names, role descriptions, instructions, output definitions).
- Your connections.
- Your settings (preamble, permissions, native mode flag).
- Layout (viewport, agent positions).

They do **not** contain:

- API keys.
- Filesystem paths to your local files (your `inputFiles[]` reference paths by basename in the workflow file; the recipient will need to wire their own files).
- Memory data.
- Run history.
- Audit logs.

If you reference a markdown file (`inputFiles[]` or `outputFiles[]`), the recipient will see the file reference but the file itself won't be in the bundle. They'll need to provide their own equivalent. For multi-file workflows that should travel together, save into a folder, zip the folder, share the zip.

## Editing by hand

You can. JSON is JSON. But the safer path is the canvas; it has validation and undo. If you do edit by hand:

- Preserve the `version` field.
- Keep `id` fields unique.
- The `columns[].order` field controls left-to-right order on the canvas.
- The `agents[].position` field is in canvas coordinates (not screen coordinates).
- Connection `sourceAgentId` and `targetAgentId` must reference existing agent IDs.

If Cerevisor can't parse a hand-edited file, it shows an error toast with the parse error.

## Version control

`.cerevisor` files diff well in Git. Format is stable JSON with no churn from save to save. Two saves of the same workflow (no edits) produce byte-identical files, Cerevisor doesn't write a fresh timestamp on every save, only when content actually changes.

For workspaces with many workflows, prefer one folder per project with multiple `.cerevisor` files over a single sprawling `.cerevisor-world`, easier to review in PRs.