Your first project

Create a project from the starter, load it on your cloud instance, try it in the REPL, and run its workflow in the simulation.

This page assumes you have installed the CLI and signed in.

1. Create the project

zeon new project my-project

This creates the project in the cloud, seeds it with the starter, and writes a working tree to ./my-project/:

created project my-project (<project id>)
  working tree: /path/to/my-project
  head:         <commit sha>

Project names are unique per account. To put the working tree elsewhere, pass a directory: zeon new project my-project ~/work/my-project. The directory must be empty or not exist.

2. Look at what you got

my-project/
  project.json            name, description, active_workflow, active_world, setup
  AGENTS.md, CLAUDE.md    the guide for coding agents
  README.md
  viewer.yaml             camera presets for the 3D viewer
  skills/move_plate/      pick a plate by its grasp anchor, set it on a seat
  skills/shaker_lid/      open or close the plate shaker's lid
  workflows/plate_transfer.json         the active workflow
  workflows/plate_through_shaker.json
  canvas/plate_transfer_screen.tsx, canvas/plate_through_shaker_screen.tsx   each workflow's input screen
  monitors/               notify-only camera checks for each workflow
  worlds/shaker_deck/world_state.json
  objects/wellplate_96_flatbottom/, objects/wellplate_stand/, objects/wellplate_shaker/

The starter world shaker_deck has a front table with two plate stands and a 96-well plate, and a back table with a plate shaker. The workflow "Plate Transfer", the project's active workflow, moves the plate from stand 1 to stand 2 with the right arm. The workflow "Plate Through Shaker" opens the shaker lid, moves the plate from stand 1 into the shaker, closes the lid, then opens it again, moves the plate to stand 2 and closes the lid. Each workflow has a canvas: its input screen in the app, where you pick the objects and confirm before Run. The files in monitors/ are camera checks that only notify; they are read only on a rig with camera recording set up. The starter is written for the dual-arm setup named in its project.json.

The .zeon/ folder holds the project's local history. Do not edit it.

3. Load it on your cloud instance

cd my-project
zeon up

zeon up loads the version last pushed to the cloud on your cloud instance, then loads the project's active world (shaker_deck). It prints progress while it works, then:

project: my-project (<project id>)
setup: <setup name>
world: shaker_deck
viewer: <link to the 3D viewer>

The first load after an instance starts can take a few minutes. If every instance is in use, the command reports that no instance is free; try again in a minute.

4. Try it in the REPL

The REPL is the main way to work with your instance: you send Python with zeon py, it runs in the simulation at once, and you see the result.

zeon py 'skills.list()'
zeon py 'skills.shaker_lid(lid="open")'
['move_plate', 'shaker_lid']

The second command opens the shaker lid with the left arm; watch it in the viewer. zeon brief shows the project, the world and its objects, and the inputs of every skill and workflow. See The REPL and A REPL session. The REPL needs REPL access on your account; without it, zeon py exits with code 3.

Run zeon up again before the next step: it reloads the world, so the lid is closed again.

5. Run the workflow

Open the run screen in the web app:

zeon app "Plate Transfer" --run

This prints a link to the workflow's run screen on your instance (zeon app needs CLI 1.5.5 or newer). It signs your browser in and is for you only: it works once and is valid for 5 minutes, so open it right away (run the command again for a fresh one). Open it, pick the plate and the two stands on the Inputs tab, click Confirm setup, then Run. The 3D view shows the arm working; the Log tab shows each step.

Or run it from the terminal:

zeon run "Plate Transfer"
zeon run "Plate Through Shaker" --timeout 600

zeon run starts the run in the simulation and waits for it, printing run <id> completed at the end. It runs Fast at 8x by default: every move is planned as on the robot, then played back (--speed 1|2|4|8). It waits 120 seconds by default; the longer workflow may need --timeout 600. Read the steps with zeon logs <id>.

6. Change something

Edit a file, for example a skill in skills/move_plate/robotic_code.py, then:

zeon commit -m "Slow down the place move"
zeon sync

zeon commit records the change locally. zeon sync merges anything new from the cloud, pushes, and refreshes your instance so it runs the new version (it prints instance refreshed). Call the skill again in the REPL, or run the workflow again, to see the effect. This is the development loop.

7. Release the instance

zeon down

Other ways to start

CommandUse it when
zeon new project NAME --template emptyYou want a project with no files.
zeon clone PROJECTThe project already exists in the cloud (yours, or one you created in the app). PROJECT is its id or name.
zeon initYou have a project folder on disk (with project.json, skills/, workflows/ and worlds/) that is not linked to the cloud yet. Run it inside the folder. The cloud project is named by "name" in project.json; the folder name plays no part.

zeon clone and zeon init write AGENTS.md and CLAUDE.md when the project has none (--no-agent-guide skips them). See Working with a coding agent.


Did this page help you?