zynoptes.

Docs · ZynoCode

Getting started with ZynoCode.

ZynoCode is the Zynoptes command-line tool, zc. Describe your robot and its task in plain English, and it builds and validates a simulation with you, tests it at scale, and brings back findings and validated fixes. This page covers what you need for your first project.

For ZynoCode 1.15.5Updated Read as Markdown

What ZynoCode does

ZynoCode runs in your terminal, on your own computer, in your project's folder. It works in two modes:

  • Guided, the default: ZynoCode builds and validates a faithful simulation of your robot and task, freezes it once it holds, generates test scenarios, runs them at scale as a cloud campaign on Isaac Sim, and brings back findings and validated fixes, then closes the project out.
  • Free: quick builds, demos and try-outs, such as a rough scene, your robot in a new space or a short video, without the guided stages and checks.

In ZynoCode itself, ask “What can you do?” or “How do I get started?” for a short guide like this one.

Install

ZynoCode runs on Linux x64 (tested on Ubuntu 24.04), in WSL, and on Windows x64. There is no macOS version.

Linux and WSL

Shell
curl -fsSL https://downloads.zynoptes.com/install.sh | bash

Windows, in PowerShell

PowerShell
irm https://downloads.zynoptes.com/install.ps1 | iex

Both install the current release for your user, without administrator rights: ~/.local/bin/zc on Linux, and %LOCALAPPDATA%\ZynoCode\current\zc.exe on Windows, which the installer adds to your user PATH. If the Linux installer says ~/.local/bin isn't on your PATH, run the line it prints.

Simulators

  • Isaac Sim 6.1, for Isaac projects and cloud campaigns. ZynoCode finds it and sets it up when it starts.
  • Gazebo needs Linux or WSL, with ROS 2 Jazzy, Gazebo Harmonic and Python 3.12.
  • On Linux, the simulation tools need jsonschema in the system Python: sudo apt install python3-jsonschema.
  • On Windows, shell commands need Git for Windows, and Isaac Sim's tools need Python 3.11 or newer (3.12 recommended) with jsonschema, which ZynoCode offers to install for you, showing the command first.

Update

ZynoCode keeps itself up to date. When it starts, and every 6 hours while it runs, it checks for a newer release and installs it in the background. The session you're in keeps its version; the new one starts the next time you open zc. To update right away, run:

Shell
zc update

To delay ordinary updates, set "autoUpdates": false in your settings (see Settings, below). An update Zynoptes requires installs either way, and ZynoCode then asks you to close and reopen it.

If you attach ZynoCode to an Isaac Sim you start yourself: after an update, close that Isaac Sim and run /sim in zc. It sets Isaac Sim up again with the new release's tools. Then start Isaac Sim with the Zynoptes Isaac bridge as before.

Your first run

Open a terminal in your project's folder and run zc:

Shell
cd /path/to/your/project
zc

You can also start with a message, zc "Test my robot picking up this part", and attach a file with @, as in zc @world.sdf "Explain this world".

In a folder it hasn't seen, ZynoCode asks up to three things before the session opens. The very first time, it also asks you to sign in:

  1. Trust this folder? Trust lets ZynoCode load the project's own settings, skills and notes, and guided projects run only in a trusted folder. In your home folder, or a folder above it, ZynoCode offers answers for this session only. /trust saves a decision for later sessions.
  2. Approve automatically in this folder? “No, keep asking me” is the default. See Approvals and auto-approve, below.
  3. Simulators. ZynoCode looks for Isaac Sim and Gazebo and asks only what it needs: which one to use in this folder when both can run, which Isaac Sim when it finds several, or where Isaac Sim is when it finds none. /sim runs this check again at any time.
  4. Sign in. Paste your Zynoptes API key, from your dashboard at dashboard.zynoptes.com. ZynoCode keeps it for next time; /login replaces it and /logout removes it.

Then describe what you want. The footer shows which mode you're in: guided or free.

A good first prompt

The more your first message covers, the fewer questions follow. What matters most: what you want, what to test and what not to, the controllers and sensors, any VLMs or VLAs in your stack, and where the files are. A short prompt works too: ZynoCode asks for the rest.

Guided mode

I want a validated sim of our UR10e cell picking totes off a conveyor onto a pallet, then a cloud campaign varying tote mass (2 to 12 kg) and conveyor speed, and fixes for what fails. Pass: every tote placed within 10 mm, in under 8 s each. Fail: a drop or any collision. Leave out the safety scanner. The controller is our ROS 2 Jazzy stack (MoveIt 2 with ros2_control at 500 Hz) in ~/ws/pick, and the sensor is a wrist RealSense D435 at 30 fps. URDF in ~/ws/pick/description; STEP, per-part STLs and the mass-properties report in ~/cad/cell; the cell drawing and photos in ~/site. Isaac Sim 6.1 on Ubuntu 24.04. All of it may be shared. The conveyor's look doesn't matter.

Free mode

Quick demo: put our AMR (URDF in ~/robots/amr) in a warehouse aisle in Isaac Sim and make a 20-second video of it driving past two pallet racks. Rough scenery is fine.

What to bring

You needn't have it all: ZynoCode asks for what's missing. “I don't know” and “skip” are answers too; ZynoCode states the default it will use and records it as an assumption.

  • What you want, and what you'll do with the results.
  • What to test and what not to: the task, success in numbers, and the failures you care about.
  • The controllers: what drives the robot, how it starts, its interfaces and topics, and any outside services it calls.
  • The sensors: which ones, where they're mounted, and their specs.
  • Any VLMs or VLAs in your stack: where they run, what they take in, and whether they're under test.
  • The robot: its file (URDF, xacro, SDF, USD or MJCF), its CAD (STEP files, one STL or OBJ per part, and the mass-properties report) and its datasheet specs.
  • The space: a description, measurements, the objects the robot handles, and photos, videos or floor plans.
  • Real-robot data, if you have any: logs, rosbags, videos and measured baselines.
  • Your setup: the simulator, its version and your operating system.
  • Where the files are.
  • Whether you may share each file, in a cloud campaign's package too.
  • What doesn't matter to you, so ZynoCode doesn't spend hours perfecting it.

Guided and free mode

Guided

For a validated simulation, a cloud campaign or fixes. New projects start in guided mode. ZynoCode keeps the project's record in ZC.md, in your project folder, so work picks up where it stopped.

Before it builds, ZynoCode asks for everything it's missing, in grouped questions you can answer in one go. Then it builds without interview questions, so you needn't stay for it. It still stops for decisions only you can make, such as how broadly to test and its credits, each paid step, and applying a fix, and for a real blocker.

Free

For quick builds, demos and try-outs. Free mode keeps its work in free/, asks as it builds, only what the next step needs, and never asks the same thing twice. When what you ask for needs a validated simulation, a cloud campaign or fixes, ZynoCode first offers to switch to guided mode.

Switching

/mode switches to the other mode, and /mode guided or /mode free picks one. Shift+Tab switches too; if your terminal doesn't pass it, as some Windows consoles don't, use /mode. ZynoCode remembers the mode for each project folder, and when it suggests a switch, it always asks you first.

Commands

Type / in zc to list every command.

CommandWhat it does
/mode [guided|free]Switch between guided and free mode.
/simFind, check and set up Isaac Sim or Gazebo for this folder. Runs between turns.
/yolo [on|off]Turn auto-approve on or off for this session. /yolo status shows the folder's saved answer, and /yolo forget clears it.
/permissionsShow what ZynoCode asks before doing. /permissions reset clears this session's approvals and turns auto-approve off.
/btw <question>Ask a side question without changing the conversation, even while ZynoCode works. /btw bring copies the answer into your prompt.
/tasks [id]List background work, or show one task. /tasks cancel <id> stops a background command.
/bg <command>Run a shell command in the background, once you approve it.
/newStart a new session.
/resumePick a saved session to continue.
/name <name>Name this session.
/sessionShow this session's file, ID and message counts.
/forkStart a new session from an earlier message of this one.
/cloneCopy this session into a new one.
/compact [instructions]Condense the conversation so far into a summary the next turns start from.
/copyCopy ZynoCode's last message.
/trustSave this folder's trust decision for future sessions.
/login, /logoutStore or remove your Zynoptes API key.
/settingsOpen settings.
/reloadReload settings, skills, prompts and project instructions. It also closes the simulators this session opened, and detaches from your own Isaac Sim.
/bug [description]Send a bug report to Zynoptes (see Getting help, below).
/hotkeysShow keyboard shortcuts.
/quitQuit zc.

Keys and phrases

  • Esc stops ZynoCode's current turn. At an approval or a question, Esc declines just that one.
  • Enter while ZynoCode works sends your message; it reads it at its next step.
  • Shift+Tab switches between guided and free mode.
  • Ctrl+O shows or hides the details of ZynoCode's steps.
  • Ctrl+C clears your prompt; press it again to quit. Ctrl+D on an empty prompt quits too.
  • Type stop campaign to stop a running cloud campaign, once you confirm.

Approvals and auto-approve

ZynoCode reads your project's files without asking. It asks before it writes or edits files, runs shell commands, reads outside the project, or reads sensitive files such as .env and .ssh. Each request offers Deny, Allow once, or Allow this exact action for this session. A request waits 30 minutes for your answer; with no answer, the step doesn't run.

Without auto-approve, every change ZynoCode makes to ZC.md asks you, showing the change, because ZynoCode treats the decisions recorded there as yours. A ZC.md that changed outside the session, through a git pull for example, comes to you for review before ZynoCode uses it.

Auto-approve (YOLO)

The first time in a trusted folder, ZynoCode asks whether to approve automatically there: “No, keep asking me”, “Yes, until zc exits”, or “Yes, always in this folder and folders inside it with no answer of their own”. With auto-approve on, ZynoCode runs commands and programs with your permissions, edits files, reads any file, .env and .ssh included, and moves cloud build files, all without asking. The status line shows YOLO while it's on.

It still asks before it attaches to your own Isaac Sim, saves your unsaved changes there, renders off-screen in it, switches modes or spends credits.

For ZC.md, it depends on how auto-approve was turned on. When your saved answer for the folder turned it on, ZynoCode's own changes to ZC.md go ahead, but it still asks before it uses a ZC.md that changed outside the session. When you type /yolo on in a session, it doesn't ask about either.

/yolo on and /yolo off change the current session. /yolo status shows the folder's saved answer, and /yolo forget clears it, so the next start asks again.

Approvals aren't a sandbox: an approved command runs with your user's permissions. For stronger isolation, run zc in a VM.

Sessions

ZynoCode saves each conversation as a session, kept per folder.

  • zc --continue (or zc -c) continues the latest session in this folder. If your last task was interrupted, ZynoCode says so, and Enter carries on.
  • zc --resume (or zc -r), or /resume inside zc, lists your saved sessions to pick from.
  • zc --session <id> opens one session, and zc --name <name> names a new one.
  • zc --no-session doesn't save the session.
  • /new starts a new session, /fork starts one from an earlier message, and /clone copies this one.

A guided project's record lives in the project itself, in ZC.md and the .zc/ folder, so a new session in the same folder picks the project up where it stopped. To carry on from another computer, ask ZynoCode to pull the project by its ID.

Credits

ZynoCode's work is measured in credits: building and checking your simulation, and running cloud campaigns.

  • Estimates first. Before it builds, and before it generates test scenarios, ZynoCode gives a credit and time estimate: the most likely figure, its usual range, the top of the range, and what it depends on most. Time and credit figures come only from these estimates.
  • Your balance. Ask “How many credits do I have left?” at any time. ZynoCode shows the credits you've used, those pending, your included and purchased credits remaining, and when they reset.
  • Paid steps have their own approval screens. A cloud campaign has two credit reviews: one to prepare it, where you type I approve, and one to run it, where you keep the quoted maximum or set a lower one. A yes in chat starts neither.
  • Stopping. Progress and the final report show the credits a campaign has used. Type stop campaign to stop one; ZynoCode asks you to confirm. Running trials end, and credits already used stay used.
  • No runaway steps. A step that uses many credits without making progress pauses to ask whether to continue.

Settings

Settings live in ~/.zc/agent/settings.json (%USERPROFILE%\.zc\agent\settings.json on Windows); a project's own .zc/settings.json can't set these three. Restart zc after a change. /settings opens more settings, such as the theme, inside zc.

SettingValuesWhat it does
autoUpdatestrue (default), falsefalse delays ordinary updates. An update Zynoptes requires installs either way.
isaac.maxInstances"auto" (default), 1, 2Whether a builder may open a second Isaac Sim, without a window, to check its work while yours stays open. "auto" opens one only on a computer with at least 64 GB of RAM and enough free memory, and closes it when it's idle or memory runs low; yours always comes first. 1 keeps one Isaac Sim. 2 opens a second even below those limits, with a warning.
isaac.telemetry"off" (default), "on"NVIDIA's telemetry and crash-report upload in the Isaac Sim that ZynoCode starts. Crash dumps stay on your computer either way. An Isaac Sim you start yourself keeps its own settings.
JSON
{
  "autoUpdates": false,
  "isaac": {
    "maxInstances": 1,
    "telemetry": "off"
  }
}

Getting help

  • Ask ZynoCode. “What can you do?” and “How do I get started?” give a short guide in zc, and /btw asks a side question while it works.
  • Check your setup. zc --help lists the options, zc --version shows your version, /hotkeys lists keyboard shortcuts, and zc auth check prints ready when you're signed in and zc can connect.
  • Report a bug. /bug sends a report to Zynoptes. It asks what went wrong and whether to include the session transcript, then asks before it uploads. The report includes your project's files and any files ZynoCode read outside it, so check there's nothing in them you can't share. Keep zc open until it shows the report ID.
  • Talk to us. Email founders@zynoptes.com, or book 15 minutes with the founders.