ev-sim

---

ev-sim is Cornell Electric Vehicles' autonomous-driving simulation platform, built for reproducible development and testing across interactive and headless workloads.

• Deterministic simulation: a shared fixed-step kernel powers browser and headless execution with seeded resets, reproducible state, and trajectory hashing.
• Parallel autonomy/RL: isolated headless environments run through a gRPC supervisor with Python Gymnasium / Stable-Baselines3 integration and shared-memory sensor transport.
• Vehicle & sensor simulation: LiDAR, camera, IMU/GNSS/odometry, physics, telemetry, binary logging/replay, scenario authoring, and ROS-oriented integration.

Note

This is Alpha (0.2.0). The API is not stable, and the documentation is incomplete. Marketplace and configuration-gated PBR are previews. Please reach out to the maintainers if you want to contribute or use this project. See CHANGELOG.md for the 0.2.0 scope and migration notes.

The product/repository brand is ev-sim; npm/Python packages and CLIs use the cev-sim name.

---

Quick start

Prerequisites

You need Node.js >=22.22.2 <23; development and CI use 22.22.2. Download it from nodejs.org or use the repository .nvmrc.

Install

# latest main (development)
curl -fsSL https://raw.githubusercontent.com/cornellev/ev-sim/main/install.sh | bash

# reproducible Alpha release (once the v0.2.0 tag is published)
curl -fsSL https://raw.githubusercontent.com/cornellev/ev-sim/v0.2.0/install.sh \
  | bash -s -- --ref v0.2.0

The installer writes the clone to ./ev-sim, creates .env.local, and asks whether to enable the marketplace. Enter enables it. n writes CEV_SIM_MARKETPLACE_ENABLED=0. An existing value is kept. To start up the app, run these commands:

cd ev-sim
npm run dev

The app uses port 3000 when PORT is unset. Open http://localhost:3000 in a browser.

This command installs ev-sim into a chosen directory. The --start flag runs the app when that command finishes.

curl -fsSL https://raw.githubusercontent.com/cornellev/ev-sim/main/install.sh | bash -s -- --dir ~/ev-sim --start

If ev-sim is already on this computer, run these commands:

npm ci
npm run build
npm start

Workspaces

The app opens on Simulation. Press Escape to open the workspace switcher.

Build and run

• Simulation. Run vehicles, sensors, and scenarios.
• Environment Editor. Edit environments and scenes.
• Vehicle Editor. Create and inspect vehicle manifests.
• Run Configuration. Edit simulation manifests.
• Scenarios. Create test scenarios.
• Experiment Suite. Experiment with scenarios.
• Headless Runs. Queue and monitor server runs.

Logic

• Scripting Canvas. Build simulation logic with blocks.
• Bindings. Bind scripts to signals.

Inspect

• Replay. Inspect recorded simulations.
• Analysis. Graph live data.
• Logs. Organize recorded simulations.

The switcher also has a Plugins pane. Use that pane to install a simulator package.

Environment Editor

Scripting Canvas

Analysis

The Analysis workspace graphs signals from a live run or a recorded log.

Vehicle Editor

Headless runner

The headless runner includes a CLI and a worker. The Python package is a client of that runner. This repository builds both as internal artifacts. This repository does not publish them on npm or on PyPI.

npm run dist:headless

That command writes an npm tarball, a Python wheel, a Python sdist, a compatibility manifest, and SHA-256 checksums.

You can download the Internal headless candidate artifact from the manual workflow. Install that artifact when you do not need the app. Release rules are in Headless release and CI gates. Jetson steps are in Jetson deployment.

In this repository the runner command is ./bin/cev-sim.js. Command details are in Headless CLI. The Headless Runs workspace queues server runs. The same workspace monitors those runs.

The Python package is a Gymnasium client and a Stable-Baselines3 client for the JavaScript supervisor. Adapter details are in Python adapter.

Agent plugin

This repository is a Cursor Agent Plugin. The plugin files are plugin.json, mcp.json, and skills/cev-sim/. An import gives the agent the cev-sim skill. Cursor invokes that skill automatically. An import also registers the MCP endpoint http://localhost:3000/mcp. The transport is Streamable HTTP.

Import does not run the app. Run npm start (or npm run dev for dev) before MCP discovery. The server id is cev-sim.

Load the plugin in one of these ways:

• Import the Git URL of this repository in Cursor.
• From the Cursor CLI, run agent --plugin-dir /path/to/this/repo.
• Copy or symlink this repository into ~/.cursor/plugins/local/cev-sim. Reload the Cursor window.

MCP setup without the plugin is in MCP Server.

Run the bundle validator:

node skills/cev-sim/scripts/validate.mjs

Simulator packages

A simulator package is not the agent plugin. Each package has its own plugin.json. Open the Plugins pane to install a package. You can also run cev-sim-plugin. The package contract is in Plugin API.

Documentation

• Documentation index
• Getting started
• Architecture
• Development workflow
• Environment editor
• Earth import
• Simulation
• Visual scripting
• Script bindings
• Vehicle manifests
• Run manifests
• Headless CLI
• Python adapter
• Headless release and CI gates
• Jetson headless deployment
• Plugin API
• Telemetry, logging, replay, and analysis
• ROS integration
• MCP Server
• Assets
• Troubleshooting

CommonRoad scenarios

CommonRoad scenarios are not in this repository. Download them from https://gitlab.lrz.de/tum-cps/commonroad-scenarios. Put the scenarios folder in public/. The local path is public/scenarios.

Example browser path:

/scenarios/recorded/NGSIM/Peachtree/USA_Peach-1_1_T-1.xml

Asset rules are in Assets.

License

The Apache License 2.0 covers this repository. It also covers the headless npm artifact and the Python package.

References

M. Althoff, M. Koschi, and S. Manzinger, "CommonRoad: Composable Benchmarks for Motion Planning on Roads," in Proc. of the IEEE Intelligent Vehicles Symposium, 2017, pp. 719-726.