Compile Server

The compile server turns sketches into firmware. It is a small Node.js program in the server folder that runs arduino-cli with the board packages installed by setup.bat.

Starting

start.bat starts it in the Circzy Server window. To start it by hand:

cd E:\circzy
node server\index.mjs

The app reaches it through the development server, which forwards every request under /api to http://localhost:3001.

What happens when you press ▶

The app sends the sketch and the board's FQBN to POST /api/compile.
The server checks its cache. An identical sketch for the same board is answered immediately.
Otherwise the sketch is compiled in a temporary build folder. Builds reuse the precompiled core of each board, so only your code is compiled.
The firmware is returned to the app: an Intel HEX file for AVR boards, a binary image for Pico and STM32, and a flash image for ESP32 and ESP8266.

When compilation fails, the compiler output is cleaned up so that file names and line numbers point to sketch.ino. Problems with the server itself, such as a missing board package or a full disk, are reported as short messages in your language.

Warm-up

When the server starts, it compiles a small program for every board in the background (about 1–3 minutes). This fills the core cache so that your first real compile is fast. Leftover build folders that are no longer used (for extra workers or unknown boards) are deleted at the same time; the others are kept and reused.

Parallel builds and the queue

The server compiles several sketches at the same time: one per two CPU cores, up to four. When all workers are busy, new requests wait in a queue and the app shows the position (for example Queue position 2).

Installing a library pauses compiling until the installation is finished.

Configuration

Environment variable	Default	Meaning
`PORT`	`3001`	The port the server listens on.
`CIRCZY_WORKERS`	Half the CPU cores, 1–4	Number of parallel compilations.
`ARDUINO_CLI`	`tools\arduino-cli.exe` if present, otherwise `arduino-cli` on the PATH	Path to a different `arduino-cli` executable.

Example:

set CIRCZY_WORKERS=2
node server\index.mjs

Running Circzy on a server

The deploy folder contains everything needed to run Circzy online on an Ubuntu VPS with Docker: the web app behind Caddy with automatic HTTPS, and the compile server in public mode (CIRCZY_MODE=public). The step-by-step guide is in deploy/README.md; the short version is:

sudo bash deploy/install.sh                                 # access by http://SERVER_IP
sudo bash deploy/install.sh yourdomain.com you@example.com  # domain + HTTPS

In public mode the compile server:

Accepts requests only from the configured domain (CIRCZY_ORIGINS).
Limits compilations per visitor (CIRCZY_RATE_LIMIT per minute, CIRCZY_MAX_ACTIVE at the same time) and answers "busy" when the queue is full (CIRCZY_MAX_QUEUE).
Runs as a non-root user without internet access and with a memory limit.
Shows only the preinstalled libraries in the Library Manager; installing and searching are turned off.

On a server, the browser talks to the Circzy API (the api folder), which handles sign-in, accounts, cloud projects and the admin dashboard, and forwards compilations to the compile server with the user's plan so Pro users are queued first. See Accounts, Cloud Projects & Pro.

API

Method and path	Description
`GET /api/health`	Returns `{ "ok": true }` when the server is running.
`GET /api/config`	Returns `{ "public", "libraryInstall" }`: whether the server runs in public mode and allows installing libraries.
`POST /api/compile`	Body `{ "code", "fqbn", "id" }`. Returns `{ "hex" }`, `{ "firmware" }` or `{ "flash" }`, or `{ "error" }` with status 400.
`GET /api/compile/status?id=…`	Queue position of the compilation with that `id`.
`GET /api/libraries/installed`	The installed libraries.
`GET /api/libraries/search?q=…`	Searches the Arduino library index.
`POST /api/libraries/install`	Body `{ "name" }`. Installs a library and its dependencies.

Requests can send X-Circzy-Language: en or id to choose the language of error messages.

Ready to try it?

Start simulating free