Skip to content

Dev Machines Setup

Dev Machines are an opt-in subsystem, included in releases since v0.1.13, and remain disabled in the default five-service deployment. Enabling them adds a machine gateway, a Docker manager and per-machine container runtimes. Read TECHNICAL.md in the repository before enabling the subsystem.

Prerequisites

Machine workloads run on a separate registrable domain — not a sibling subdomain of the main application — with wildcard DNS pointing to the host. Production wildcard TLS requires a custom Caddy build with a DNS-01 module or an operator-provided wildcard certificate; stock Caddy cannot issue wildcard certificates over HTTP-01. The Docker data root must use XFS project quotas.

  • DEV_MACHINE_DOMAIN on a separate registrable domain
  • Wildcard DNS for *.DEV_MACHINE_DOMAIN
  • Wildcard TLS via DNS-01 Caddy build or an imported certificate
  • Docker data root on XFS mounted with pquota or prjquota
  • A GitHub App with scoped write permissions for agent push/PR workflows

Required configuration

When DEV_MACHINES_ENABLED=true, the backend validates the machine domain, frontend URL, encryption key, ingestion URL and related runtime settings. The Compose provisioning prerequisite separately requires the gateway database password. FRONTEND_URL must be the exact public Kuayle origin; the gateway requires the native terminal WebSocket Origin header to match it exactly.

  • DEV_MACHINES_ENABLED=true
  • DEV_MACHINE_ENCRYPTION_KEY — independent random value, at least 32 characters
  • DEV_MACHINE_INGEST_URL — public HTTPS collector ingestion URL
  • DEV_MACHINE_GATEWAY_DB_PASSWORD — independent credential for the restricted gateway role
  • FRONTEND_URL — exact public origin, scheme included

Build and start

Runtime images are built locally, migrations applied, and the optional control plane started through Compose profiles.

  • docker compose --profile dev-machine-images build
  • docker compose exec backend /app/server migrate up
  • docker compose --profile dev-machines run --rm machine-gateway-db-provision
  • docker compose --profile dev-machines up -d

Security model

The Machine Manager is the only Dev Machines runtime component with Docker socket access; the gateway is unprivileged. The separately optional system updater also mounts the socket when enabled. Machine services publish no host ports and run on isolated per-machine networks with an egress policy proxy. Docker hardening reduces risk but is not hostile multi-tenant isolation — the subsystem targets trusted self-hosted workspaces.

  • One-time launch tickets and host-restricted machine sessions
  • AES-256-GCM encrypted secrets delivered through tmpfs
  • Egress proxy blocks private address ranges; optional domain allowlists
  • Workspace policies control concurrency, runtime, providers and repositories

Private teams

Dev Machines are disabled in workspaces that use private teams, and the restriction remains if those teams are later made public or deleted. Remove existing development machines, environments and development defaults before enabling team privacy.

  • Tear down machines and environments before enabling private teams
  • The restriction is workspace-wide and persistent

Review Kuayle before you deploy it

Inspect the Apache 2.0 source, then follow the Docker Compose guide to run an instance on your infrastructure.

View source on GitHub Deployment guide