project.json

The project manifest: name, the default workflow and world, and the setup the project is authored for.

project.json sits at the root of every project. It is written when the project is created. The app reads it; saving a world, opening a workflow or renaming the project does not rewrite it. To change a default, edit the file and sync it like any other file.

Example

A new project from the starter template:

{
  "name": "my-project",
  "description": "",
  "created_at": "2026-11-08T10:15:02.118Z",
  "updated_at": "2026-11-08T10:15:02.118Z",
  "archived": false,
  "active_workflow": "plate_transfer",
  "active_world": "shaker_deck",
  "setup": "<the starter's setup>"
}

Fields

FieldTypeDescription
namestringThe project name at creation. zeon init names the new cloud project from it, and refuses when it is missing. Data export uses it as the project part of each exported run's key, and falls back to the project id when it is empty.
descriptionstringFree text.
created_at, updated_atstringCreation time, UTC with milliseconds. Both get the same value.
archivedbooleanWritten as false. Archiving a project changes the cloud record, not this file.
active_workflowstring or nullThe workflow id (workflows/<id>.json) the editors open first.
active_worldstring or nullThe world id (worlds/<id>/) the editors select first, and the world zeon up loads when you pass no --world.
setupstring, optionalThe setup (robot rig) the project is authored for. See below.

The name shown in the app comes from the cloud project record. zeon project rename changes that record and leaves project.json as it is.

active_workflow and active_world

Both are checked when read: workflows/<active_workflow>.json must exist, and worlds/<active_world>/ must be a folder. When a value is missing or points at nothing, there is no default and the editor falls back to the first item in its list. A stale value is ignored, not repaired.

Saving a world does not change active_world.

setup

A setup describes the robot rig the platform builds when your instance starts: how many arms (one or two), their models, the gripper on each arm, where each arm's base stands in the world, and the wrist cameras. Each organization may use a fixed list of setups and has a default one.

When you open a project on your cloud instance, the instance switches to the project's setup if your organization may use it. Switching restarts the robot service on the instance, which takes a few minutes. A setup your organization may not use is ignored: the instance stays on its setup, or moves to your organization's default if its current setup is not available to you. A project without setup leaves the instance on whatever setup it runs.

The world's coordinates are only meaningful for the setup they were built on: a world built for one rig places objects relative to that rig's arm bases. The starter project's world and skills are written for the starter's setup.

On a deployed box the setup is fixed by the box and setup in project.json is not applied.

When the file is missing or malformed

The defaults are treated as absent: the editors fall back to the first item in each list, and no setup switch happens.

See also


Did this page help you?