switchyard-runner

Runs Switchyard's lesson sandboxes on your own Docker and pairs them with the course in your browser.

Nothing you do in a lesson runs on anyone else's machine. The runner starts containers with your Docker, listens on 127.0.0.1 unless you put it on a network, and answers the page that knows the pairing code it prints. Stopping it removes the sandbox.

Use

You need Bun 1.3 or newer and a running Docker.

bunx switchyard-runner --origin https://switchyard-gentleduck.vercel.app

It prints a pairing link and a code. Open the link, or paste the code into the course's Sandbox page, and the terminal there is a shell in the sandbox.

Running the course locally instead? bunx switchyard-runner on its own — localhost is always accepted, so no --origin is needed.

Options

| | | | --- | --- | | --port <n> | port to listen on (default 4839) | | --host <address> | address to listen on (default 127.0.0.1, or every network when an --origin is this machine's own address on one). 0.0.0.0 listens on every network the machine is on; see Running it on another machine | | --url <url> | the address browsers use for the runner, http(s)://host[:port], when a proxy or a tunnel stands in front of it, or a VM's public address is not one of its own. Default: the --host address; with 0.0.0.0, the --origin's address when that is this machine, else its first network address | | --tls-cert <file>, --tls-key <file> | serve https and wss from these PEM files; both or neither | | --origin <url> | also accept the app from this origin, repeatable | | --app-url <url> | app address used in the pairing link (default: the --origin, if exactly one is given, else http://localhost:5173) | | --memory <MiB> | memory per sandbox node (default: the profile's) | | --cpus <n> | CPUs per sandbox node (default: the profile's) | | --ports <list> | node 1 ports published on the --host address, e.g. 8080-8089,9090 | | --idle <minutes> | remove the sandbox after this long with no app connected (default 60, 0 = never) | | --new-token | forget the saved pairing code and make a new one | | -v, --version | print the version and exit |

SWITCHYARD_HUB_USERNAME and SWITCHYARD_HUB_TOKEN give the sandbox's image cache a Docker Hub account, which raises the pull limit above the anonymous one.

Running it on another machine

The runner and its Docker can be on one machine and the course on another: a desktop that runs the sandbox and a laptop that shows the lessons, or a VM online. The pair link the runner prints names the runner's address, and the page asks once before it pairs with a runner that is not on its own machine.

Whoever has the pairing code can use the sandbox. Without TLS, the code, your terminals and the editor cross the network unencrypted, and the runner says so when it starts. That is fine on a home network you trust. Anywhere else, give it TLS or use a tunnel.

On the same network

bunx switchyard-runner --host 0.0.0.0 --origin http://192.168.1.20:5173

--host 0.0.0.0 listens on every network the machine is on, and --origin is the course's address as the other machine opens it. Open the pair link the runner prints in that machine's browser, or open the course there and paste the pairing code: a page served over http from another machine of the network looks for the runner on that machine first.

When the course is served from the runner's own machine, as bun run dev serves it, --origin with that machine's address is enough: an origin at one of the machine's own network addresses puts the runner on every network by itself, and the start-up output says so. --host 127.0.0.1 keeps it on this machine alone.

• macOS may ask whether the runner may accept incoming connections. Allow it.
• A course opened over https cannot reach a plain http runner on another machine: the browser blocks it as mixed content, and the page says so. Open the course over http, or give the runner TLS with a certificate that browser trusts.
• Lesson ports are published on the same address, so http://192.168.1.20:8080 reaches node 1's port 8080 from the other machine.

On a VM online, with HTTPS

The VM needs a name, such as sandbox.example.com, and a certificate for it. Either the runner serves TLS itself, from files its user can read:

bunx switchyard-runner --host 0.0.0.0 --url https://sandbox.example.com:4839 \
  --tls-cert ~/certs/fullchain.pem --tls-key ~/certs/privkey.pem \
  --origin https://switchyard-gentleduck.vercel.app

or a proxy such as Caddy gets the certificate and stands in front of a runner left on 127.0.0.1:

sandbox.example.com {
	reverse_proxy 127.0.0.1:4839
}

bunx switchyard-runner --url https://sandbox.example.com --origin https://switchyard-gentleduck.vercel.app

With --host 0.0.0.0 on a VM, the lesson ports are open to the whole internet. Behind the proxy they are on the VM's 127.0.0.1; reach them with an SSH tunnel, as below.

Through an SSH tunnel

The runner stays on the VM's 127.0.0.1 and the tunnel brings it to yours:

ssh -L 4839:127.0.0.1:4839 -L 8080:127.0.0.1:8080 you@vm

Start bunx switchyard-runner --origin <the course's address> on the VM and open the link it prints. To your browser the runner is on 127.0.0.1:4839, so this works with the course over https too, and nothing but SSH crosses the network. Add an -L for each lesson port you want.

What it starts

A sandbox is one or more Alpine containers, each running its own Docker daemon, built from a profile in sandboxes/ that ships inside this package. Every node has its own filesystem and network, so nothing a lesson does touches your own containers, images or files.

MIT licensed. Source: wildduck2/switchyard.