# Torollo: a local Docker lab where every architecture node is a real container

> Torollo is an MIT-licensed TypeScript tool that turns a canvas into a live Docker environment and grades guided roadmaps against the running system. It is a strong fit for engineers who want to learn system design by breaking real things, and a poor fit for anyone without a working Docker daemon.

**Derssa/Torollo** — Torollo is an open-source interactive visual playground designed to learn system design and networking, all locally.

- Repository: https://github.com/Derssa/Torollo
- Website: torollo.app
- Stars: 447 · Forks: 48
- Language: TypeScript
- License: MIT
- Published: 2026-09-17 · Updated: 2026-09-17 · Language: en
- Canonical page: https://hysenlabs.com/projects/derssa-torollo

## The problem Torollo targets: diagrams that never fail

Most system design practice happens on a whiteboard or in a drawing tool. You place a load balancer, two app servers and a database, draw arrows between them, and the diagram looks correct. Nothing in that exercise tells you whether the rules you imagined actually hold. Torollo's README makes this the whole pitch: "Drawing boxes is easy; plenty of tools do that." The difference it claims is that a link on the canvas becomes a real firewall rule, a database node becomes a real database, and a roadmap step is checked by probing live containers rather than by comparing your answer to a picture.

The audience is narrower than the tagline suggests. This is for backend and DevOps learners who already know what a subnet is, and for engineers who want to rehearse a three-tier deployment without provisioning cloud resources. It is not a course platform and it does not explain concepts for you. The repository ships a roadmaps directory, and the README points new users at a single named roadmap, "Deploy a resilient three-tier app", which walks from one web server to a load-balanced, firewalled, database-backed architecture in ten validated steps. That is the intended first contact, not an empty canvas.

## How the canvas maps to Docker and iptables

The architecture is three pieces: a TypeScript backend that talks to the Docker daemon through dockerode, a frontend served by nginx in production, and a set of node images Torollo prepares on first run. The backend is the only part that touches the host. In the Compose setup it mounts the host Docker socket, and the README states plainly that this mount is what gives the backend control of the daemon. The frontend never talks to Docker; it reaches the backend through the proxy on port 23232.

The Compose file confirms the split. The backend container exposes 23233 internally and publishes nothing on its own; only the development override publishes that port. The frontend publishes 23232 bound to TOROLLO_BIND_ADDRESS, which defaults to 127.0.0.1. A healthcheck hits /health on the backend and /healthz on the frontend, and the frontend waits for the backend to report healthy before it starts.

Validation is where the design gets interesting. A roadmap step is graded against container state, so the check can fail for a reason the tool reports. The README's demo caption describes exactly that loop: the database accepts 5432 from anywhere, Validate returns a failure with the reason, the firewall is tightened to the two app servers, Validate passes, and the roadmap completes. The networking topics attached to the repository, iptables and VPC among them, match that mechanism. Cross-subnet security groups and NAT need host iptables rules, which is why rootless Docker is flagged as a degraded mode rather than a supported one.

## Installing Torollo and finishing your first roadmap step

The fastest path needs no clone and no permanent install. Docker must be running first, then a single npx command starts the CLI, which downloads node images on the first run, reports which image it is on, and opens the browser only once the backend answers.

```bash
npx torollo start
```

If that command exits with an error, the same package ships a diagnostic command. It checks the active Node.js version, the Docker CLI, access to the daemon Torollo will use, the default frontend and backend ports, available disk space, and the installed version. Blocking problems produce a non-zero exit code; an occupied default port is only a warning, because Torollo can pick the next free one.

```bash
npx torollo doctor
```

For a report you can paste into a GitHub issue, the CLI takes a JSON flag. Home-directory paths are rewritten to ~ in that output, which matters if you are sharing logs.

```bash
npx torollo doctor --json
```

If you prefer a container stack, copy the example environment file and bring up Compose. The defaults target localhost, so the copy is optional.

```bash
cp .env.example .env
docker compose up --build -d
docker compose logs -f
```

Open http://localhost:23232 and choose Start learning on the first-run screen. The Learning tab in the left rail brings the catalogue back later. Progress and projects live in the torollo-data named volume; docker compose down keeps them, and docker compose down -v deletes them permanently. Expect the first boot to take several minutes while node images are prepared.

## Where Torollo breaks: rootless Docker, ports and trust

The clearest limitation is documented in the CLI's own error table. Under rootless Docker, containers work, but subnets, NAT and cross-subnet security groups need host iptables rules that a rootless daemon cannot apply. The README's fix is to use a rootful daemon for the full network engine. That rules out a meaningful share of Linux desktop setups and most hardened environments, and it is not a bug you can work around from inside the app.

The second constraint is trust. Torollo has no authentication, and the backend holds the host Docker socket. Anyone who can reach the published port inherits control of the daemon. The default bind address of 127.0.0.1 is what keeps the stack private; the README is explicit that TOROLLO_ALLOWED_ORIGINS does not, since it only controls browser origins. Changing TOROLLO_BIND_ADDRESS to expose the lab on a LAN is therefore a decision with real consequences, not a convenience toggle.

Third, this is a single-user tool by design. There is no account model, no per-user isolation, and no hosted option described in the README. If you need a shared classroom environment, Torollo is the wrong shape. The same goes for anyone who wants a static diagramming tool: if you never intend to run the topology, the container machinery is pure overhead.

## Torollo compared with container-based lab tools

The nearest category is the container lab tool that spins up a topology from a declarative file, most commonly Containerlab. The difference is direction of travel. Containerlab starts from a topology definition you write and gives you the running network; you inspect it with your own tools and you decide whether the result is correct. Torollo starts from a canvas and a roadmap, and the application itself decides whether your configuration satisfies the step, by probing the containers it created. One is a provisioning tool with a CLI surface; the other is a graded exercise with a GUI.

That difference has costs. Containerlab composes with existing CI and scripting because the topology is a file. Torollo's grading logic lives in the application and in the roadmaps shipped in the repository, so you are working inside its catalogue unless you write your own roadmap content. Packet Tracer, which the README invokes in its own tagline, is the other reference point, and the contrast there is simulation versus reality: Packet Tracer models devices, while Torollo runs actual containers and actual firewall rules on your machine. The trade is fidelity for blast radius, which is exactly why the socket warning exists.

## Maintenance, licence and the cost of upgrading

The repository is not archived, and the last push was on 2026-09-14, three days before the date of this review. Release cadence in the published history is roughly monthly: v1.2.3 on 2026-07-29 added a RabbitMQ node, security hardening and English/French i18n; v1.2.4 on 2026-08-26 added the home shell and catalogue, dark mode, local roadmap imports and self-hosting support; v1.2.5 on 2026-09-10 added the Environment Doctor, CLI diagnostics and roadmap solution debriefs. The version in package.json is 1.2.5, and the engines field requires Node.js 18 or newer.

Upgrade cost is low for the npm path, since npx fetches the published package and the CLI reports its own version. The Compose path is heavier: images are built locally from the Dockerfile, which pins node:20.20.2-bookworm-slim and nginx:1.28.3-alpine as build arguments, and the data volume survives rebuilds unless you pass -v. Changing dependencies requires a rebuild, as the README notes for the development override.

The licence is MIT, which permits commercial and private use with the copyright notice retained. Torollo also ships a CLA.md and a SECURITY.md at the repository root. The README does not describe how security reports are handled, so treat SECURITY.md as the place to look rather than assuming a disclosure process. This is not legal advice; read the LICENSE file itself if the terms matter to your organisation.

## Conclusion

Adopt Torollo if you learn best by breaking a real system and you already run a rootful Docker daemon on your own machine. Skip it if you need multi-user access, authentication, or a hosted service, because the project has none of those and the README is explicit that the socket mount hands host Docker control to the backend. Before you invest time in a roadmap, run npx torollo doctor and confirm the rootful daemon, the Docker socket path, and the free default ports 23232 and 23233.

## FAQ

### Does Torollo need Docker installed to run?

Yes. The README states that Docker must be running before npx torollo start, and the CLI's environment check verifies the Docker CLI and access to the same daemon the backend will use. The Compose path also requires Docker Engine or Docker Desktop with the daemon running.

### Can I run Torollo with rootless Docker?

Containers work, but the README's diagnostic table says subnets, NAT and cross-subnet security groups need host iptables rules that a rootless daemon cannot apply. The recommended fix is to use a rootful daemon for the full network engine.

### Which port does Torollo use by default?

The frontend is published on 23232 and the backend listens on 23233, which the Compose file only publishes through the development override. An occupied default port is reported as a warning rather than a blocking error, because Torollo can select the next available port.

## Sources

- [Derssa/Torollo on GitHub](https://github.com/Derssa/Torollo)
- [Issues](https://github.com/Derssa/Torollo/issues)
- [License: MIT](https://github.com/Derssa/Torollo/blob/main/LICENSE)
- [README](https://github.com/Derssa/Torollo/blob/main/README.md)
- [Releases](https://github.com/Derssa/Torollo/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/derssa-torollo