gb setup-local

Setup local development environment for *.genbox.local domains.

Synopsis


gb setup-local [options]

Description

Interactive wizard that sets up your local machine for local genbox development. This includes configuring a Caddy reverse proxy for *.genbox.local domains with automatic HTTPS certificates.

Options

Option	Description
`--status`	Show proxy status and active routes
`--stop`	Stop the local proxy
`--restart`	Restart the local proxy

Examples

Run Setup Wizard


gb setup-local


Local Development Environment Setup
────────────────────────────────────────────────────

Platform detected: macos

This wizard will set up:
  1. Caddy reverse proxy for *.genbox.local domains
  2. HTTPS certificate trust (optional, removes browser warnings)

Note: DNS entries are automatically added to /etc/hosts when creating genboxes.

✓ Docker is available
✓ Multipass is available (optional, for --vm mode)

Starting local proxy...
✓ Proxy started

HTTPS Certificates
────────────────────────────────────────────────────

The proxy uses Caddy's internal CA for automatic HTTPS.
? Do you want to trust the certificate system-wide? (requires sudo) Yes

Commands to Run
────────────────────────────────────────────────────

Please run the following commands to trust the certificate:

  # Run after creating your first local genbox (cert is generated on first use)
  docker cp genbox-local-proxy:/data/caddy/pki/authorities/local/root.crt /tmp/caddy-root.crt
  sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain /tmp/caddy-root.crt

────────────────────────────────────────────────────

Setup complete!

Configuration:
  DNS:       Automatic (/etc/hosts managed per genbox)
  HTTPS:     System-trusted (after running commands above)

Next steps:
  gb create -l  Create an isolated local genbox (Docker)
  gb create -l --vm  Create an isolated local genbox (Multipass VM)
  gb setup-local --status  Check proxy status

Check Proxy Status


gb setup-local --status


Local Proxy Status:

  Proxy:   Running
  Network: Created
  Routes:  2

Active Routes:
  https://my-app.genbox.local → my-app-container:3000
  https://api.my-app.genbox.local → my-app-container:4000

Stop Proxy


gb setup-local --stop


✓ Local proxy stopped

Restart Proxy


gb setup-local --restart


Proxy stopped
✓ Proxy restarted successfully

Platform-Specific Certificate Commands

macOS


docker cp genbox-local-proxy:/data/caddy/pki/authorities/local/root.crt /tmp/caddy-root.crt
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain /tmp/caddy-root.crt

Linux


docker cp genbox-local-proxy:/data/caddy/pki/authorities/local/root.crt /usr/local/share/ca-certificates/caddy-root.crt
sudo update-ca-certificates
# For Chrome/Firefox, you may need to import the cert manually in browser settings

Windows


docker cp genbox-local-proxy:/data/caddy/pki/authorities/local/root.crt %TEMP%\caddy-root.crt
certutil -addstore -f "ROOT" %TEMP%\caddy-root.crt

Requirements

Requirement	Status
Docker	Required
Multipass	Optional (for `--vm` mode)

How It Works

Caddy Proxy: Runs a Caddy reverse proxy in Docker (genbox-local-proxy)
DNS: Entries added to /etc/hosts when local genboxes are created
HTTPS: Caddy generates certificates from its internal CA
Routing: Routes *.genbox.local to appropriate containers

Notes

The proxy runs in the background as a Docker container
Certificate trust is optional but removes browser HTTPS warnings
DNS entries are managed automatically per genbox
Compatible with both Docker and Multipass isolation modes