Use Vesk without guessing.

Getting started

From a robot file to a result

What Vesk does

Vesk turns a plain-language robotics task and a trusted robot description into ROS 2 code. It builds the code, runs bounded behavioral checks in an isolated container, and reports the evidence. When a check fails, Vesk can make another attempt. Each attempt remains visible.

Choose how to use Vesk

The Vesk Simulation Coding Agent app includes its Python runtime and dependencies, with guided setup and Plan mode. You do not need a source checkout, a separate Python installation, a virtual environment, or pip to install the full app. The source CLI is a separate setup path for invited pilots who prefer terminal commands. Docker and local verification resources are required for either path.

Set up the desktop app

Windows, macOS, and Linux use the same Vesk Simulation Coding Agent interface, including Plan mode and Machine setup. Choose the preview that matches your operating system and processor. Before opening it, verify the supplied checksum against the reviewed release record.

The Windows preview is unsigned; the macOS preview is not Developer ID signed or notarized. If your system blocks a preview, report the block to support rather than disabling its protections. Other processors, Linux distributions, and headless desktops need their own acceptance.

1. Start Docker and wait for its engine to be ready. Reopen Vesk after installing Docker so it sees the updated environment.
2. Select continue with Google in the sidebar, complete sign-in in your browser, then return to Vesk. Check that Account & Usage shows the expected invited TEST account.
3. Open Machine setup and select Check again. Complete Prepare ROS 2 verification, Download retrieval model, and Prepare reference documents, one action at a time. These prepare local resources without using Vesk model credits. Prepare physics simulation is an optional additional setup action.
4. Select Check again and resolve each named prerequisite. A completed setup action or an unknown check does not establish readiness. Return to Run when the required checks pass.

Review a plan before building

Plan mode is available in all three desktop previews. It creates a plan for you to review and edit before code generation and simulation begin. Planning uses model credits; a plan is not a verification result.

1. In Run, choose Plan, select your robot description or Use the sample claw, and describe one observable behavior.
2. Select Review for paid planning. Check the parsed robot and planning cost disclosure. This review does not start a model call or a container.
3. Select Run paid planning only when you want to spend credits on the plan. If planning succeeds, Vesk pauses at Review the plan before generating code or starting verification containers.
4. Review the names, topics, and robot relationships shown in the structured fields. Edit those fields or open Advanced: edit the complete plan JSON. Editing does not start paid work. Vesk validates the edited plan again before accepting it.
5. Read the continuation cost disclosure, then select Approve plan & start run to authorize generation and verification. Read the resulting checks and verdict together; approving a plan does not prove it works.

To ask for a different plan in words, enter a constraint and use Re-plan with added constraint. This uses model credits and returns another plan for review. Closing the review does not refund completed planning. Choosing Build instead uses the task and cost review, then proceeds with the run without this editable Plan checkpoint.

Source CLI prerequisites

• The source checkout supplied with your pilot invitation. There is no public standalone CLI package yet.
• Python 3.12 or newer for a full robotics run.
• Docker Engine on Ubuntu 24.04 x86_64, the current CI-verified live ROS host, or Docker Desktop with WSL 2 on Windows. A Windows sample has passed a live container trial; this does not establish full cross-platform coverage.
• The full Python dependencies, verification image, and grounding index from the source checkout setup.
• A URDF with complete joint limits for the CLI manifest path.
• An invited TEST account for paid-model runs.
• The TEST VESK_SUPABASE_URL, VESK_SUPABASE_ANON_KEY, and VESK_PROXY_URL values supplied with the invitation. Never use service-role credentials in the CLI.

First CLI run on Ubuntu 24.04

These commands are for Bash on Ubuntu, from the supplied checkout. Windows PowerShell uses different paths and activation commands. CI coverage and preview availability are listed in Reference below.

1. In the supplied checkout, create and activate a Python 3.12+ virtual environment with python3 -m venv .venv and source .venv/bin/activate.
2. Run python -m pip install -e ., then python -m pip install -r requirements-full.txt.
3. Start the host-specific Docker engine, run ./scripts/fetch-artifacts.sh to download the compatible verification image and grounding index from the public ghcr.io/vesk-robotics/verify package. No registry login is needed. Use the current aliases; older release tags may fail the compatibility checks. Then run python -m preflight --tier live. Fix every blocked prerequisite before continuing.
4. Run vesk login. The CLI opens Google sign-in or prints a URL to open on the same computer. It stores the session in the operating system credential vault, not a plaintext file.
5. Confirm the session with vesk whoami.
6. Start with the bundled claw by running vesk run "publish claw state" --sample --human. This uses the normal paid-run review and does not grant a free run.
7. --human shows stages, the verdict, usage, and the output location without raw event JSON. Omit it when your script needs the default JSON Lines output. Add --no-spinner for plain progress; spend confirmation still applies.
8. For your own robot, replace --sample with --manifest /path/to/robot.urdf.
9. Review the robot identity and cost ceiling before confirming any paid model work.
10. Read the verdict, named checks, skipped checks, and artifacts together.

Concepts

Read the evidence, not the color

What verification proves

A result can prove specific ROS 2 behavior such as compilation, discovery, message delivery, QoS compatibility, action lifecycle, callback behavior, and termination. The result names the case and environment that produced that evidence. It proves no more than those checks observed.

What verification does not prove

Vesk does not validate a physical robot. It does not certify safe motion, controller gains, electrical limits, collision safety, calibration, payload capacity, or field reliability. Physics scoring, when present, is labeled ADVISORY and does not turn simulated code into hardware evidence.

Attempts and corrections

A failed attempt stays failed. If Vesk produces a corrected attempt, judge that attempt by its own build and checks. Do not read a later pass as proof that an earlier artifact was valid. A skipped blocking check produces NO DATA until that check runs.

Robot descriptions

Supply kinematics, not just shape

For vesk run --manifest PATH, supply a URDF with a <robot> root. This CLI path reads URDF, even though other Vesk tools can parse SDF. Renaming an SDF file does not convert it. The CLI reports the file name and actuated-joint count before paid model work starts; check these against your robot.

Required limits

Vesk never guesses or defaults a missing limit. A guessed value could be copied into both the generated code and its test, creating a false agreement.

CAD and mesh files

STEP, STP, STL, and DAE files describe geometry. They do not provide a complete joint tree and trustworthy limits, so Vesk cannot use them as the CLI manifest. Export a URDF from your CAD or robot-authoring tool. Keep mesh files as referenced visual or collision assets.

Export a ROS description with Xacro

Xacro is a ROS robot-description authoring and expansion tool. It turns XML macros and declared parameters into plain URDF. This is not a GUI CAD export or a conversion from geometry to joint limits. Expand the description in an environment containing its required ROS packages before passing the URDF to Vesk.

Recorded CI on 10 September 2026 used Xacro 2.1.1 from ROS 2 Jazzy and the official Franka description 2.9.0 at commit 7aeeddc449edf8d62b594f9e36a81da53e7796f9. It expanded the standalone Franka Hand and loaded the result through the CLI's URDF parser. The recorded CI log is the execution evidence, not a new run performed for this guide.

1. Use the supplied Vesk checkout on Ubuntu 24.04 with the full dependencies, grounding index and vesk/verify:jazzy image prepared as above. The recorded image installed ros-jazzy-xacro 2.1.1-1noble.20260519.011123. The image tag alone does not pin that package version; check your image before treating a repeat as the same environment.
2. In a Bash terminal at the Vesk checkout root, run this shell equivalent of the recorded checkout, build and expansion steps. It downloads the public description into a fresh temporary directory, keeps the source read-only in the container, and retains the exported file after the container exits.
   Franka Hand export commands

   set -euo pipefail
   work="$(mktemp -d)"
   git clone --no-checkout https://github.com/frankarobotics/franka_description.git "$work/franka_description"
   git -C "$work/franka_description" checkout --detach 7aeeddc449edf8d62b594f9e36a81da53e7796f9
   mkdir "$work/output"
   container_name="vesk-franka-export-$(basename "$work")"
   cleanup() {
     timeout --signal=TERM --kill-after=5s 10s \
       docker rm --force "$container_name" >/dev/null 2>&1 || true
   }
   trap cleanup EXIT
   trap 'exit 130' INT
   trap 'exit 143' TERM
   timeout --signal=TERM --kill-after=10s 300s \
     docker run --rm --name "$container_name" \
       --network none --cap-drop ALL --security-opt no-new-privileges \
       --memory 2g --memory-swap 2g --cpus 2 --pids-limit 512 \
       --user "$(id -u):$(id -g)" --workdir /tmp \
       -v "$work/franka_description:/src/franka_description:ro" \
       -v "$work/output:/out:rw" \
       vesk/verify:jazzy bash -e -o pipefail -c '
         mkdir -p /tmp/franka-build
         cd /tmp/franka-build
         colcon build --base-paths /src/franka_description \
           --packages-select franka_description --cmake-args -DBUILD_TESTING=OFF
         source install/setup.bash
         xacro "$(ros2 pkg prefix franka_description)/share/franka_description/end_effectors/franka_hand/franka_hand.urdf.xacro" \
           -o /out/franka_hand.urdf
       '
   printf 'Exported URDF: %s\n' "$work/output/franka_hand.urdf"

3. Compare the exported joint names and limits with the pinned upstream joint declarations. With unchanged defaults, fr3_finger_joint1 and fr3_finger_joint2 are prismatic. Each declares lower=0.0, upper=0.04 metres, effort=100 newtons and velocity=0.2 metres per second. The second joint mimics the first. Preserve these declarations; do not replace missing values with guesses.
4. In the same terminal, with the Vesk virtual environment active, parse and check the exported file with the local validator:

   python cad-pipeline/validate.py "$work/output/franka_hand.urdf"

   This command calls the same URDF parser used in the recorded manifest check, then checks the model and prints its summary and findings. It sends nothing to a model and does not generate code or run a simulation. These command details come from the current validator source; the recorded CI evidence above is a parser check, not a recorded execution of this validator command. Exit 2 means the file could not be read or parsed. Exit 1 means validation found errors. Exit 0 means no validation errors; warnings may still need review. This validator does not reject every missing effort or velocity limit. A zero exit does not replace the source comparison in the previous step.

The recorded parser summary was franka_hand: 4 links, 3 joints (1xfixed, 2xprismatic), 1 actuated DoF, 1 mimic. Expect the validator to print that summary with its findings. If names, limits or counts differ, stop and inspect the source, expansion arguments and output. Keep the description package at $work/franka_description so the validator can find the referenced meshes beside the output directory. Fix validation errors and review warnings before using this model. A successful manifest read does not prove a simulator loaded it.

The CI suite used a stub model for its live-path tests. It proves this export and intake wiring, not paid-model quality, a customer first run, or hardware validation. Any later verification remains simulation-only. This walkthrough does not establish a SolidWorks, Onshape or other GUI CAD exporter workflow.

Writing tasks

Ask for one observable behavior

Name the ROS behavior, the relevant joint or interface, and any concrete target. Keep the task focused and concise. The current release represents one generated node per task.

A task that asks for physical validation, missing robot facts, or several independent behaviors cannot produce an honest verified result. Split broad work into separate observable tasks.

Troubleshooting

Fix the named boundary

Use the CLI message and the detail printed beside it. The entries below quote complete messages or their stable prefixes; file paths, missing module names, and parser details vary with the input. A manifest refusal occurs before paid model work.

Run failures

Machine setup failures

Run python -m preflight --tier live from the checkout. Each check prints its status, detail and fix. These are the Linux messages for the current Ubuntu live-run path; other hosts get their own remedies. An unknown check is not a readiness pass.

• docker cli: not on PATH. Preflight says: "install Docker Engine for your distribution (https://docs.docker.com/engine/install/), then add your user to the docker group and log back in".
• docker daemon: not reachable. Preflight says: "start the Docker daemon (on a systemd distro: sudo systemctl start docker); if it is already running, add your user to the docker group and log back in".
• docker did not respond within 8s. This is an unknown result. The Linux remedy is "start the Docker daemon (on a systemd distro: sudo systemctl start docker)".
• grounding/data/index does not exist. Run ./scripts/fetch-artifacts.sh from the checkout to download the stamped release index, then rerun preflight.
• downloaded index failed its compatibility stamp; live index untouched or downloaded index failed its integrity check; live index untouched: the artifact script refused the downloaded index. Keep the existing index; use the local-build fallback printed by the script or report the failure to support. Do not bypass its compatibility or integrity checks.
• Verification image missing or unavailable:follow the specific preflight fix. A failed Docker inspection can mean an unavailable daemon, not an absent image. Do not substitute an unpinned image.
• Exit 137 or memory failure: on Linux, preflight explains: "Docker Engine uses the host's own CPU and RAM - there is no VM to resize; free memory or run this on a larger machine".
• No space left on device: free Docker disk space, then retry. Keep any generated workspace you still need before removing Docker data.

Billing

Plans set the room available for paid work

• These multiples compare monthly credit allowances, not a fixed number of tasks or successful runs. Planning, generation, and retries use credits; consumption depends on the task and model calls. Unused monthly credits expire at the end of the billing period and do not roll over.
• Team usage is shared across active members. At least 2 members are required to subscribe. Billing and the included usage pool retain a 2-seat minimum if a member leaves.
• Usage is shown as a percentage, not as internal model-cost figures.
• Paid calls use available included or deliberately purchased credit only. Running out of credit does not authorize additional charges.
• If no usable credit remains, paid work stops at the next unpaid call boundary and reports NO DATA. Existing run records and artifacts remain.
• Purchased credit packs apply to individual accounts only, expire after 365 days, and do not refill a Teams pool. An exhausted team must wait for the next period or ask its billing owner to review the plan. Credit-pack checkout is not yet generally released; use the billing setup supplied with your pilot invitation.

See the pricing page for the current plan presentation.

MCP & API

One Vesk connection for your agents

MCP and API access are part of Vesk Simulation Coding Agent, connected under the Vesk name. MCP lets a compatible coding assistant call its tools and read the resulting evidence from the same conversation where you write code.

How the connection works

1. Set up the local agent and Docker, then connect your coding assistant through MCP.
2. Authorize access with a scoped API key from your Vesk account.
3. Ask the assistant to test existing ROS 2 code or use the agent to generate and test code.
4. Read the job status and simulation evidence, then decide what to change or test next.

Simulation runs in local Docker containers on your computer. Requests for Vesk-generated code use the hosted model API. This integration does not provide hosted simulation compute.

API access and controls

The initial API supports model-job submission, status, results, and cancellation. Keys have explicit permissions, expiration, rate limits, and model-call allowances. You can rotate or revoke a key without sharing your account sign-in with another tool.

Usage and billing

Testing existing code locally makes no Vesk model calls. Vesk-generated code requires explicit paid consent and uses existing Vesk model credits, subject to key and session limits. Your coding assistant may have its own charges. Additional integration pricing has not been announced.

Reference

Current supported surface

A result still does not make sense? Send the run details to support.