Your first project

This takes about ten minutes. You need the CLI installed and signed in.

Everything up to the run happens in your terminal. The last step moves to the browser, because watching a robot arm move is the one thing a terminal cannot do.

1. Create the project

From wherever you keep your work:

zeon new project my-project

One command does two things. It creates the project in the cloud, then materializes a working tree on disk from that project's first commit. You end up with local files and a cloud project already in step with each other.

It prints the project id, where the working tree landed, and the commit you are sitting on:

created project my-project (3f2a9c1e-8b4d-4e7a-9c11-5d6e7f801234)
  working tree: /path/to/my-project
  head:         a1b2c3d4...

By default the working tree goes in ./my-project/. Pass a second argument to put it somewhere else, and --description to set the project's description:

zeon new project my-project ~/work/plates --description "Plate prep experiments"

The command refuses rather than overwrites if the destination already exists and has anything in it.

2. Look at what you got

cd my-project
ls

A new project is not empty. The server seeds it with a small runnable example so you have something that works before you have written anything:

project.json      the manifest: name, description, active workflow and world
CLAUDE.md         authoring notes for the project
skills/           one folder per skill, plus a shared utils.py
workflows/        one JSON file per workflow
worlds/           one folder per world
objects/          the lab objects the world places
canvas/           custom input forms, when a workflow uses one

Open a skill and read it. The two files that matter are the metadata and the Python:

cat skills/*/metadata.yaml | head -20

The thing worth internalising early: a skill's parameters come from the Python function signature in its robotic_code.py, not from metadata.yaml. The metadata carries the id, version, description and tags. The signature carries the inputs. See Authoring a skill.

3. Add a workflow

zeon new workflow my_first_workflow

created workflow my_first_workflow
  - workflows/my_first_workflow.json

Edit workflows/my_first_workflow.json to get started.

You get a minimal graph: a start node, an end node, and one edge between them. Nothing runs yet, but it is a valid workflow.

This is where the strict naming rule applies. Item names must match ^[a-z_][a-z0-9_-]{0,63}$, so lowercase letters, digits, underscores and hyphens, starting with a letter or underscore, up to 64 characters. A name that fails is rejected before any file is written.

zeon new checks every file it is about to write for collisions first, so a clash aborts cleanly instead of leaving a half-made workflow behind.

The same command makes the other item kinds:

zeon new skill my_skill
zeon new world my_world
zeon new object <catalog-name>
zeon new canvas my_first_workflow

4. See what changed, then push it

zeon status

Your new workflow shows under Added. Nothing has left your machine yet.

zeon diff

Then push:

zeon sync -m "Add my first workflow"

zeon sync commits your working tree, pulls whatever the cloud has, merges the two, and pushes the result. One command, and it always pulls before it pushes, so it cannot fail the way a bare push can when someone else has moved the project on.

This is the loop you will repeat all day. It is worth reading The development loop once before you settle into it.

5. Run it in the simulator

Open https://zeonsystems.app and sign in.

Your CLI credentials and the browser session are separate things. zeon auth login wrote a token for the CLI to use; it did not sign your browser in. So you sign in to the web app once, in the browser, even though the CLI is already authenticated.

The app routes you into a project rather than showing a list. If it lands you somewhere else, switch with the project dropdown in the header.

From Home, click Execute Workflow. That is the way into the Workflow Editor.

Pick your workflow in the Workflow dropdown. A workflow with one edge and no skills will not show you much, so switch to the seeded example instead: it is wired end to end and declares a custom input form, so the Inputs tab renders that form rather than a plain list. Fill it in, submit it, and Run becomes available. An unbound canvas workflow refuses to start, rather than quietly running against example data.

Click Run, name the run if you want it labelled, and watch the arm work through the graph in the 3D viewport. The Log tab streams the run log as it happens.

To edit the graph visually rather than in JSON, see Authoring a workflow. Saving there commits to the same project you just pushed to, so the CLI and the app stay on one history.

Where to go next