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://hase.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. Web browser

Click the Browser button on any running sandbox to access Google Chrome with a graphical desktop environment. Perfect for browser automation, visual testing, or running GUI applications.

How it works: Each sandbox includes Google Chrome, Xvfb (virtual X server), and x11vnc. Clicking Browser launches a noVNC container that connects to the sandbox's VNC server, giving you a full graphical browser in your web browser.
Chrome profile persistence: Go to Settings → Browser to enable Chrome profile persistence. When enabled, your Chrome extensions, bookmarks, and settings are saved and persist across sandbox recreations. If you use Mount Home, profiles are stored in ~/.config/google-chrome alongside all your other home directory files. Without Mount Home, profiles are stored separately in a dedicated directory.

8. 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

9. 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 hase.sandcastle.rocks before adding the route. TLS certificates are provisioned automatically via Let's Encrypt.

10. 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

11. User settings

Click Settings in the navbar to manage your account preferences:

  • Profile — Update your email address and change your password
  • Tailscale — View connection status and toggle auto-connect for new sandboxes
  • Browser — Toggle Chrome profile persistence across sandbox recreations
  • API Token — Generate or revoke your API token for CLI authentication
Using API tokens: After generating a token in Settings, configure the CLI with
sandcastle config set-token and paste your token when prompted.

Run sandcastle --help for the full command reference.