Documentation & CLI Reference

Welcome to the Tom Labs documentation. Below is the complete reference for the orchestrator CLI.

🚀 Tom Labs Orchestrator CLI (labsctl)

The labsctl orchestrator is the engine that drives Tom Labs. It handles container lifecycles, user provisioning, WireGuard mesh networking, and log streaming.

Core Commands
# Build a lab image
labsctl build essentials:lab --no-cache

# Deploy an instance for a user
labsctl deploy essentials:lab --user=sathish --hash=HASH

# Stop, Start, or Delete an instance
labsctl stop essentials --hash=HASH
labsctl start essentials --hash=HASH
labsctl remove essentials --hash=HASH

# Enter the container shell interactively
labsctl shell essentials --hash=HASH

# Live log stream to WebSocket
labsctl stream --key=logs.HASH

# User & Validation Utilities
labsctl syncuser sathish             # Fix permissions
labsctl ensure-codeserver --hash=HASH # Check VS Code status
labsctl list-images                  # List all built labs
labsctl get-workers                  # Check active background workers
Challenge Commands (CTF Labs)
# Build a CTF challenge image
labsctl challenge build sql_injection:lab

# Deploy a CTF challenge lab
labsctl challenge deploy --user=sathish --hash=HASH --challenge=sql_injection

# Manage CTF challenge lifecycles
labsctl challenge stop --hash=HASH
labsctl challenge start --hash=HASH
labsctl challenge remove --hash=HASH

# Generate AI Quiz Content
labsctl quiz generate --topic=ID --subtopic=ID --diff=hard

Feature Deep-Dives

1. Automated Domain Routing (Traefik)

Tom Labs automatically provisions subdomains for every lab using Traefik. When you deploy a lab, labsctl writes a dynamic configuration file (e.g., HASH.yml) that Traefik instantly detects without requiring a restart. Let's Encrypt SSL certificates are automatically fetched, ensuring all traffic is encrypted.

2. The WireGuard VPN Overlay

Security is our priority. Every deployed lab container is connected to an isolated Docker network, but user access is facilitated through a WireGuard VPN mesh. When a user requests a lab, the system assigns a dedicated 172.30.0.X virtual IP.

How to Connect & SSH
# 1. Download your WireGuard config from the dashboard
# 2. Connect via your WireGuard client
# 3. SSH directly into your container using the virtual IP!
$ ssh user@172.30.0.42

# No exposed public ports. Complete isolation.

3. Pre-Configured Bundled Services

A lab is not just a terminal. Tom Labs bundles enterprise-grade services into the infrastructure so students can learn on real tech stacks without spending hours configuring them:

  • MongoDB 8.0: Primary database for user auth and state.
  • RabbitMQ: Message broker handling deployment jobs and WebSocket log streaming.
  • MySQL & Redis: Pre-configured in the `essentials` labs for backend development.
  • Adminer: Built-in lightweight database management tool.

4. AI Quiz Engine

Tom Labs integrates directly with Gemini and Local LLMs to generate on-the-fly technical quizzes. Using the orchestrator, you can dynamically test student knowledge on any tech stack.

Quiz Generation
$ labsctl quiz generate --topic=Docker --diff=hard
[Generating Quiz via RabbitMQ AI Worker...]
Q1: How do you bypass the PID 1 zombie reaping issue?
A) Use init=true flag
B) Ignore it