Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.stacyide.xyz/llms.txt

Use this file to discover all available pages before exploring further.

​
Production Live Preview Architecture for StacyVM (Implemented)

​
Objective

To implement a production-grade, highly scalable “Live Preview” system for 100+ concurrent users entirely powered by Traefik. This design supports seamless local development (*.localhost) and production environments (*.stacyide.xyz), using Traefik’s native dynamic discovery.

​
Status: Implemented (Phase 1 & 2)

StacyVM now supports automatic Traefik integration for the Docker provider. Preview URLs can be generated via the SDK using sandbox.getPreviewUrl(port).

​
Background & Motivation

StacyVM sandboxes need a way to expose internal web servers (e.g., Vite on 5173, Next.js on 3000) to external users. Traefik is an industry-standard dynamic reverse proxy that integrates natively with Docker. By using Traefik, we eliminate custom proxy code and leverage robust features like automatic SSL (Let’s Encrypt), WebSocket support, and zero-downtime configuration updates.

​
Architecture

The architecture adapts based on the StacyVM provider (Docker vs. Firecracker).

​
Phase 1: Native Docker Integration (Done)

For the Docker provider, Traefik discovers sandboxes automatically by reading the Docker daemon socket (/var/run/docker.sock). 1. StacyVM Core Modification (Go): internal/providers/docker.go injects Traefik labels during Spawn. These labels define the routing rules and the internal target port. 
// Example injected labels:
Labels: map[string]string{
    "traefik.enable": "true",
    // Route for port 3000
    fmt.Sprintf("traefik.http.routers.%s-3000.rule", id): fmt.Sprintf("Host(`3000-%s.%s`)", id, previewDomain),
    fmt.Sprintf("traefik.http.services.%s-3000.loadbalancer.server.port", id): "3000",
}
2. Traefik Deployment: Traefik runs as a container with access to /var/run/docker.sock. It instantly detects new sandboxes and updates its routing table.

​
Phase 2: Workflow & Domain Configuration (Done)

A. Local Development (Laptop)
  • Domain: Set StacyVM preview_domain to localhost in stacyvm.yaml (or via ENV).
  • Setup: Run docker compose up -d in the root of the project to start both StacyVM and Traefik together.
  • Access: Visit http://3000-sb-123.localhost. The browser resolves *.localhost to your machine, Traefik intercepts it, and forwards it to the sandbox container.
B. Production Export (*.stacyide.xyz)
  • Domain: Set StacyVM preview_domain to stacyide.xyz in stacyvm.yaml.
  • Setup: Deploy Traefik on public ports 80/443. Configure Traefik with an ACME resolver for Wildcard SSL.
  • DNS: Point a Wildcard A record (*.stacyide.xyz) to the server IP.
  • Access: Users visit https://3000-sb-123.stacyide.xyz. Traefik handles SSL termination and routes traffic to the internal sandbox IP.

​
Phase 3: Supporting Firecracker (Pending)

Firecracker microVMs are not Docker containers and cannot be discovered via the Docker socket.
  1. IP Exposure: Modify the Firecracker provider to capture and return the guest’s internal IP address.
  2. Dynamic Configuration: When a Firecracker sandbox is spawned, the StacyVM orchestrator pushes a routing rule to Traefik via its HTTP API or a Key-Value store (Redis/Etcd): Rule: Host("3000-sb-123.stacyide.xyz") -> Forward: http://172.17.0.5:3000

​
Implementation Details

​
1. API & Model Updates

  • Added PreviewDomain to orchestrator.Sandbox and orchestrator.SandboxInfo.
  • Docker provider generates a deterministic name/ID for containers to make routing predictable.

​
2. Configuration

  • Added preview_domain to server block in stacyvm.yaml (defaults to localhost).

​
3. Frontend / SDK

  • Exposed sandbox.getPreviewUrl(port) in JS/TS SDK.
  • Exposed sandbox.get_preview_url(port) in Python SDK.