File Formats

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):

{
  "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

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.