---
site: "zyx.tw"
title: "Carrel"
description: "Carrel: lab machines, asked for in words."
url: "https://www.zyx.tw/project/carrel"
---

# Carrel

Lab machines, asked for in words.

A carrel is the desk a library sets aside for one graduate student. Carrel gives every WinLab member their own corner of the lab's Proxmox VE cluster.

Members never touch Proxmox. They tell their agent what machine they need, and one MCP endpoint creates it and returns an SSH line.

From there the same endpoint gives the machine a domain, opens its ports and deploys its code on every push.

## Ask for a machine

The member says what the machine is for. The agent picks an image and a size, calls one tool and waits for the answer.

The answer comes when the machine is ready to use: it has booted, initialized and answered over SSH. In our own test that took 29 seconds. The agent writes the SSH alias into the member's config, so the next line just works.

```text
╭─ claude ───────────────────────────────────────────────────╮
│ > Open a VM on winlab for my SDN homework                  │
│                                                            │
│ * carrel  machine_create                                   │
│   name sdn-hw, image ubuntu-24.04                          │
│                                                            │
│   Ready: 2 vCPU, 2 GiB RAM, 20 GiB disk.                   │
│   SSH and initialization verified.                         │
│                                                            │
│   ssh sdn-hw.alice                                         │
╰────────────────────────────────────────────────────────────╯
```

Figure: A Claude Code session. The member asks for a VM for SDN homework. Carrel's machine\_create tool answers that the machine is ready with 2 vCPU, 2 GiB RAM and a 20 GiB disk, and gives the line ssh sdn-hw.alice.

1. Ask: The member says what the machine is for.
2. Call: The agent picks an image and a size, and calls one tool.
3. Ready: Carrel answers once the machine has booted and answered over SSH.
4. Connect: The alias is already in the member's SSH config.

## A desk of your own

Every member gets the same budget, and spends it as they like: 8 small machines, or one large one. A project group gets a second budget of its own.

A machine is a full VM (Debian or Ubuntu, with Docker and cloud-init) or a lighter container. Each member also has private networks, so machines talk to each other and to nobody else.

```text
╭──╮     ╭────╮     ╭────────╮     ╭────────────────╮
│  │     │    │     │        │     │                │
╰──╯     ╰────╯     ╰────────╯     ╰────────────────╯
 TINY     SMALL      MEDIUM         LARGE
 1 vCPU   2 vCPU     4 vCPU         8 vCPU
 1 GiB    2 GiB      8 GiB          16 GiB of memory
 10 GiB   20 GiB     40 GiB         80 GiB of disk
```

Figure: Four machine sizes drawn as boxes that double in width: tiny with 1 vCPU, 1 GiB of memory and 10 GiB of disk, small with 2, 2 and 20, medium with 4, 8 and 40, large with 8, 16 and 80.

1. Tiny: The default: enough for a bot or a small service.
2. Small: A prepared development machine starts here.
3. Medium: For builds, Docker stacks and databases.
4. Large: A member's whole CPU and memory budget in one machine.

- Machines: 8, with 8 vCPU, 16 GiB of memory and 100 GiB of disk between them.
- Names: 10 domains under the member's own name, with HTTPS.
- Ports: 10 public TCP or UDP ports.
- Networks: 4 private networks.
- Snapshots: 4 per machine.

## Publish and deploy

One call puts a service on the internet: a domain with a certificate, or a public port. Names outside the member's own and fixed ports go to an admin as a request.

A repository on GitHub links to a machine once. After that every push builds, switches the machine to the new release and watches its health for 60 seconds. A failing release rolls back by itself.

```text
╭──────────╮    ╭──────────╮    ╭──────────╮    ╭──────────╮
│   PUSH   │───>│  BUILD   │───>│  SWITCH  │───>│  CHECK   │
╰──────────╯    ╰──────────╯    ╰──────────╯    ╰──────────╯
 your repo       GitHub          the machine,    60 s of health
 on GitHub       Actions         new release     or roll back
```

Figure: Four steps in a row: git push to your repository, GitHub Actions builds, the machine switches to the new release, then 60 seconds of health checks decide whether to keep it or roll back.

1. Push: A push to the linked branch starts it.
2. Build: GitHub Actions builds the release.
3. Switch: A small daemon on the machine swaps to it.
4. Check: It watches health for 60 seconds, and goes back if the release fails.

## Keep, pause, put away

A machine does not have to run to be kept. What a member is not using stops counting against the cluster, and comes back as it was.

- Snapshot: Saves the disk, and rolls back to it.
- Pause: Holds a VM in memory and resumes it where it stopped.
- Freeze: Moves a stopped machine to backup storage. Thaw restores it with the same name and address.
- Resize: Changes CPU, memory and disk.
- VPN: A WireGuard profile into the member's private networks.
- Console: A link to the machine's screen in the browser, when SSH is not enough.

## How it is built

The control plane is one Go service. It serves MCP, signs members in with the lab's Keycloak account, checks every request against the quota and runs it as a durable job, so a dropped connection never loses a machine.

Under it are the cluster's own parts: Proxmox VE for machines, EVPN and VXLAN for each member's networks, and Caddy for HTTPS. A reconciler compares the cluster with the records every 5 minutes.

```text
 Claude Code, Codex
        │ MCP over HTTPS, signed in with Keycloak
 ╭──────┴───────────────────────────────────────────╮
 │ CARREL CONTROL PLANE                  Go, SQLite │
 │ MCP server    jobs    admission    quotas        │
 ╰──────┬─────────────────┬─────────────────┬───────╯
        │                 │                 │
 ╭──────┴───────╮ ╭───────┴──────╮ ╭────────┴─────╮
 │ PROXMOX VE   │ │ NETWORK      │ │ GATEWAY      │
 │ 4 nodes      │ │ EVPN, VXLAN  │ │ Caddy, HTTPS │
 │ VMs and CTs  │ │ WireGuard    │ │ TCP and UDP  │
 ╰──────────────╯ ╰──────────────╯ ╰──────────────╯
```

Figure: An agent reaches the Carrel control plane over MCP. The control plane, written in Go, drives three things: Proxmox VE with 4 nodes, the network (EVPN, VXLAN, WireGuard) and the gateway (Caddy for HTTPS, plus TCP and UDP ports).

1. Agent: The member's agent calls one MCP endpoint, signed in with the lab account.
2. Control plane: It checks the quota, then runs the request as a durable job.
3. Proxmox: Machines are VMs and containers on 4 Proxmox VE nodes.
4. Network: Each member's networks are their own, across every node.
5. Gateway: The gateway gives services a name, a certificate and public ports.

## In numbers

Carrel has run the lab's machines since October 2026. These are from its public status page on 2026-11-12.

- Cluster: 4 nodes with 160 CPU threads, 503 GiB of memory and 2,125 GiB of disk.
- In use: 30 machines for 11 accounts.
- Tools: 84 MCP tools: 66 for members and 18 for admins.

## Details

- Site: [https://carrel.winlab.tw](https://carrel.winlab.tw)
- Code: [https://github.com/NYCU-WinLab/carrel](https://github.com/NYCU-WinLab/carrel)
- Built with: Go, Proxmox VE, MCP, Keycloak, EVPN, Caddy

Back to [Project](https://www.zyx.tw/project.md).
