dev-server-sandbox_skill

Overview

This skill runs multiple isolated mux dev-server instances by creating temporary MUX_ROOT directories and selecting free ports so you can run parallel development servers. It wraps the existing make dev-server flow with environment overrides and sandboxing to avoid lockfile conflicts. The tool is lightweight and designed for local, agentic development workflows.

How this skill works

The skill creates a fresh temporary MUX_ROOT and seeds it with optional config files (providers.jsonc and config.json) from a specified source root. It finds unused BACKEND_PORT and VITE_PORT values, sets VITE_ALLOWED_HOSTS=all, and launches make dev-server with those environment variables. Secrets are intentionally not copied into the sandbox; you can keep the sandbox directory for debugging or pin ports manually.

When to use it

• You need to run multiple dev-server instances in parallel on one machine.
• Testing different agents or worktrees without changing global dev state.
• Running isolated experiments that require unique backend or Vite ports.
• Using port-forwarding or subdomain mappings that require VITE_ALLOWED_HOSTS=all.
• Debugging a single instance without affecting your primary MUX_ROOT.

Best practices

• Seed from an explicit SEED_MUX_ROOT to control which configs are copied into the sandbox.
• Never put secrets.json in seed directories; the sandbox does not copy secrets by design.
• Use KEEP_SANDBOX=1 when you need to inspect logs, config, or provider files after shutdown.
• Pin BACKEND_PORT and VITE_PORT only when coordinating with other services; ensure port values differ between instances.
• Use MAKE override (e.g., MAKE=gmake) if your environment requires a specific make executable.

Example use cases

• Start two independent dev-server instances for testing an agent change in one and a control in the other.
• Run a sandboxed instance from a git worktree to validate feature branches without touching your main dev server.
• Spin up temporary servers for CI or local integration testing that require unique ports.
• Troubleshoot provider config differences by seeding from alternate MUX_ROOTs and keeping the sandbox for inspection.