There are three ways to work with a project outside the browser, and they all use the same files, so you can mix them: save to GitHub from the editor, clone the repository and open it in VS Code, sync from VS Code or the terminal, and open it in Mokxi again.
What a saved project looks like
Every save to GitHub, every mokxi pull and every project VS Code opens has the
same layout:
| File | What it is |
|---|---|
Blink/Blink.ino |
the sketch, as an Arduino IDE folder, with its other tabs beside it |
diagram.mokxi.json |
the whole project: parts, wires, notes and code. Mokxi opens it as it is |
README.md |
what the project is, with an Open in Mokxi badge |
.vscode/extensions.json |
recommends the Mokxi extension when the folder opens in VS Code |
.vscode/settings.json |
which Mokxi project the folder is |
.vscode/tasks.json |
push, pull, run, compile and upload as VS Code tasks |
.gitignore |
leaves out the command line's sync state and build output |
The folder takes the project's name, so the Arduino IDE opens it as it is
(File > Open > Blink/Blink.ino). A project with two boards gets a folder for
each, such as Traffic_Lights_uno1/ and Traffic_Lights_esp1/.
Edit the sketch in the folder, not inside diagram.mokxi.json: when Mokxi
reads the repository back, the folder wins. A tab you delete from the folder is
deleted from the project, and a new file in it becomes a new tab.
The README, .gitignore and the .vscode files are yours once they exist:
Mokxi writes them the first time and leaves your edits alone after that.
Save to GitHub from the editor
- Open Export in the editor's header.
- Under GitHub, press Connect GitHub. GitHub asks you to let Mokxi write to your public repositories. Tick Include private repositories first if you want private ones too.
- Back in the editor, open Export again and press Save to GitHub.
- Pick New repository (Mokxi names it after the project) or one of yours, write a commit message if you like, and press Save to GitHub.
You get a link to the commit on GitHub. Every later save is a new commit on the same branch. The line at the top of the card says where you are:
- Synced with ada/blink (main): GitHub has exactly this project.
- Changes not saved to ada/blink yet: you changed the project since.
- ada/blink has newer commits: somebody pushed to the repository. Use Open from GitHub to get them.
Open from GitHub
Open Export and press Open from GitHub, then pick one of your
repositories or paste any repository you can read (owner/name or a
github.com link).
- A repository saved from Mokxi opens as it was saved, with any edits made to the sketch folder on GitHub or in VS Code.
- A plain Arduino sketch repository (a folder with an
.inofile) opens too. Mokxi puts it on an Uno, or an ESP32 when the sketch includes WiFi. Change the board if it is meant for another one.
What was open before goes on the shelf first, as with Open JSON, so nothing is lost. The Open in Mokxi badge in a saved repository's README opens the project right away.
Connecting, and disconnecting
Mokxi asks GitHub for repository access only when you press Connect GitHub, never when you sign in. It is a separate permission from signing in with GitHub, and it works the same if you sign in with Google, Microsoft or email.
The access is stored encrypted with your account and used only when you press Save or Open. Nothing else in Mokxi reads it, and it is never sent to your browser.
To disconnect, go to Settings > Connected accounts and press Disconnect. Mokxi revokes its access at GitHub and deletes it. Closing your account does the same. You can also revoke it on GitHub, under Settings > Applications > Authorized OAuth Apps.
GitHub sync is not offered to students in a class or to children's accounts.
VS Code
Install Mokxi from the VS Code Marketplace (search for Mokxi in the Extensions view), or from Open VSX in VSCodium and Cursor. A folder saved from Mokxi already recommends it.
Run the circuit in VS Code
Open a project folder: a Mokxi project, a Wokwi project (wokwi.toml and
diagram.json) or a sketch. Press Start Simulator (the play button on a
sketch or the diagram). The circuit runs in a panel beside your code, on the
same engine as the Mokxi editor, and the Mokxi Serial Monitor terminal
shows what the boards print; type a line there and press Enter to send it.
Saving the sketch or the diagram, or a new build from your build tool, runs it
again. Stop and Restart are on the panel's title bar and in the status bar.
A project with a build (the firmware wokwi.toml names, a PlatformIO build, or
an arduino-cli build) runs that build; otherwise the panel compiles the sketch
the way the editor does. None of this needs an account.
Tests, lint and CI
- Scenario files (
mokxi.test.yaml,*.test.yaml, Wokwi's*.scenario.yaml) show up in VS Code's Testing view. Each scenario is a test with its steps under it; a failure points at the step's line, with the last serial lines. - Mokxi: Check the Circuit (Lint) puts wiring problems in the Problems panel. It runs when you save the diagram too.
- Mokxi: Screenshot a Display saves a display as a PNG at the moment you pick.
- Mokxi: Set Up CI (GitHub Actions or GitLab) writes the workflow, the
GitLab CI file, or both, and a first
mokxi.test.yamlif the project has none. See simulation tests in CI.
Your Mokxi projects
- Click the Mokxi icon in the Activity Bar and press Sign In. Approve the short code in your browser, or paste a token from Settings > Developer.
- Your projects are listed in the sidebar. Click one to open it as a folder.
- Edit the sketch.
.inofiles get Arduino highlighting, and snippets such assketch,blink,buttonandevery. - Press Sync (the cloud on the editor's title bar) to send it to Mokxi.
- Open in Mokxi (the Mokxi item in the status bar) opens it in the editor in your browser.
Sync refuses to overwrite work done in the browser since your last sync, and Pull refuses to throw away edits you have not synced. Each tells you why and lets you choose. Opening, syncing, pulling and uploading are part of Pro.
Compile and upload
Mokxi: Compile (arduino-cli) uses arduino-cli if you have it, with errors in the Problems panel, and Mokxi: Compile and Upload to Mokxi syncs, compiles and stores the build with the project, so mokxi.com runs exactly what you built. You do not need arduino-cli for the simulator panel, which compiles a sketch itself.
The command line
The same things work from a terminal with npx @mokxi/cli. See
The mokxi command line.
npx @mokxi/cli login
npx @mokxi/cli pull https://mokxi.com/p/abc123 blink
cd blink && git init
npx @mokxi/cli push
npx @mokxi/cli run --timeout 5s
Which plans
GitHub sync and the command line are on every plan. mokxi run and mokxi test compile and simulate on your own machine, so they are free and need no
sign-in. In VS Code, the simulator panel, tests, lint, screenshots, Set Up CI
and Compile are free and need no account too. Your Mokxi projects in VS
Code (opening, Sync, Pull and Compile and Upload to Mokxi) are part of Pro
(and the student price and Classroom); without it, the extension says
so and offers the 7-day Pro trial where you can still start it. CI runs (the GitHub
Action, or the command line tool in a CI job) are free for public
repositories; for private ones, CI comes with Pro (and the student price,
Classroom, the trial, Lifetime, and Ultra for accounts that still have it); see simulation tests in CI. If you used either in the 60 days before
October 12, 2026, you keep it until December 11, 2026, and the tool tells you
so. mokxi run --cloud and mokxi simulate run on Mokxi's servers and use the
API minutes your plan includes; the developers page lists them.