Install the Roclet server

You can use Roclet in your browser without installing anything. Use the optional server when you want to open and save notebooks directly in a local project, alongside your modules and data files. It also downloads and caches GitHub release packages automatically, so you don’t have to download and upload bundles by hand.

This is useful for projects you manage with Git or edit with other tools. You keep the same interactive notebook interface, and code still runs in your browser. No Roc or Zig installation is needed.

1. Install

On macOS or Linux, run:

curl -fsSL https://ageron.github.io/roclet/install.sh -o /tmp/roclet-install.sh
sh /tmp/roclet-install.sh

On Windows, run in PowerShell:

Invoke-WebRequest https://ageron.github.io/roclet/install.ps1 -OutFile "$env:TEMP/roclet-install.ps1"
powershell -NoProfile -ExecutionPolicy Bypass -File "$env:TEMP/roclet-install.ps1"

The installer downloads the latest server release for your computer and verifies its checksum. No administrator access is needed. You can inspect the downloaded script before running it. Run it again to upgrade, or pass a version (sh /tmp/roclet-install.sh 0.2.0, or -Version 0.2.0 in PowerShell).

On macOS and Linux, follow the printed instruction to add ~/.local/bin to your PATH if needed. Windows adds the command to your user PATH; open a new terminal if necessary. Previous versions remain installed.

2. Start Roclet

Open a terminal in your notebook project and run:

roclet serve

You can also pass a project directory or notebook filename after serve. Open the private URL printed in your terminal (it starts with http://127.0.0.1:4173/?token=). Keep it private: it grants access to your project. Keep the terminal running; press Ctrl+C to stop the server. If the port is busy, use --port 4174. Run roclet --help for options and examples.

Optional HTTPS with Caddy

For use on the same computer, ordinary local HTTP is enough. For HTTPS, install Caddy and run it alongside Roclet. Caddy handles encryption and certificates; Roclet still requires its private token URL.

On this computer

Start Roclet (replace demos with your project directory):

roclet serve demos --public-url https://localhost:8443 --no-browser

In a second terminal, start Caddy:

caddy reverse-proxy --from localhost:8443 --to 127.0.0.1:4173

Open the HTTPS token URL printed by Roclet. Caddy may ask for an administrator password to trust its local certificate. If the browser still reports an untrusted certificate, follow Caddy’s local certificate instructions. Keep both processes running; Ctrl+C stops each one.

With a public domain

Point a domain such as notebooks.example.com to your server and allow incoming ports 80 and 443 through its firewall/router. Run both commands on that server:

roclet serve demos --public-url https://notebooks.example.com --no-browser
caddy reverse-proxy --from notebooks.example.com --to 127.0.0.1:4173

Run these in separate terminals, or configure services for continuous use. Caddy automatically obtains and renews a trusted certificate; it needs permission to bind ports 80 and 443. See Caddy’s HTTPS requirements. Only share Roclet’s token URL with people allowed to read and edit your project.

For private-network access without a public domain, use the server’s hostname or IP in both commands instead of localhost. Each connecting device must trust Caddy’s root certificate. Do not forward ports on your router for this setup.

--public-url accepts an HTTPS origin with an optional port, but no path, query, or fragment. It does not enable TLS inside Roclet. Keep Roclet bound to 127.0.0.1 (the default), with Caddy on the same computer. If you change Roclet’s --port, change Caddy’s --to address to match. The token changes whenever Roclet restarts.

The server serves the browser app; it does not run notebooks headlessly. For development and the separate headless runner, see the source build instructions.