Getting Started

Everything you need to go from zero to a running sandbox.

1. Install the CLI

Download the latest release from GitHub Releases, then extract it: 

tar xzf sandcastle_*.tar.gz
sudo mv sandcastle /usr/local/bin/

2. Log in

Point the CLI at this server and authenticate via your browser:

sandcastle login https://hq.sandcastle.rocks

3. Enable Tailscale (recommended)

Each sandbox gets its own Tailscale IP so you can reach services directly — no port forwarding needed. 

# Interactive login — opens a browser URL to authenticate
sandcastle tailscale enable

# Or use an auth key for headless setups
sandcastle tailscale enable --auth-key tskey-auth-...

After authenticating, approve the advertised subnet routes in the Tailscale admin console.

4. Create a sandbox

Web UI — click the "Create Sandcastle" button on your dashboard to create a sandbox with all available options:

  • Name — unique identifier for your sandbox
  • Container Image — custom image or default
  • Snapshot — restore from an existing snapshot
  • Persistent Volume — keep /workspace across recreations
  • Mount Home — persistent home directory across all sandboxes
  • Data Path — mount user data (or subpath) to /data
  • Tailscale — connect to your Tailscale network
  • Temporary — auto-remove when you disconnect

Or use the CLI for quick creation:

Quick throwaway sandbox — deleted when you disconnect:

sandcastle create scratch --rm

Persistent sandbox — keeps your home directory and data across restarts:

sandcastle create my-dev --home --data
Tip: Set environment variables to make flags the default:
export SANDCASTLE_HOME=1 SANDCASTLE_DATA=. SANDCASTLE_RM=1

5. Connect

Two ways to get a shell:

# tmux session (reconnectable, auto-starts stopped sandboxes)
sandcastle connect my-dev

# Plain SSH
sandcastle ssh my-dev

6. Web terminal

Click the Terminal button on any running sandbox to open a browser-based shell. No SSH client needed — just a web browser.

How it works: Sandcastle spins up an ephemeral WeTTY container that auto-connects to your sandbox via SSH. The terminal session is protected by your existing login — no extra passwords required.

7. Manage sandboxes

sandcastle list              # Show all your sandboxes
sandcastle stop my-dev       # Stop a running sandbox
sandcastle start my-dev      # Start a stopped sandbox
sandcastle delete my-dev     # Permanently remove a sandbox

8. Custom domain routes

Expose services running inside your sandbox on custom domains with automatic TLS. Each sandbox can have multiple routes pointing to different ports: 

# Add a route — app.example.com → port 8080 (default) in sandbox "myapp"
sandcastle route add myapp app.example.com

# Add another route on a custom port
sandcastle route add myapp api.example.com 3000

# List all routes for a sandbox
sandcastle route list myapp

# Remove a specific route
sandcastle route delete myapp app.example.com

Point a DNS A/CNAME record at hq.sandcastle.rocks before adding the route. TLS certificates are provisioned automatically via Let's Encrypt.

9. Snapshots

Save and restore the full state of a sandbox:

# Create a snapshot
sandcastle snapshot create my-dev my-checkpoint

# List snapshots
sandcastle snapshot list

# Restore into a new sandbox
sandcastle create my-dev-v2 --snapshot my-checkpoint

Run sandcastle --help for the full command reference.