docs: sync provider and vnc docs (#26)
This commit is contained in:
Peter Steinberger
GitHub
parent
27f3b1c140
commit
237ef3a64d
18
README.md
18
README.md
@ -6,13 +6,13 @@
|
||||
|
||||
**Warm a box, sync the diff, run the suite.**
|
||||
|
||||
Crabbox is an open-source remote testbox runner for maintainers and AI agents. Lease a fast Linux machine on owned cloud capacity, or point at an existing macOS/Windows SSH host, sync your dirty checkout, run a command remotely, stream output, and release. Local edit-save-run loop, cloud-grade compute.
|
||||
Crabbox is an open-source remote testbox runner for maintainers and AI agents. Lease fast managed cloud capacity, or point at an existing SSH host, sync your dirty checkout, run a command remotely, stream output, and release. Local edit-save-run loop, cloud-grade compute.
|
||||
|
||||
```sh
|
||||
crabbox run -- pnpm test
|
||||
```
|
||||
|
||||
Behind that single command: a Go CLI on your laptop, a Cloudflare Worker broker that owns provider credentials and lease state, and a vanilla Ubuntu runner on Hetzner Cloud or AWS EC2 Spot. Crabbox can also wrap Blacksmith Testboxes when you choose `provider: blacksmith-testbox`, or use `provider: ssh` for existing macOS and Windows targets.
|
||||
Behind that single command: a Go CLI on your laptop, a Cloudflare Worker broker that owns provider credentials and lease state, and a managed runner on Hetzner Cloud or AWS EC2. Crabbox can also wrap Blacksmith Testboxes when you choose `provider: blacksmith-testbox`, or use `provider: ssh` for existing macOS and Windows targets.
|
||||
|
||||
---
|
||||
|
||||
@ -55,7 +55,7 @@ Every lease has a stable `cbx_...` ID and a friendly crustacean slug (`blue-lobs
|
||||
```text
|
||||
your laptop Cloudflare Worker cloud provider
|
||||
------------- ------------------ --------------
|
||||
crabbox CLI -- HTTPS --> Fleet Durable Object --> Hetzner / AWS Spot
|
||||
crabbox CLI -- HTTPS --> Fleet Durable Object --> Hetzner / AWS EC2
|
||||
| lease + cost state |
|
||||
| |
|
||||
+------------ SSH + rsync to leased runner <--------------+
|
||||
@ -75,7 +75,7 @@ For the full mental model, see [How Crabbox Works](docs/how-it-works.md). For th
|
||||
- **Run observability.** Every coordinator-backed run gets an early `run_...` handle. Use `crabbox attach <run-id>` while it is active, `crabbox events <run-id> --after <seq> --limit <n>` for durable lifecycle/output events, and `crabbox logs <run-id>` for retained output after completion.
|
||||
- **Stable timing records.** `--timing-json` on `run`, `warmup`, and `actions hydrate` gives scripts one machine-readable sync/command/total timing schema across AWS, Hetzner, and Blacksmith Testboxes.
|
||||
- **Local-first sync.** No clean-checkout requirement. Tracked + nonignored files only, fingerprint skip on no-op runs, sanity checks against suspicious mass deletions, optional shallow base-ref hydration for changed-test workflows.
|
||||
- **Brokered cloud.** Maintainers and agents share infra without sharing provider tokens. Hetzner and AWS EC2 Spot are first-class Linux providers; AWS also owns managed Windows and EC2 Mac targets. Providers fall back across compatible instance families when capacity or quota rejects a request.
|
||||
- **Brokered cloud.** Maintainers and agents share infra without sharing provider tokens. Hetzner and AWS EC2 are first-class managed providers; AWS also owns managed Windows and EC2 Mac targets. Linux defaults to Spot unless capacity config says otherwise. Providers fall back across compatible instance families when capacity or quota rejects a request.
|
||||
- **macOS and Windows static hosts.** `provider: ssh` reuses existing machines; it does not create macOS or Windows Crabbox boxes. macOS and Windows WSL2 use the POSIX rsync path; native Windows uses PowerShell plus tar archive sync.
|
||||
- **Blacksmith Testbox wrapper.** Set `provider: blacksmith-testbox` to delegate warmup/run/list/status/stop to the Blacksmith CLI while Crabbox keeps local slugs, repo claims, timing summaries, and config conventions.
|
||||
- **Trusted AWS images.** Operators can create AMIs from active brokered AWS leases and promote a known-good image as the coordinator default.
|
||||
@ -96,20 +96,22 @@ Hetzner standard ccx33, cpx62, cx53
|
||||
large ccx53, ccx43, cpx62, cx53
|
||||
beast ccx63, ccx53, ccx43, cpx62, cx53
|
||||
|
||||
AWS Spot standard c7a/c7i/m7a/m7i.8xlarge family
|
||||
AWS Linux standard c7a/c7i/m7a/m7i.8xlarge family
|
||||
fast …16xlarge family
|
||||
large …24xlarge family
|
||||
beast …48xlarge family, falling back to 32x/24x/16x
|
||||
|
||||
AWS Win standard m7i.large, m7a.large, t3.large
|
||||
fast m7i.2xlarge, m7a.2xlarge, m7i.xlarge
|
||||
large m7i.4xlarge, m7a.4xlarge, m7i.2xlarge
|
||||
fast m7i.xlarge, m7a.xlarge, t3.xlarge
|
||||
large m7i.2xlarge, m7a.2xlarge, t3.2xlarge
|
||||
beast m7i.4xlarge, m7a.4xlarge, m7i.2xlarge
|
||||
|
||||
AWS WSL2 standard m8i.large, m8i-flex.large, c8i.large, r8i.large
|
||||
fast m8i.xlarge, m8i-flex.xlarge, c8i.xlarge, r8i.xlarge
|
||||
large m8i.2xlarge, m8i-flex.2xlarge, c8i.2xlarge, r8i.2xlarge
|
||||
beast m8i.4xlarge, m8i-flex.4xlarge, c8i.4xlarge, r8i.4xlarge
|
||||
beast m8i.4xlarge, m8i-flex.4xlarge, c8i.4xlarge, r8i.4xlarge, m8i.2xlarge
|
||||
|
||||
AWS macOS all mac2.metal unless --type is set
|
||||
```
|
||||
|
||||
Override with `--type` or `CRABBOX_SERVER_TYPE` for a specific instance.
|
||||
|
||||
@ -6,20 +6,20 @@
|
||||
|
||||
Crabbox is a shared remote testbox system for OpenClaw maintainers and AI agents. The goal is to keep the local developer story unchanged - edit, save, run - while moving compute and tests onto owned cloud capacity.
|
||||
|
||||
A `crabbox run` command leases a brokered Linux machine or reuses a static macOS/Windows SSH host, syncs your tracked and nonignored local files, executes the command remotely, streams stdout and stderr back, and releases or unclaims the target. Behind the scenes a small Cloudflare-hosted broker owns cloud provider credentials, lease state, cleanup, usage, and cost guardrails so individual machines and CLIs never need to.
|
||||
A `crabbox run` command leases a brokered cloud machine or reuses a static SSH host, syncs your tracked and nonignored local files, executes the command remotely, streams stdout and stderr back, and releases or unclaims the target. Behind the scenes a small Cloudflare-hosted broker owns cloud provider credentials, lease state, cleanup, usage, and cost guardrails so individual machines and CLIs never need to.
|
||||
|
||||
## How it fits together
|
||||
|
||||
```text
|
||||
your laptop Cloudflare Worker cloud provider
|
||||
------------- ------------------ --------------
|
||||
crabbox CLI -- HTTPS --> Fleet Durable Object --> Hetzner / AWS Spot
|
||||
crabbox CLI -- HTTPS --> Fleet Durable Object --> Hetzner / AWS EC2
|
||||
| lease + cost state |
|
||||
| |
|
||||
+------------ SSH + rsync to leased runner <--------------+
|
||||
```
|
||||
|
||||
The CLI is a Go binary. The broker is a Cloudflare Worker plus a single Durable Object. Brokered runners are vanilla Ubuntu boxes prepared by cloud-init with SSH, Git, rsync, curl, jq, and `/work/crabbox`. Static macOS and Windows targets are existing SSH hosts selected with `provider: ssh`. Project runtimes come from Actions hydration or repo-owned setup. Runners hold no broker credentials - they are leaf nodes.
|
||||
The CLI is a Go binary. The broker is a Cloudflare Worker plus a single Durable Object. Brokered Linux runners are vanilla Ubuntu boxes prepared by cloud-init with SSH, Git, rsync, curl, jq, and `/work/crabbox`; AWS can also broker managed Windows and EC2 Mac desktop targets. Static hosts are existing SSH machines selected with `provider: ssh`. Project runtimes come from Actions hydration or repo-owned setup. Runners hold no broker credentials - they are leaf nodes.
|
||||
|
||||
## A run, end to end
|
||||
|
||||
@ -78,6 +78,7 @@ Pick whichever matches your intent:
|
||||
|
||||
- **Get the mental model:** [How Crabbox Works](how-it-works.md), [Architecture](architecture.md), [Orchestrator](orchestrator.md).
|
||||
- **Use the CLI:** [CLI](cli.md), [Commands](commands/README.md), [Features](features/README.md), [Actions hydration](features/actions-hydration.md).
|
||||
- **Pick a target:** [Providers](features/providers.md), [AWS](features/aws.md), [Hetzner](features/hetzner.md), [Blacksmith Testbox](features/blacksmith-testbox.md), [Interactive desktop and VNC](features/interactive-desktop-vnc.md).
|
||||
- **Operate it:** [Operations](operations.md), [Observability](observability.md), [Troubleshooting](troubleshooting.md), [Performance](performance.md).
|
||||
- **Set it up or audit it:** [Infrastructure](infrastructure.md), [Security](security.md), [Source Map](source-map.md), [MVP Plan](mvp-plan.md).
|
||||
|
||||
|
||||
@ -6,7 +6,7 @@ Crabbox has three main parts:
|
||||
|
||||
- CLI: local Go binary used by maintainers and agents.
|
||||
- Coordinator: Cloudflare Worker plus Durable Object state.
|
||||
- Workers: Hetzner or SSH-accessible machines that run commands.
|
||||
- Workers: managed cloud or SSH-accessible machines that run commands.
|
||||
|
||||
The coordinator leases machines. The CLI executes work. Machines do not need to call back to the coordinator in the MVP.
|
||||
|
||||
@ -19,7 +19,7 @@ developer laptop
|
||||
Cloudflare Worker
|
||||
Durable Object lease state
|
||||
|
|
||||
| Hetzner API or AWS EC2 Spot API
|
||||
| Hetzner API or AWS EC2 API
|
||||
v
|
||||
cloud machines
|
||||
|
||||
@ -36,7 +36,7 @@ leased machine
|
||||
2. CLI creates a per-lease SSH key.
|
||||
3. CLI sends `POST /v1/leases` with lease ID, slug, profile, TTL, idle timeout, desired machine class, and SSH public key.
|
||||
4. Coordinator validates identity and policy.
|
||||
5. Durable Object chooses a provider from config and creates a Hetzner server or AWS EC2 Spot instance.
|
||||
5. Durable Object chooses a provider from config and creates a Hetzner server or AWS EC2 instance.
|
||||
6. Coordinator returns lease ID, slug, machine address, SSH user, workdir, and expiry.
|
||||
7. CLI waits for `crabbox-ready`.
|
||||
8. CLI seeds remote Git when possible, compares sync fingerprints, and syncs changed files with `rsync --delete`.
|
||||
@ -101,7 +101,7 @@ Owned backends:
|
||||
|
||||
- `hetzner-static`: pre-created warm machines.
|
||||
- `hetzner-ephemeral`: created per lease or overflow.
|
||||
- `aws-spot`: one-time EC2 Spot instances for burst capacity.
|
||||
- `aws`: one-time EC2 instances for burst capacity, managed Windows/WSL2, and EC2 Mac.
|
||||
- `ssh-static`: manually managed machines reachable by SSH.
|
||||
|
||||
Brokered backends, later:
|
||||
@ -109,7 +109,7 @@ Brokered backends, later:
|
||||
- `github-actions`: register or dispatch real Actions-backed runner work when workflow parity is required.
|
||||
- `external-runner`: adapter boundary for other hosted runner systems if needed.
|
||||
|
||||
The MVP implements `hetzner-ephemeral` and `aws-spot`, and leaves interfaces ready for `hetzner-static`.
|
||||
The current broker implements `hetzner-ephemeral` and `aws`, and leaves interfaces ready for `hetzner-static`.
|
||||
|
||||
## Machine Bootstrap
|
||||
|
||||
|
||||
47
docs/cli.md
47
docs/cli.md
@ -71,7 +71,7 @@ One-shot run:
|
||||
crabbox run --profile project-check -- pnpm check:changed
|
||||
```
|
||||
|
||||
AWS EC2 Spot run:
|
||||
AWS EC2 run:
|
||||
|
||||
```sh
|
||||
crabbox run --class beast -- pnpm check:changed
|
||||
@ -122,7 +122,7 @@ crabbox run --provider ssh --target windows --windows-mode wsl2 --static-host wi
|
||||
Create managed AWS desktop boxes:
|
||||
|
||||
```sh
|
||||
crabbox warmup --provider aws --target windows --desktop --market on-demand
|
||||
crabbox warmup --provider aws --target windows --desktop
|
||||
CRABBOX_AWS_MAC_HOST_ID=h-... crabbox warmup --provider aws --target macos --desktop --market on-demand
|
||||
crabbox vnc --id blue-lobster
|
||||
crabbox screenshot --id blue-lobster --output desktop.png
|
||||
@ -253,8 +253,16 @@ Flags:
|
||||
--profile <name> profile to run on
|
||||
--class <name> machine class override
|
||||
--type <name> provider server or instance type override
|
||||
--market spot|on-demand AWS capacity market override
|
||||
--ttl <duration> maximum lease lifetime, default 90m
|
||||
--idle-timeout <duration> idle expiry, default 30m
|
||||
--desktop provision or require visible desktop capability
|
||||
--browser provision or require browser capability
|
||||
--tailscale join new managed Linux leases to the configured tailnet
|
||||
--tailscale-tags <csv> Tailscale tags for new managed leases
|
||||
--tailscale-hostname-template <template>
|
||||
--tailscale-auth-key-env <env-var>
|
||||
--network auto|tailscale|public
|
||||
--no-sync run without syncing
|
||||
--sync-only sync and exit
|
||||
--force-sync-large allow a sync candidate above configured fail thresholds
|
||||
@ -263,8 +271,6 @@ Flags:
|
||||
--checksum use checksum rsync instead of size/time
|
||||
--debug print sync timing and itemized rsync output
|
||||
--junit <paths> comma-separated remote JUnit XML paths to attach to run history
|
||||
--open open local VNC client for `crabbox vnc`
|
||||
--output <path> local PNG path for `crabbox screenshot`
|
||||
--reclaim claim an existing lease for the current repo
|
||||
--timing-json print a final JSON timing record
|
||||
--blacksmith-org <org> Blacksmith organization
|
||||
@ -462,18 +468,26 @@ blacksmith:
|
||||
```text
|
||||
CRABBOX_COORDINATOR
|
||||
CRABBOX_COORDINATOR_TOKEN
|
||||
CRABBOX_COORDINATOR_ADMIN_TOKEN
|
||||
CRABBOX_ADMIN_TOKEN alias for CRABBOX_COORDINATOR_ADMIN_TOKEN
|
||||
CRABBOX_ACCESS_CLIENT_ID
|
||||
CRABBOX_ACCESS_CLIENT_SECRET
|
||||
CRABBOX_ACCESS_TOKEN
|
||||
CRABBOX_PROVIDER
|
||||
CRABBOX_TARGET
|
||||
CRABBOX_TARGET_OS alias for CRABBOX_TARGET
|
||||
CRABBOX_WINDOWS_MODE
|
||||
CRABBOX_DESKTOP
|
||||
CRABBOX_BROWSER
|
||||
CRABBOX_NETWORK
|
||||
CRABBOX_STATIC_ID
|
||||
CRABBOX_STATIC_NAME
|
||||
CRABBOX_STATIC_HOST
|
||||
CRABBOX_STATIC_USER
|
||||
CRABBOX_STATIC_PORT
|
||||
CRABBOX_STATIC_WORK_ROOT
|
||||
CRABBOX_OWNER
|
||||
CRABBOX_ORG
|
||||
CRABBOX_PROFILE
|
||||
CRABBOX_CONFIG
|
||||
CRABBOX_DEFAULT_CLASS
|
||||
@ -485,6 +499,19 @@ CRABBOX_SSH_USER
|
||||
CRABBOX_SSH_PORT
|
||||
CRABBOX_SSH_FALLBACK_PORTS comma-separated fallback ports, or none
|
||||
CRABBOX_WORK_ROOT
|
||||
CRABBOX_AWS_REGION
|
||||
CRABBOX_AWS_AMI
|
||||
CRABBOX_AWS_SECURITY_GROUP_ID
|
||||
CRABBOX_AWS_SUBNET_ID
|
||||
CRABBOX_AWS_INSTANCE_PROFILE
|
||||
CRABBOX_AWS_ROOT_GB
|
||||
CRABBOX_AWS_SSH_CIDRS
|
||||
CRABBOX_AWS_MAC_HOST_ID
|
||||
CRABBOX_CAPACITY_MARKET
|
||||
CRABBOX_CAPACITY_STRATEGY
|
||||
CRABBOX_CAPACITY_FALLBACK
|
||||
CRABBOX_CAPACITY_REGIONS
|
||||
CRABBOX_CAPACITY_AVAILABILITY_ZONES
|
||||
CRABBOX_ACTIONS_WORKFLOW
|
||||
CRABBOX_ACTIONS_JOB
|
||||
CRABBOX_ACTIONS_REF
|
||||
@ -514,6 +541,11 @@ CRABBOX_ENV_ALLOW
|
||||
CRABBOX_CACHE_PNPM/NPM/DOCKER/GIT
|
||||
CRABBOX_CACHE_MAX_GB
|
||||
CRABBOX_CACHE_PURGE_ON_RELEASE
|
||||
CRABBOX_TAILSCALE
|
||||
CRABBOX_TAILSCALE_TAGS
|
||||
CRABBOX_TAILSCALE_HOSTNAME_TEMPLATE
|
||||
CRABBOX_TAILSCALE_AUTH_KEY_ENV
|
||||
CRABBOX_TAILSCALE_AUTH_KEY direct-provider only, via auth-key env
|
||||
```
|
||||
|
||||
Provider/deploy variables live outside normal CLI operation:
|
||||
@ -522,8 +554,11 @@ Provider/deploy variables live outside normal CLI operation:
|
||||
CRABBOX_CLOUDFLARE_API_TOKEN
|
||||
CRABBOX_CLOUDFLARE_ACCOUNT_ID
|
||||
CRABBOX_CLOUDFLARE_ZONE_ID
|
||||
HCLOUD_TOKEN
|
||||
AWS_PROFILE/AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY
|
||||
CRABBOX_CLOUDFLARE_ZONE_NAME
|
||||
CRABBOX_DOMAIN
|
||||
CRABBOX_FALLBACK_DOMAIN
|
||||
HCLOUD_TOKEN/HETZNER_TOKEN
|
||||
AWS_PROFILE/AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_SESSION_TOKEN
|
||||
GITHUB_TOKEN
|
||||
```
|
||||
|
||||
|
||||
@ -10,7 +10,7 @@ crabbox admin release blue-lobster --delete
|
||||
crabbox admin delete cbx_... --force
|
||||
```
|
||||
|
||||
Release/delete accept a canonical `cbx_...` ID or an active slug; use the canonical ID when an admin slug lookup is ambiguous.
|
||||
Release/delete accept a canonical `cbx_...` ID or an active slug; use the canonical ID when an admin slug lookup is ambiguous. Add `--json` to print the updated lease record.
|
||||
|
||||
Admin commands require a configured coordinator and a separate admin bearer token
|
||||
stored as `broker.adminToken` or `CRABBOX_COORDINATOR_ADMIN_TOKEN`. The shared
|
||||
@ -34,10 +34,26 @@ Flags:
|
||||
|
||||
Mark a lease released. Add `--delete` to delete the backing server while releasing.
|
||||
|
||||
Flags:
|
||||
|
||||
```text
|
||||
--id <lease-id-or-slug>
|
||||
--delete
|
||||
--json
|
||||
```
|
||||
|
||||
## delete
|
||||
|
||||
Delete the backing server for an active lease and mark it released. Requires `--force`.
|
||||
|
||||
Flags:
|
||||
|
||||
```text
|
||||
--id <lease-id-or-slug>
|
||||
--force
|
||||
--json
|
||||
```
|
||||
|
||||
Related docs:
|
||||
|
||||
- [Operations](../operations.md)
|
||||
|
||||
@ -17,6 +17,12 @@ Flags:
|
||||
|
||||
```text
|
||||
--provider hetzner|aws
|
||||
--target linux|macos|windows
|
||||
--windows-mode normal|wsl2
|
||||
--static-host <host>
|
||||
--static-user <user>
|
||||
--static-port <port>
|
||||
--static-work-root <path>
|
||||
--dry-run
|
||||
```
|
||||
|
||||
|
||||
@ -15,7 +15,7 @@ Subcommands:
|
||||
```text
|
||||
path
|
||||
show [--json]
|
||||
set-broker --url <url> --token-stdin [--provider hetzner|aws]
|
||||
set-broker --url <url> [--token-stdin] [--admin-token-stdin] [--provider hetzner|aws]
|
||||
```
|
||||
|
||||
`config show` reports broker auth as `auth` and `admin_auth`, plus
|
||||
|
||||
@ -23,4 +23,7 @@ Flags:
|
||||
--target linux|macos|windows
|
||||
--windows-mode normal|wsl2
|
||||
--static-host <host>
|
||||
--static-user <user>
|
||||
--static-port <port>
|
||||
--static-work-root <path>
|
||||
```
|
||||
|
||||
@ -5,6 +5,7 @@
|
||||
```sh
|
||||
crabbox image create --id cbx_... --name openclaw-crabbox-20260501-1246 --wait
|
||||
crabbox image promote ami-...
|
||||
crabbox image promote ami-... --json
|
||||
```
|
||||
|
||||
Image commands require a configured coordinator and admin-token auth. Set
|
||||
@ -64,6 +65,8 @@ Promote an available AMI as the coordinator's default AWS image:
|
||||
crabbox image promote ami-1234567890abcdef0
|
||||
```
|
||||
|
||||
Add `--json` to print the promoted image record for automation.
|
||||
|
||||
Future brokered AWS leases use the promoted image when the request does not set
|
||||
an explicit `awsAMI` or `CRABBOX_AWS_AMI` override. Promotion stores coordinator
|
||||
metadata only; it does not copy or modify the AMI.
|
||||
|
||||
@ -19,6 +19,9 @@ Flags:
|
||||
--target linux|macos|windows
|
||||
--windows-mode normal|wsl2
|
||||
--static-host <host>
|
||||
--static-user <user>
|
||||
--static-port <port>
|
||||
--static-work-root <path>
|
||||
--network auto|tailscale|public
|
||||
--json
|
||||
```
|
||||
|
||||
@ -23,5 +23,8 @@ Flags:
|
||||
--target linux|macos|windows
|
||||
--windows-mode normal|wsl2
|
||||
--static-host <host>
|
||||
--static-user <user>
|
||||
--static-port <port>
|
||||
--static-work-root <path>
|
||||
--json
|
||||
```
|
||||
|
||||
@ -34,9 +34,10 @@ Browser login/profile state is not managed by Crabbox; use a scenario-owned
|
||||
profile directory or app-specific auth artifact when tests need a logged-in
|
||||
browser.
|
||||
|
||||
`--desktop` provisions or requires a visible Linux display and injects
|
||||
`CRABBOX_DESKTOP=1` plus `DISPLAY=:99`. It does not imply a browser. Use
|
||||
`--desktop --browser` for headed browser automation in the VNC-visible session.
|
||||
`--desktop` provisions or requires a visible desktop/VNC session and injects
|
||||
`CRABBOX_DESKTOP=1`; POSIX desktop targets also use `DISPLAY=:99`. It does not
|
||||
imply a browser. Use `--desktop --browser` for headed browser automation in the
|
||||
VNC-visible session.
|
||||
|
||||
`--tailscale` asks new managed Linux leases to join the configured tailnet.
|
||||
`--network` selects how Crabbox resolves SSH for reused leases and for the final
|
||||
|
||||
@ -49,3 +49,10 @@ Flags:
|
||||
--output <path>
|
||||
--reclaim
|
||||
```
|
||||
|
||||
Related docs:
|
||||
|
||||
- [Interactive desktop and VNC](../features/interactive-desktop-vnc.md)
|
||||
- [Linux VNC](../features/vnc-linux.md)
|
||||
- [Windows VNC](../features/vnc-windows.md)
|
||||
- [macOS VNC](../features/vnc-macos.md)
|
||||
|
||||
@ -18,6 +18,9 @@ Flags:
|
||||
--target linux|macos|windows
|
||||
--windows-mode normal|wsl2
|
||||
--static-host <host>
|
||||
--static-user <user>
|
||||
--static-port <port>
|
||||
--static-work-root <path>
|
||||
--network auto|tailscale|public
|
||||
--reclaim
|
||||
```
|
||||
|
||||
@ -20,6 +20,9 @@ Flags:
|
||||
--target linux|macos|windows
|
||||
--windows-mode normal|wsl2
|
||||
--static-host <host>
|
||||
--static-user <user>
|
||||
--static-port <port>
|
||||
--static-work-root <path>
|
||||
--network auto|tailscale|public
|
||||
--wait
|
||||
--wait-timeout <duration>
|
||||
|
||||
@ -17,4 +17,7 @@ Flags:
|
||||
--target linux|macos|windows
|
||||
--windows-mode normal|wsl2
|
||||
--static-host <host>
|
||||
--static-user <user>
|
||||
--static-port <port>
|
||||
--static-work-root <path>
|
||||
```
|
||||
|
||||
@ -19,7 +19,7 @@ crabbox vnc --id blue-lobster --open
|
||||
Managed AWS Windows and EC2 Mac desktop leases use the same command:
|
||||
|
||||
```sh
|
||||
crabbox warmup --provider aws --target windows --desktop --market on-demand
|
||||
crabbox warmup --provider aws --target windows --desktop
|
||||
crabbox vnc --id crimson-crab
|
||||
|
||||
CRABBOX_AWS_MAC_HOST_ID=h-... \
|
||||
@ -148,7 +148,7 @@ host's VNC or Screen Sharing prompt.
|
||||
| --- | --- | --- |
|
||||
| Hetzner Linux | Yes | Requires `--desktop`; installs XFCE, Xvfb, and x11vnc. |
|
||||
| AWS Linux | Yes | Requires `--desktop`; same Linux desktop profile. |
|
||||
| AWS Windows | Yes | Requires `--target windows --desktop --market on-demand`; installs Git for Windows and TightVNC after EC2Launch enables OpenSSH. |
|
||||
| AWS Windows | Yes | Requires `--target windows --desktop`; installs Git for Windows and TightVNC after EC2Launch enables OpenSSH. Spot or On-Demand follows the AWS capacity config. |
|
||||
| AWS macOS | Yes | Requires `--target macos --desktop --market on-demand` plus `CRABBOX_AWS_MAC_HOST_ID` or `aws.macHostId`. |
|
||||
| Static Linux | Host-managed | Requires an existing loopback VNC service on the host. |
|
||||
| Static macOS | Host-managed | Uses existing Screen Sharing or VNC. |
|
||||
@ -252,5 +252,8 @@ Related docs:
|
||||
- [screenshot](screenshot.md)
|
||||
- [warmup](warmup.md)
|
||||
- [Interactive desktop and VNC](../features/interactive-desktop-vnc.md)
|
||||
- [Linux VNC](../features/vnc-linux.md)
|
||||
- [Windows VNC](../features/vnc-windows.md)
|
||||
- [macOS VNC](../features/vnc-macos.md)
|
||||
- [Tailscale](../features/tailscale.md)
|
||||
- [Providers](../features/providers.md)
|
||||
|
||||
@ -8,7 +8,7 @@ crabbox warmup --provider aws --class beast --market on-demand
|
||||
crabbox warmup --browser
|
||||
crabbox warmup --tailscale
|
||||
crabbox warmup --desktop --browser
|
||||
crabbox warmup --provider aws --target windows --desktop --market on-demand
|
||||
crabbox warmup --provider aws --target windows --desktop
|
||||
crabbox warmup --provider aws --target macos --desktop --market on-demand --type mac2.metal
|
||||
crabbox warmup --actions-runner
|
||||
crabbox warmup --provider blacksmith-testbox --blacksmith-workflow .github/workflows/ci-check-testbox.yml --blacksmith-job test
|
||||
|
||||
@ -43,6 +43,10 @@ Flags:
|
||||
--provider hetzner|aws
|
||||
--target linux|macos|windows
|
||||
--windows-mode normal|wsl2
|
||||
--static-host <host>
|
||||
--static-user <user>
|
||||
--static-port <port>
|
||||
--static-work-root <path>
|
||||
--network auto|tailscale|public
|
||||
--local-port <port>
|
||||
--open
|
||||
@ -55,3 +59,10 @@ Limitations:
|
||||
- Static SSH hosts are intentionally not supported yet because the portal cannot
|
||||
prove that host-managed VNC credentials and prompts are safe to expose.
|
||||
- Blacksmith Testbox still owns its own machine connectivity.
|
||||
|
||||
Related docs:
|
||||
|
||||
- [Interactive desktop and VNC](../features/interactive-desktop-vnc.md)
|
||||
- [Linux VNC](../features/vnc-linux.md)
|
||||
- [Windows VNC](../features/vnc-windows.md)
|
||||
- [macOS VNC](../features/vnc-macos.md)
|
||||
|
||||
@ -12,13 +12,16 @@ Core features:
|
||||
|
||||
- [Coordinator](coordinator.md): brokered leases through Cloudflare Workers and Durable Objects.
|
||||
- [Broker auth and routing](broker-auth-routing.md): GitHub login, shared bearer tokens, optional Cloudflare Access, and Worker routes.
|
||||
- [Providers](providers.md): Hetzner, AWS EC2 Spot, static SSH macOS/Windows targets, Blacksmith Testbox selection, classes, and fallback.
|
||||
- [Providers](providers.md): provider overview, target matrix, classes, and fallback.
|
||||
- [AWS](aws.md): EC2 Linux, Windows, WSL2, EC2 Mac, capacity, AMIs, and security groups.
|
||||
- [Hetzner](hetzner.md): Linux-only managed Hetzner behavior, classes, and cleanup.
|
||||
- [Blacksmith Testbox](blacksmith-testbox.md): delegated Testbox backend behavior.
|
||||
- [Tailscale](tailscale.md): optional tailnet reachability for managed Linux leases and static hosts.
|
||||
- [Blacksmith Testbox](blacksmith-testbox.md): wrapper mode that delegates machines and sync to the Blacksmith CLI.
|
||||
- [Runner bootstrap](runner-bootstrap.md): cloud-init, installed tools, SSH port, and readiness.
|
||||
- [Sync](sync.md): Git file-list manifests, rsync, fingerprints, excludes, guardrails, and sanity checks.
|
||||
- [Actions hydration](actions-hydration.md): let GitHub Actions prepare a runner, then sync local work into that workspace.
|
||||
- [Interactive desktop and VNC](interactive-desktop-vnc.md): Linux UI leases, tunnel-only VNC takeover, and Mantis/browser QA boundaries.
|
||||
- [Interactive desktop and VNC](interactive-desktop-vnc.md): VNC hub, support matrix, tunnel model, and QA boundaries.
|
||||
- [Linux VNC](vnc-linux.md), [Windows VNC](vnc-windows.md), [macOS VNC](vnc-macos.md): OS-specific desktop setup and troubleshooting.
|
||||
- [SSH keys](ssh-keys.md): per-lease keys, provider key cleanup, and local storage.
|
||||
- [Cost and usage](cost-usage.md): guardrails, provider-backed pricing, and reporting.
|
||||
- [History and logs](history-logs.md): coordinator run records, events, and retained remote output.
|
||||
|
||||
@ -8,9 +8,9 @@ Read when:
|
||||
|
||||
Actions hydration lets a repository reuse its existing GitHub Actions setup without putting repository-specific setup code in the Crabbox binary.
|
||||
|
||||
Runner registration is currently Linux-only. Brokered Hetzner/AWS targets work;
|
||||
static macOS and Windows SSH targets are for direct `crabbox run` loops until
|
||||
platform-specific runner installation is added.
|
||||
Runner registration is currently Linux-only. Brokered Hetzner/AWS Linux targets
|
||||
work; static macOS/Windows and managed AWS Windows/macOS targets are for direct
|
||||
`crabbox run` loops until platform-specific runner installation is added.
|
||||
|
||||
The flow:
|
||||
|
||||
|
||||
117
docs/features/aws.md
Normal file
117
docs/features/aws.md
Normal file
@ -0,0 +1,117 @@
|
||||
# AWS
|
||||
|
||||
Read when:
|
||||
|
||||
- choosing AWS as the Crabbox provider;
|
||||
- debugging EC2 capacity, quotas, AMIs, security groups, or EC2 Mac hosts;
|
||||
- changing AWS provisioning code in the CLI or Worker.
|
||||
|
||||
AWS is Crabbox's broad managed provider. It supports Linux, native Windows,
|
||||
Windows WSL2, and EC2 Mac targets. Brokered mode keeps AWS credentials in the
|
||||
Cloudflare Worker; direct mode uses the local AWS credential chain for provider
|
||||
debugging.
|
||||
|
||||
## Targets
|
||||
|
||||
| Target | Managed | Notes |
|
||||
| --- | --- | --- |
|
||||
| Linux | Yes | Spot by default; On-Demand optional; cloud-init bootstrap. |
|
||||
| Windows native | Yes | EC2Launch, OpenSSH, Git for Windows, TightVNC, archive sync. |
|
||||
| Windows WSL2 | Yes | Nested virtualization on C8i/M8i/R8i families; POSIX sync through WSL. |
|
||||
| macOS | Yes | EC2 Mac Dedicated Host id required; On-Demand only. |
|
||||
|
||||
Examples:
|
||||
|
||||
```sh
|
||||
crabbox warmup --provider aws --class beast
|
||||
crabbox run --provider aws --class beast --market on-demand -- pnpm check
|
||||
crabbox warmup --provider aws --target windows --desktop
|
||||
crabbox warmup --provider aws --target windows --windows-mode wsl2
|
||||
CRABBOX_AWS_MAC_HOST_ID=h-... crabbox warmup --provider aws --target macos --desktop --market on-demand
|
||||
```
|
||||
|
||||
## Capacity
|
||||
|
||||
AWS Linux defaults to Spot. Use `--market on-demand` for one lease when Spot is
|
||||
blocked or when an account only has On-Demand quota. `capacity.fallback` can
|
||||
fall back to On-Demand after Spot capacity/quota failures when configured.
|
||||
|
||||
Crabbox tries ordered instance candidates for the requested class. Explicit
|
||||
`--type` is exact: if EC2 rejects it, Crabbox fails clearly instead of silently
|
||||
choosing another type.
|
||||
|
||||
Current class defaults:
|
||||
|
||||
```text
|
||||
AWS Linux
|
||||
standard c7a.8xlarge, c7i.8xlarge, m7a.8xlarge, m7i.8xlarge, c7a.4xlarge
|
||||
fast c7a.16xlarge, c7i.16xlarge, m7a.16xlarge, m7i.16xlarge, c7a.12xlarge, c7a.8xlarge
|
||||
large c7a.24xlarge, c7i.24xlarge, m7a.24xlarge, m7i.24xlarge, r7a.24xlarge, c7a.16xlarge, c7a.12xlarge
|
||||
beast c7a.48xlarge, c7i.48xlarge, m7a.48xlarge, m7i.48xlarge, r7a.48xlarge, c7a.32xlarge, c7i.32xlarge, m7a.32xlarge, c7a.24xlarge, c7a.16xlarge
|
||||
|
||||
AWS Windows
|
||||
standard m7i.large, m7a.large, t3.large
|
||||
fast m7i.xlarge, m7a.xlarge, t3.xlarge
|
||||
large m7i.2xlarge, m7a.2xlarge, t3.2xlarge
|
||||
beast m7i.4xlarge, m7a.4xlarge, m7i.2xlarge
|
||||
|
||||
AWS Windows WSL2
|
||||
standard m8i.large, m8i-flex.large, c8i.large, r8i.large
|
||||
fast m8i.xlarge, m8i-flex.xlarge, c8i.xlarge, r8i.xlarge
|
||||
large m8i.2xlarge, m8i-flex.2xlarge, c8i.2xlarge, r8i.2xlarge
|
||||
beast m8i.4xlarge, m8i-flex.4xlarge, c8i.4xlarge, r8i.4xlarge, m8i.2xlarge
|
||||
|
||||
AWS macOS
|
||||
all mac2.metal unless `--type` is set
|
||||
```
|
||||
|
||||
## Broker Secrets And Env
|
||||
|
||||
Worker secrets:
|
||||
|
||||
```text
|
||||
AWS_ACCESS_KEY_ID
|
||||
AWS_SECRET_ACCESS_KEY
|
||||
AWS_SESSION_TOKEN optional
|
||||
CRABBOX_AWS_MAC_HOST_ID optional; required for brokered target=macos
|
||||
```
|
||||
|
||||
CLI/direct env and config:
|
||||
|
||||
```text
|
||||
AWS_PROFILE
|
||||
AWS_ACCESS_KEY_ID
|
||||
AWS_SECRET_ACCESS_KEY
|
||||
AWS_SESSION_TOKEN
|
||||
CRABBOX_AWS_REGION
|
||||
CRABBOX_AWS_AMI
|
||||
CRABBOX_AWS_SECURITY_GROUP_ID
|
||||
CRABBOX_AWS_SUBNET_ID
|
||||
CRABBOX_AWS_INSTANCE_PROFILE
|
||||
CRABBOX_AWS_ROOT_GB
|
||||
CRABBOX_AWS_SSH_CIDRS
|
||||
CRABBOX_AWS_MAC_HOST_ID
|
||||
```
|
||||
|
||||
## Security And Networking
|
||||
|
||||
Crabbox imports or reuses an EC2 key pair, creates or reuses the
|
||||
`crabbox-runners` security group when no security group is supplied, and opens
|
||||
only SSH ports to configured CIDRs or the detected request source. VNC stays
|
||||
behind the SSH tunnel. Supplying `CRABBOX_AWS_SECURITY_GROUP_ID` makes ingress
|
||||
policy your responsibility.
|
||||
|
||||
## Images
|
||||
|
||||
Linux resolves the latest Ubuntu 24.04 x86_64 AMI unless overridden. Windows
|
||||
resolves the latest Windows Server 2022 English Full Base AMI unless overridden.
|
||||
Operators can create and promote trusted AWS images with `crabbox image`.
|
||||
|
||||
Related docs:
|
||||
|
||||
- [Providers](providers.md)
|
||||
- [Linux VNC](vnc-linux.md)
|
||||
- [Windows VNC](vnc-windows.md)
|
||||
- [macOS VNC](vnc-macos.md)
|
||||
- [Infrastructure](../infrastructure.md)
|
||||
- [image command](../commands/image.md)
|
||||
@ -2,12 +2,17 @@
|
||||
|
||||
Read when:
|
||||
|
||||
- choosing a provider/service page;
|
||||
- choosing `provider: blacksmith-testbox`;
|
||||
- changing Blacksmith CLI forwarding;
|
||||
- deciding what Crabbox owns versus Blacksmith owns.
|
||||
|
||||
Crabbox can use Blacksmith Testboxes as the machine backend without using the Crabbox broker. Select it with `--provider blacksmith-testbox` for one command, or put `provider: blacksmith-testbox` in config when a repo or machine should use it by default.
|
||||
|
||||
Blacksmith is a delegated service integration. Crabbox does not provision,
|
||||
bootstrap, sync, or expose VNC for the Testbox itself; it forwards to the
|
||||
Blacksmith CLI and keeps local Crabbox ergonomics around that CLI.
|
||||
|
||||
## One-Liners
|
||||
|
||||
If you already have a Blacksmith Testbox ID, no Crabbox YAML is required:
|
||||
@ -100,6 +105,15 @@ Because Blacksmith owns sync in this mode, Crabbox sync flags such as `--sync-on
|
||||
|
||||
`blacksmith.workflow` is required only when Crabbox needs to warm or acquire a Testbox. Reusing an existing `tbx_...` ID or slug does not need workflow config.
|
||||
|
||||
## Desktop And VNC
|
||||
|
||||
Blacksmith can run headless browser automation through its own runner setup, but
|
||||
Crabbox does not currently expose `crabbox vnc`, `crabbox webvnc`, or managed
|
||||
screenshots for `provider=blacksmith-testbox`. Blacksmith owns machine
|
||||
connectivity in this mode. Crabbox should add VNC only after Blacksmith exposes
|
||||
a stable SSH tunnel or connection-info API that preserves the same security
|
||||
boundary as managed Crabbox leases.
|
||||
|
||||
## Choosing The Path
|
||||
|
||||
Use the one-liner when:
|
||||
@ -117,6 +131,7 @@ Use repo YAML when:
|
||||
Related docs:
|
||||
|
||||
- [Providers](providers.md)
|
||||
- [Interactive desktop and VNC](interactive-desktop-vnc.md)
|
||||
- [run command](../commands/run.md)
|
||||
- [warmup command](../commands/warmup.md)
|
||||
- [Source map](../source-map.md)
|
||||
|
||||
78
docs/features/hetzner.md
Normal file
78
docs/features/hetzner.md
Normal file
@ -0,0 +1,78 @@
|
||||
# Hetzner
|
||||
|
||||
Read when:
|
||||
|
||||
- choosing Hetzner as the Crabbox provider;
|
||||
- debugging Hetzner capacity, quotas, images, or SSH readiness;
|
||||
- changing Hetzner provisioning code in the CLI or Worker.
|
||||
|
||||
Hetzner is Crabbox's Linux-only managed provider. It creates Ubuntu servers,
|
||||
labels them with Crabbox lease metadata, bootstraps the normal SSH/sync
|
||||
contract, and optionally adds Linux desktop/browser capability.
|
||||
|
||||
## Targets
|
||||
|
||||
| Target | Managed | Notes |
|
||||
| --- | --- | --- |
|
||||
| Linux | Yes | Cloud-init bootstrap, SSH, rsync, optional desktop/browser. |
|
||||
| Windows | No | Use AWS for managed Windows or `provider: ssh` for an existing Windows host. |
|
||||
| macOS | No | Use AWS EC2 Mac or `provider: ssh` for an existing Mac. |
|
||||
|
||||
Examples:
|
||||
|
||||
```sh
|
||||
crabbox warmup --provider hetzner --class beast
|
||||
crabbox run --provider hetzner --class standard -- pnpm test
|
||||
crabbox warmup --provider hetzner --desktop --browser
|
||||
crabbox vnc --id blue-lobster --open
|
||||
```
|
||||
|
||||
## Classes
|
||||
|
||||
```text
|
||||
standard ccx33, cpx62, cx53
|
||||
fast ccx43, cpx62, cx53
|
||||
large ccx53, ccx43, cpx62, cx53
|
||||
beast ccx63, ccx53, ccx43, cpx62, cx53
|
||||
```
|
||||
|
||||
Dedicated-core types can hit account quota. Crabbox falls back through the
|
||||
configured server types when Hetzner rejects a candidate for capacity or quota.
|
||||
Explicit `--type` is exact and fails clearly when the type cannot be created.
|
||||
|
||||
## Broker Secrets And Env
|
||||
|
||||
Worker secret:
|
||||
|
||||
```text
|
||||
HETZNER_TOKEN
|
||||
```
|
||||
|
||||
Direct/provider env and config:
|
||||
|
||||
```text
|
||||
HCLOUD_TOKEN
|
||||
HETZNER_TOKEN
|
||||
CRABBOX_HETZNER_IMAGE
|
||||
CRABBOX_HETZNER_LOCATION
|
||||
CRABBOX_HETZNER_SSH_KEY
|
||||
```
|
||||
|
||||
## Desktop
|
||||
|
||||
Hetzner desktop leases use the Linux VNC path: Xvfb, a lightweight desktop
|
||||
session, x11vnc bound to `127.0.0.1:5900`, and an SSH local tunnel created by
|
||||
`crabbox vnc`. Hetzner does not manage Windows desktop boxes in Crabbox.
|
||||
|
||||
## Cleanup
|
||||
|
||||
Brokered cleanup belongs to the Durable Object alarm. Direct cleanup is
|
||||
best-effort through provider labels and `crabbox cleanup`; it skips kept
|
||||
machines and deletes expired direct-provider leftovers.
|
||||
|
||||
Related docs:
|
||||
|
||||
- [Providers](providers.md)
|
||||
- [Linux VNC](vnc-linux.md)
|
||||
- [Infrastructure](../infrastructure.md)
|
||||
- [cleanup command](../commands/cleanup.md)
|
||||
@ -2,128 +2,150 @@
|
||||
|
||||
Read when:
|
||||
|
||||
- adding or using browser/UI QA that needs a visible Linux desktop;
|
||||
- deciding whether Mantis, OpenClaw, or Crabbox owns VNC setup;
|
||||
- debugging an interactive QA lease that needs operator takeover.
|
||||
- choosing a desktop target for browser/UI QA;
|
||||
- opening a lease with VNC or WebVNC;
|
||||
- deciding which layer owns desktop setup, browser state, screenshots, or
|
||||
credentials.
|
||||
|
||||
Interactive desktop support belongs in Crabbox. Crabbox owns machine lifecycle,
|
||||
network reachability, SSH keys, lease expiry, and provider-specific setup.
|
||||
Scenario systems such as Mantis should ask for the needed machine capability
|
||||
and then drive browser automation, screenshots, artifacts, and PR comments from
|
||||
inside that lease.
|
||||
Crabbox treats desktop access as a lease capability, not a separate remote
|
||||
access product. A desktop lease still uses the normal Crabbox boundaries:
|
||||
provider lifecycle, per-lease SSH keys, SSH tunnels, idle expiry, cleanup, and
|
||||
run history. VNC is a way to inspect or drive the visible session inside that
|
||||
boundary.
|
||||
|
||||
The intended contract is:
|
||||
## Quick Start
|
||||
|
||||
- `crabbox warmup --desktop` leases or reuses a machine with the normal Crabbox
|
||||
SSH contract plus a desktop profile;
|
||||
- `crabbox warmup --browser` leases or reuses a Linux machine with a known
|
||||
browser binary for headless automation;
|
||||
- `crabbox warmup --desktop --browser` combines a visible session with a browser
|
||||
for headed automation;
|
||||
- `crabbox vnc --id <lease>` prints a tunnel command and connection metadata for
|
||||
operator takeover, including `managed: true` for Crabbox-created desktops and
|
||||
`managed: false` for static host services;
|
||||
- `crabbox run --id <lease> --desktop -- <command...>` runs UI automation in
|
||||
the desktop session;
|
||||
- `crabbox run --id <lease> --browser -- <command...>` injects browser env
|
||||
without requiring a desktop;
|
||||
- `crabbox desktop launch --id <lease> --browser --url <url>` opens a browser
|
||||
or app in the visible desktop and detaches it from SSH;
|
||||
- desktop services bind to loopback on the runner and are reachable through SSH
|
||||
tunnels only;
|
||||
- `--network tailscale` can move the SSH tunnel endpoint onto the tailnet, but
|
||||
managed VNC still binds to `127.0.0.1:5900` on the runner;
|
||||
- screenshots, traces, videos, and browser profiles remain regular command
|
||||
artifacts owned by the caller or repository workflow.
|
||||
```sh
|
||||
crabbox warmup --desktop --browser
|
||||
crabbox vnc --id blue-lobster --open
|
||||
crabbox webvnc --id blue-lobster --open
|
||||
crabbox screenshot --id blue-lobster --output desktop.png
|
||||
```
|
||||
|
||||
Login and browser profile state are caller-owned. `--browser` only guarantees a
|
||||
browser binary and env such as `BROWSER` and `CHROME_BIN`; it does not create,
|
||||
sync, unlock, or migrate a logged-in profile. On managed Linux, a manual login
|
||||
through VNC persists only for that lease and disappears with the machine unless
|
||||
the caller stores a profile artifact intentionally. On static macOS or Windows,
|
||||
the target may already have a logged-in OS browser profile, but Crabbox does not
|
||||
copy Keychain, DPAPI, cookies, or Chrome sync state across hosts or operating
|
||||
systems.
|
||||
AWS Windows and EC2 Mac use the same VNC command once the desktop lease exists:
|
||||
|
||||
For repeatable logged-in tests, the scenario layer should create a named
|
||||
profile or import app-specific auth state, for example a Playwright storage
|
||||
state file, from the repository's normal secret flow. Avoid syncing full browser
|
||||
profile directories between operating systems; browser credentials are often
|
||||
machine- and user-encrypted.
|
||||
```sh
|
||||
crabbox warmup --provider aws --target windows --desktop
|
||||
crabbox vnc --id crimson-crab --open
|
||||
|
||||
Crabbox should provision the reusable machine capability:
|
||||
CRABBOX_AWS_MAC_HOST_ID=h-... \
|
||||
crabbox warmup --provider aws --target macos --desktop --market on-demand
|
||||
crabbox vnc --id silver-squid --open
|
||||
```
|
||||
|
||||
- Xvfb or a lightweight compositor/display manager;
|
||||
- a small window manager suitable for browser automation;
|
||||
- Chrome stable or a Chromium fallback when `--browser` is requested;
|
||||
- x11vnc or an equivalent VNC server bound to `127.0.0.1`;
|
||||
- a per-lease VNC password retrieved over SSH by `crabbox vnc`.
|
||||
Static hosts are explicit and host-managed:
|
||||
|
||||
Crabbox should not own product-specific scenario logic:
|
||||
```sh
|
||||
crabbox vnc --provider ssh --target macos --static-host mac-studio.local --host-managed --open
|
||||
crabbox vnc --provider ssh --target windows --static-host win-dev.local --host-managed --open
|
||||
```
|
||||
|
||||
- provider tokens and app credentials;
|
||||
- Discord, Slack, WhatsApp, email, or OpenClaw workflow setup;
|
||||
## What Crabbox Owns
|
||||
|
||||
Crabbox owns:
|
||||
|
||||
- the lease lifecycle and cleanup;
|
||||
- per-lease SSH keys and known_hosts scoping;
|
||||
- SSH local forwarding to the target's loopback VNC service;
|
||||
- generated per-lease VNC or OS passwords for managed desktop leases;
|
||||
- `desktop=true` and `browser=true` lease metadata;
|
||||
- screenshots and desktop launch commands that operate inside the lease.
|
||||
|
||||
Scenario systems such as Mantis own:
|
||||
|
||||
- product-specific login and app credentials;
|
||||
- browser profile import/export;
|
||||
- screenshots that prove a bug before and after a fix;
|
||||
- PR comments or issue triage.
|
||||
- PR comments, issue triage, and artifact summaries.
|
||||
|
||||
Those belong to Mantis or the repository workflow. Crabbox's job is to make the
|
||||
machine debuggable and reproducible.
|
||||
## Support Matrix
|
||||
|
||||
Security rules:
|
||||
| Target | Managed by Crabbox | Desktop access | Primary page |
|
||||
| --- | --- | --- | --- |
|
||||
| Linux on Hetzner | Yes | Xvfb/XFCE/x11vnc over SSH tunnel | [Linux VNC](vnc-linux.md) |
|
||||
| Linux on AWS | Yes | Xvfb/XFCE/x11vnc over SSH tunnel | [Linux VNC](vnc-linux.md) |
|
||||
| AWS Windows | Yes | TightVNC over SSH tunnel | [Windows VNC](vnc-windows.md) |
|
||||
| AWS EC2 Mac | Yes | Screen Sharing/VNC over SSH tunnel | [macOS VNC](vnc-macos.md) |
|
||||
| Static Linux | Host-managed | Existing loopback VNC service | [Linux VNC](vnc-linux.md) |
|
||||
| Static macOS | Host-managed | Existing Screen Sharing/VNC | [macOS VNC](vnc-macos.md) |
|
||||
| Static Windows | Host-managed | Existing VNC service | [Windows VNC](vnc-windows.md) |
|
||||
| Blacksmith Testbox | No | Not exposed through Crabbox VNC today | [Blacksmith Testbox](blacksmith-testbox.md) |
|
||||
|
||||
- never expose VNC directly to the public internet;
|
||||
- do not expose managed VNC directly on the Tailscale 100.x interface;
|
||||
- prefer SSH local forwarding such as `localhost:5901 -> 127.0.0.1:5900`;
|
||||
- generate per-lease VNC passwords for managed desktop leases;
|
||||
- redact passwords from logs and run records;
|
||||
- stop desktop services when the lease stops;
|
||||
- keep the normal TTL and idle-timeout lifecycle in force.
|
||||
## Commands
|
||||
|
||||
Provider notes:
|
||||
Use `crabbox vnc` for a native VNC client:
|
||||
|
||||
- Hetzner and AWS brokered Linux leases use cloud-init to install Xvfb, XFCE,
|
||||
x11vnc, and optional Chrome/Chromium.
|
||||
- AWS brokered Windows desktop leases use EC2Launch v2 `enableOpenSsh` for the
|
||||
first AWS key-backed foothold. The Crabbox CLI then installs Git for Windows
|
||||
and TightVNC, creates a local `crabbox` administrator, stores the per-lease
|
||||
password under `C:\ProgramData\crabbox`, enables Windows auto-logon for that
|
||||
user, and verifies loopback VNC after the reboot. VNC is reached through the
|
||||
SSH tunnel; the security group only needs SSH.
|
||||
- AWS brokered macOS desktop leases require an allocated EC2 Mac Dedicated Host
|
||||
and On-Demand capacity. Bootstrap enables Screen Sharing for `ec2-user` and
|
||||
stores the generated password on the instance for `crabbox vnc`.
|
||||
- Static SSH Linux hosts can participate when the operator accepts responsibility
|
||||
for packages and display services.
|
||||
- Static macOS hosts are existing Macs, not Crabbox-created boxes. They can
|
||||
participate when Screen Sharing or another
|
||||
VNC-compatible service is already available on `127.0.0.1:5900` over SSH or
|
||||
directly on `host:5900`. Credentials are host-managed because Apple Remote
|
||||
Desktop authentication still belongs to the target host.
|
||||
- Static Windows hosts are existing Windows machines, not Crabbox-created boxes.
|
||||
They can participate only when the operator already provides a VNC-compatible
|
||||
service on `127.0.0.1:5900` for SSH tunneling or, for trusted static networks,
|
||||
directly on `host:5900`. Opening Windows requires `--host-managed` because the
|
||||
password prompt belongs to the target OS, not Crabbox.
|
||||
- Blacksmith Testbox can run headless browser automation today, but VNC takeover
|
||||
needs a Blacksmith-supported SSH tunnel or connection-info API before Crabbox
|
||||
can offer the same `vnc` command there.
|
||||
- EC2 Mac host allocation, host scrubbing, and the AWS 24-hour host lifecycle
|
||||
remain operator concerns; Crabbox only launches onto a host id it is given.
|
||||
```sh
|
||||
crabbox vnc --id blue-lobster
|
||||
crabbox vnc --id blue-lobster --network tailscale
|
||||
crabbox vnc --id blue-lobster --open
|
||||
```
|
||||
|
||||
For Mantis, the first consumer should be a Discord QA lane:
|
||||
Use `crabbox webvnc` for the authenticated coordinator portal:
|
||||
|
||||
1. lease a desktop-capable Linux runner;
|
||||
2. hydrate OpenClaw and the Discord bot credentials;
|
||||
3. create a named browser profile;
|
||||
4. reproduce the baseline and capture screenshots;
|
||||
5. apply or check out the candidate fix;
|
||||
6. rerun the same scenario and capture candidate screenshots;
|
||||
7. attach artifacts and a compact visual summary to the PR.
|
||||
```sh
|
||||
crabbox webvnc --id blue-lobster --open
|
||||
```
|
||||
|
||||
Related docs:
|
||||
Use `crabbox screenshot` when you need a PNG without taking over the session:
|
||||
|
||||
- [Runner bootstrap](runner-bootstrap.md)
|
||||
- [Providers](providers.md)
|
||||
- [Tailscale](tailscale.md)
|
||||
- [SSH keys](ssh-keys.md)
|
||||
- [Actions hydration](actions-hydration.md)
|
||||
```sh
|
||||
crabbox screenshot --id blue-lobster --output desktop.png
|
||||
```
|
||||
|
||||
Use `crabbox desktop launch` to start a browser or app inside the visible
|
||||
session without keeping the SSH command attached:
|
||||
|
||||
```sh
|
||||
crabbox desktop launch --id blue-lobster --browser --url https://example.com
|
||||
```
|
||||
|
||||
## Network Model
|
||||
|
||||
Managed VNC is tunnel-first:
|
||||
|
||||
- VNC binds to `127.0.0.1:5900` on the target.
|
||||
- The cloud firewall/security group opens SSH only, not VNC.
|
||||
- `crabbox vnc` forwards a local port such as `localhost:5901` to remote
|
||||
`127.0.0.1:5900`.
|
||||
- `--network tailscale` changes only the SSH endpoint used by that tunnel.
|
||||
- WebVNC keeps the same local SSH tunnel and adds an authenticated browser
|
||||
websocket through the coordinator.
|
||||
|
||||
Crabbox does not bind managed VNC directly to a public IP or Tailscale 100.x
|
||||
address. Static hosts can expose direct `host:5900` only when the operator has
|
||||
already made that endpoint reachable on a trusted network.
|
||||
|
||||
## Browser State
|
||||
|
||||
`--browser` guarantees a browser binary and env such as `BROWSER` and
|
||||
`CHROME_BIN`; it does not create, unlock, sync, or migrate a logged-in profile.
|
||||
On managed targets, manual browser login through VNC lasts only for that lease
|
||||
unless the caller intentionally exports an artifact. On static hosts, any
|
||||
existing browser profile belongs to that host.
|
||||
|
||||
For repeatable logged-in tests, use scenario-owned state such as a Playwright
|
||||
storage-state file or an app-specific short-lived token. Avoid syncing full
|
||||
browser profile directories between operating systems; browser credentials are
|
||||
often machine- and user-encrypted.
|
||||
|
||||
## Security Rules
|
||||
|
||||
- Never expose managed VNC directly to the public internet.
|
||||
- Do not expose managed VNC directly on a Tailscale interface.
|
||||
- Prefer SSH local forwarding such as
|
||||
`localhost:5901 -> 127.0.0.1:5900`.
|
||||
- Generate per-lease passwords for managed desktop leases.
|
||||
- Redact passwords from logs, provider metadata, and run records.
|
||||
- Keep TTL and idle-timeout cleanup in force.
|
||||
- Require `--host-managed` before opening static-host VNC prompts.
|
||||
|
||||
## Where To Go Next
|
||||
|
||||
- [Linux VNC](vnc-linux.md): Hetzner/AWS Linux desktop services and static Linux.
|
||||
- [Windows VNC](vnc-windows.md): AWS Windows, native Windows static hosts, and WSL2 boundaries.
|
||||
- [macOS VNC](vnc-macos.md): AWS EC2 Mac and static Mac Screen Sharing.
|
||||
- [AWS](aws.md): AWS target matrix, capacity, AMIs, and EC2 Mac host requirements.
|
||||
- [Hetzner](hetzner.md): Linux-only managed Hetzner behavior.
|
||||
- [Blacksmith Testbox](blacksmith-testbox.md): delegated Testbox behavior and why VNC is not a Crabbox feature there yet.
|
||||
- [vnc command](../commands/vnc.md), [webvnc command](../commands/webvnc.md), [screenshot command](../commands/screenshot.md), [desktop command](../commands/desktop.md).
|
||||
|
||||
@ -10,7 +10,7 @@ Crabbox currently supports two brokered providers:
|
||||
|
||||
```text
|
||||
hetzner Hetzner Cloud servers
|
||||
aws AWS EC2 one-time Spot instances
|
||||
aws AWS EC2 instances
|
||||
```
|
||||
|
||||
Brokered Hetzner leases are Linux targets. Brokered AWS supports Linux, native
|
||||
@ -21,7 +21,13 @@ still exists for reusing existing macOS and Windows machines:
|
||||
ssh Existing SSH host selected by static.host
|
||||
```
|
||||
|
||||
Hetzner behavior:
|
||||
## Provider Pages
|
||||
|
||||
- [AWS](aws.md): EC2 Linux, Windows, WSL2, EC2 Mac, capacity, AMIs, and security groups.
|
||||
- [Hetzner](hetzner.md): Linux-only managed provider behavior, classes, and cleanup.
|
||||
- [Blacksmith Testbox](blacksmith-testbox.md): delegated Testbox backend behavior.
|
||||
|
||||
## Hetzner Summary
|
||||
|
||||
- imports or reuses the lease SSH key;
|
||||
- creates a server with Crabbox labels;
|
||||
@ -29,12 +35,12 @@ Hetzner behavior:
|
||||
- falls back across class server types when capacity or quota rejects a request;
|
||||
- fetches server-type hourly prices when cost estimates need provider pricing.
|
||||
|
||||
AWS behavior:
|
||||
## AWS Summary
|
||||
|
||||
- signs EC2 Query API calls inside the Worker;
|
||||
- imports or reuses an EC2 key pair;
|
||||
- creates or reuses the `crabbox-runners` security group with SSH ingress limited to configured CIDRs or the request source IP;
|
||||
- launches one-time Spot instances;
|
||||
- launches one-time Linux Spot or On-Demand instances;
|
||||
- launches AWS Windows Server desktop leases with EC2Launch PowerShell user
|
||||
data, OpenSSH, Git for Windows, and TightVNC when `target=windows`;
|
||||
- launches EC2 Mac leases only with an explicit Dedicated Host id
|
||||
@ -147,6 +153,8 @@ contract and needs `git`, `rsync`, `tar`, and SSH.
|
||||
Related docs:
|
||||
|
||||
- [Infrastructure](../infrastructure.md)
|
||||
- [AWS](aws.md)
|
||||
- [Hetzner](hetzner.md)
|
||||
- [Tailscale](tailscale.md)
|
||||
- [Blacksmith Testbox](blacksmith-testbox.md)
|
||||
- [Runner bootstrap](runner-bootstrap.md)
|
||||
|
||||
87
docs/features/vnc-linux.md
Normal file
87
docs/features/vnc-linux.md
Normal file
@ -0,0 +1,87 @@
|
||||
# Linux VNC
|
||||
|
||||
Read when:
|
||||
|
||||
- using `--desktop` on Hetzner or AWS Linux;
|
||||
- debugging Xvfb, XFCE/Openbox, x11vnc, or screenshots on a Linux lease;
|
||||
- preparing a static Linux host for Crabbox VNC.
|
||||
|
||||
Linux is the simplest managed desktop path. Hetzner and AWS Linux leases use
|
||||
the same bootstrap shape: install a lightweight desktop, run it on `DISPLAY=:99`,
|
||||
bind x11vnc to loopback, and let the CLI create an SSH tunnel.
|
||||
|
||||
## Managed Linux
|
||||
|
||||
```sh
|
||||
crabbox warmup --desktop --browser
|
||||
crabbox run --id blue-lobster --desktop --browser -- google-chrome --version
|
||||
crabbox vnc --id blue-lobster --open
|
||||
crabbox screenshot --id blue-lobster --output linux.png
|
||||
```
|
||||
|
||||
Managed Linux desktop leases include:
|
||||
|
||||
- Xvfb on `:99`;
|
||||
- a lightweight desktop/window-manager session;
|
||||
- x11vnc bound to `127.0.0.1:5900`;
|
||||
- a generated per-lease VNC password at `/var/lib/crabbox/vnc.password`;
|
||||
- optional Chrome stable or Chromium fallback when `--browser` is requested;
|
||||
- readiness checks that verify desktop services when `desktop=true`.
|
||||
|
||||
`crabbox run --desktop` injects `CRABBOX_DESKTOP=1` and `DISPLAY=:99`.
|
||||
`crabbox run --browser` injects `CRABBOX_BROWSER=1`, `BROWSER`, and
|
||||
`CHROME_BIN` after probing the target.
|
||||
|
||||
## Static Linux
|
||||
|
||||
Static Linux is host-managed. Crabbox does not install packages or start a
|
||||
desktop service on an existing machine. The host must already provide a VNC
|
||||
service reachable from SSH loopback:
|
||||
|
||||
```yaml
|
||||
provider: ssh
|
||||
target: linux
|
||||
static:
|
||||
host: linux-box.tailnet-name.ts.net
|
||||
user: crabbox
|
||||
port: "22"
|
||||
workRoot: /home/crabbox/work
|
||||
```
|
||||
|
||||
```sh
|
||||
crabbox vnc --provider ssh --target linux --static-host linux-box.tailnet-name.ts.net
|
||||
```
|
||||
|
||||
For static Linux, keep x11vnc or another VNC server bound to
|
||||
`127.0.0.1:5900`. Direct `host:5900` is accepted only when reachable and should
|
||||
be limited to a trusted LAN or tailnet.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
`lease ... was not created with desktop=true`
|
||||
|
||||
Warm a new lease with `--desktop`; existing leases do not gain the capability
|
||||
after creation.
|
||||
|
||||
`target=linux does not expose a loopback VNC desktop`
|
||||
|
||||
For managed leases, inspect cloud-init and service logs or warm a fresh box.
|
||||
For static hosts, start Xvfb/desktop services and x11vnc on
|
||||
`127.0.0.1:5900`.
|
||||
|
||||
Black screen
|
||||
|
||||
Check that the app was launched into `DISPLAY=:99`. For detached browser work,
|
||||
use:
|
||||
|
||||
```sh
|
||||
crabbox desktop launch --id blue-lobster --browser --url https://example.com
|
||||
```
|
||||
|
||||
Related docs:
|
||||
|
||||
- [Interactive desktop and VNC](interactive-desktop-vnc.md)
|
||||
- [Hetzner](hetzner.md)
|
||||
- [AWS](aws.md)
|
||||
- [vnc command](../commands/vnc.md)
|
||||
- [screenshot command](../commands/screenshot.md)
|
||||
88
docs/features/vnc-macos.md
Normal file
88
docs/features/vnc-macos.md
Normal file
@ -0,0 +1,88 @@
|
||||
# macOS VNC
|
||||
|
||||
Read when:
|
||||
|
||||
- launching managed AWS EC2 Mac desktop leases;
|
||||
- preparing a static Mac for Crabbox VNC;
|
||||
- debugging Screen Sharing credentials or EC2 Mac host requirements.
|
||||
|
||||
Crabbox supports macOS in two ways:
|
||||
|
||||
- managed AWS EC2 Mac leases on an operator-provided Dedicated Host;
|
||||
- static Macs reached through `provider: ssh`.
|
||||
|
||||
## Managed AWS EC2 Mac
|
||||
|
||||
```sh
|
||||
CRABBOX_AWS_MAC_HOST_ID=h-... \
|
||||
crabbox warmup --provider aws --target macos --desktop --market on-demand
|
||||
crabbox vnc --id silver-squid --open
|
||||
crabbox screenshot --id silver-squid --output macos.png
|
||||
```
|
||||
|
||||
EC2 Mac requirements:
|
||||
|
||||
- an allocated EC2 Mac Dedicated Host in the selected region;
|
||||
- `CRABBOX_AWS_MAC_HOST_ID` or `aws.macHostId`;
|
||||
- On-Demand capacity;
|
||||
- the default `mac2.metal` instance type unless `--type` is set.
|
||||
|
||||
Bootstrap enables Screen Sharing for `ec2-user`, sets a generated per-lease
|
||||
password, stores it at `/var/db/crabbox/vnc.password`, and keeps access behind
|
||||
the SSH tunnel. `crabbox vnc` prints:
|
||||
|
||||
```text
|
||||
macos username: ec2-user
|
||||
macos password: ...
|
||||
```
|
||||
|
||||
AWS EC2 Mac has a provider-level lifecycle constraint: Mac instances run on
|
||||
allocated Dedicated Hosts with a 24-hour minimum host allocation period.
|
||||
Crabbox launches onto a host id you provide; it does not allocate, scrub, or
|
||||
retire Mac hosts for you.
|
||||
|
||||
## Static Mac
|
||||
|
||||
Static Mac targets are existing machines:
|
||||
|
||||
```yaml
|
||||
provider: ssh
|
||||
target: macos
|
||||
static:
|
||||
host: mac-studio.tailnet-name.ts.net
|
||||
user: steipete
|
||||
port: "22"
|
||||
workRoot: /Users/steipete/crabbox
|
||||
```
|
||||
|
||||
```sh
|
||||
crabbox vnc --provider ssh --target macos --static-host mac-studio.tailnet-name.ts.net --host-managed --open
|
||||
```
|
||||
|
||||
The Mac must already have SSH, `git`, `rsync`, `tar`, and Screen Sharing or a
|
||||
VNC-compatible service. Credentials are host-managed. `--open` requires
|
||||
`--host-managed` because the visible login prompt belongs to that Mac, not to a
|
||||
Crabbox-created cloud lease.
|
||||
|
||||
Static Macs work well over Tailscale: put the MagicDNS name or 100.x address in
|
||||
`static.host` and keep Screen Sharing limited to trusted networks.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
Missing host id
|
||||
|
||||
Set `CRABBOX_AWS_MAC_HOST_ID` or `aws.macHostId`, use `--market on-demand`, and
|
||||
verify the Dedicated Host is allocated in the selected AWS region.
|
||||
|
||||
VNC prompt asks for host credentials
|
||||
|
||||
If `managed: false`, you opened a static Mac. Use the Mac's own Screen Sharing
|
||||
credentials. Managed AWS EC2 Mac leases print the generated `ec2-user`
|
||||
password.
|
||||
|
||||
Related docs:
|
||||
|
||||
- [Interactive desktop and VNC](interactive-desktop-vnc.md)
|
||||
- [AWS](aws.md)
|
||||
- [vnc command](../commands/vnc.md)
|
||||
- [screenshot command](../commands/screenshot.md)
|
||||
111
docs/features/vnc-windows.md
Normal file
111
docs/features/vnc-windows.md
Normal file
@ -0,0 +1,111 @@
|
||||
# Windows VNC
|
||||
|
||||
Read when:
|
||||
|
||||
- using managed AWS Windows desktop leases;
|
||||
- choosing between native Windows and WSL2;
|
||||
- preparing a static Windows host for Crabbox VNC.
|
||||
|
||||
Crabbox has two Windows execution contracts:
|
||||
|
||||
- native Windows: PowerShell over OpenSSH, archive sync, Windows desktop;
|
||||
- WSL2: POSIX commands through WSL, Linux-style sync, no separate managed VNC
|
||||
contract beyond the underlying Windows host.
|
||||
|
||||
Managed Windows desktop support is AWS-only.
|
||||
|
||||
## Managed AWS Windows
|
||||
|
||||
```sh
|
||||
crabbox warmup --provider aws --target windows --desktop
|
||||
crabbox vnc --id crimson-crab --open
|
||||
crabbox screenshot --id crimson-crab --output windows.png
|
||||
```
|
||||
|
||||
Bootstrap flow:
|
||||
|
||||
- EC2Launch v2 enables the first OpenSSH foothold on port `22`.
|
||||
- Crabbox installs Git for Windows and TightVNC.
|
||||
- Crabbox creates a local `crabbox` administrator.
|
||||
- Windows auto-logon starts a visible console session for that user.
|
||||
- The generated password is stored at
|
||||
`C:\ProgramData\crabbox\vnc.password`.
|
||||
- VNC remains reachable only through the SSH tunnel.
|
||||
|
||||
`crabbox vnc` prints both the VNC password and the generated Windows console
|
||||
login:
|
||||
|
||||
```text
|
||||
windows username: crabbox
|
||||
windows password: ...
|
||||
```
|
||||
|
||||
That login belongs to the Crabbox-created EC2 instance. It is not your local
|
||||
Windows account and is not stored in coordinator history.
|
||||
|
||||
## WSL2
|
||||
|
||||
Managed AWS WSL2 leases are Windows instances with nested virtualization
|
||||
enabled and an Ubuntu rootfs imported into WSL. Commands and sync use the POSIX
|
||||
WSL contract:
|
||||
|
||||
```sh
|
||||
crabbox warmup --provider aws --target windows --windows-mode wsl2
|
||||
crabbox run --id blue-lobster -- pnpm test
|
||||
```
|
||||
|
||||
Use native Windows mode when you need the Windows desktop. Use WSL2 when you
|
||||
need Linux tooling on Windows-capable AWS instance families.
|
||||
|
||||
## Static Windows
|
||||
|
||||
Static Windows is host-managed:
|
||||
|
||||
```yaml
|
||||
provider: ssh
|
||||
target: windows
|
||||
windows:
|
||||
mode: normal
|
||||
static:
|
||||
host: win-dev.local
|
||||
user: Peter
|
||||
port: "22"
|
||||
workRoot: C:\crabbox
|
||||
```
|
||||
|
||||
```sh
|
||||
crabbox vnc --provider ssh --target windows --static-host win-dev.local --host-managed --open
|
||||
```
|
||||
|
||||
The static host must already have OpenSSH Server, PowerShell, Git, `tar`, a
|
||||
writable `static.workRoot`, and a VNC-compatible service. `--open` requires
|
||||
`--host-managed` because the visible password prompt belongs to that durable
|
||||
host, not to a Crabbox-created lease.
|
||||
|
||||
For static WSL2, set `windows.mode: wsl2` and use a WSL path such as
|
||||
`/home/peter/crabbox` for `static.workRoot`.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
Tunnel command uses port `22`
|
||||
|
||||
Expected for AWS Windows. EC2Launch enables OpenSSH on port `22`, and Crabbox
|
||||
records the working SSH port after probing fallbacks.
|
||||
|
||||
Screenshot is black from raw SSH
|
||||
|
||||
Use `crabbox screenshot`. It runs a scheduled task inside the logged-in console
|
||||
session; an ad hoc non-interactive SSH PowerShell session cannot reliably
|
||||
capture the visible desktop.
|
||||
|
||||
VNC opens an OS credential prompt
|
||||
|
||||
Check `managed:` in `crabbox vnc` output. If it is `false`, you opened a static
|
||||
host. Use that host's credentials and pass `--host-managed` intentionally.
|
||||
|
||||
Related docs:
|
||||
|
||||
- [Interactive desktop and VNC](interactive-desktop-vnc.md)
|
||||
- [AWS](aws.md)
|
||||
- [vnc command](../commands/vnc.md)
|
||||
- [screenshot command](../commands/screenshot.md)
|
||||
@ -28,7 +28,7 @@ Cloud machines are vanilla Ubuntu runners that hold no broker secrets. They are
|
||||
| | provider API
|
||||
| v
|
||||
| +------------------------------+
|
||||
| SSH (primary + fallback) | Hetzner Cloud / AWS Spot |
|
||||
| SSH (primary + fallback) | Hetzner Cloud / AWS EC2 |
|
||||
+----------- rsync ------------> | Ubuntu runner |
|
||||
| /work/crabbox/<lease>/<repo> |
|
||||
+------------------------------+
|
||||
@ -42,8 +42,8 @@ The CLI talks to the broker over HTTPS, then talks **directly** to the leased ru
|
||||
|:------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| **CLI** | config + flags; per-lease SSH key; SSH readiness; Git seeding + rsync; sync fingerprints + sanity checks; remote command + streaming; heartbeats; release |
|
||||
| **Broker** | request auth + identity; serialized lease state; provider credentials; machine create/delete; lease expiry; pool/status/inspect; usage; spend caps |
|
||||
| **Provider** | raw compute: Hetzner Cloud servers or AWS EC2 Spot instances |
|
||||
| **Runner** | nothing durable for brokered boxes: Ubuntu prepared by cloud-init with SSH, Git, rsync, curl, jq, `/work/crabbox`; static macOS/Windows targets are existing SSH hosts; project runtimes come from repo-owned setup |
|
||||
| **Provider** | raw compute: Hetzner Cloud servers or AWS EC2 instances |
|
||||
| **Runner** | nothing durable for brokered boxes: Linux prepared by cloud-init with SSH, Git, rsync, curl, jq, `/work/crabbox`; AWS Windows/WSL2/macOS targets have provider-specific bootstrap; static targets are existing SSH hosts; project runtimes come from repo-owned setup |
|
||||
|
||||
## What `crabbox run` does
|
||||
|
||||
|
||||
@ -184,9 +184,9 @@ Current direct-CLI status:
|
||||
- SSH prefers the configured primary port, default `2222`, and then tries `ssh.fallbackPorts`, default `["22"]`. Set `ssh.fallbackPorts: []` or `CRABBOX_SSH_FALLBACK_PORTS=none` to disable fallback dialing/opening.
|
||||
- The verified kept lease was `cbx_f782c469c9ce` on server `128694755`, `cpx62`, `188.245.91.84`.
|
||||
|
||||
## AWS EC2 Spot
|
||||
## AWS EC2
|
||||
|
||||
Use AWS as the first non-Hetzner burst backend. The Cloudflare coordinator brokers AWS EC2 Spot by default; the CLI direct provider remains available with `--provider aws` when no broker is configured.
|
||||
Use AWS as the first non-Hetzner burst backend. The Cloudflare coordinator brokers AWS EC2 Spot by default for Linux, can launch managed Windows and WSL2 targets, and can launch EC2 Mac instances on an operator-provided Dedicated Host. The CLI direct provider remains available with `--provider aws` when no broker is configured.
|
||||
|
||||
Brokered AWS credentials live as Worker secrets:
|
||||
|
||||
@ -194,6 +194,7 @@ Brokered AWS credentials live as Worker secrets:
|
||||
AWS_ACCESS_KEY_ID
|
||||
AWS_SECRET_ACCESS_KEY
|
||||
AWS_SESSION_TOKEN optional
|
||||
CRABBOX_AWS_MAC_HOST_ID optional; required only for brokered target=macos
|
||||
```
|
||||
|
||||
Direct fallback env is whatever the AWS SDK can resolve, such as:
|
||||
@ -209,16 +210,17 @@ AWS-specific Crabbox env:
|
||||
|
||||
```text
|
||||
CRABBOX_AWS_REGION default eu-west-1
|
||||
CRABBOX_AWS_AMI optional Ubuntu 24.04 x86_64 AMI override
|
||||
CRABBOX_AWS_AMI optional AMI override for selected AWS target
|
||||
CRABBOX_AWS_SECURITY_GROUP_ID optional security group override
|
||||
CRABBOX_AWS_SUBNET_ID optional subnet override
|
||||
CRABBOX_AWS_INSTANCE_PROFILE optional IAM instance profile name
|
||||
CRABBOX_AWS_ROOT_GB default 400
|
||||
CRABBOX_AWS_SSH_CIDRS optional comma-separated SSH source CIDRs
|
||||
CRABBOX_AWS_MAC_HOST_ID EC2 Mac Dedicated Host id for target=macos
|
||||
CRABBOX_SSH_FALLBACK_PORTS optional comma-separated SSH fallback ports, or none
|
||||
```
|
||||
|
||||
The AWS provider imports the local SSH public key as an EC2 key pair when needed, creates or reuses a `crabbox-runners` security group when no security group is supplied, launches one-time Spot instances, tags instances and volumes with Crabbox lease metadata, and terminates non-kept instances after the command.
|
||||
The AWS provider imports the local SSH public key as an EC2 key pair when needed, creates or reuses a `crabbox-runners` security group when no security group is supplied, launches one-time EC2 instances, tags instances and volumes with Crabbox lease metadata, and terminates non-kept instances after the command.
|
||||
|
||||
Grant the Worker AWS principal EC2 launch/list/tag/terminate permissions plus
|
||||
`servicequotas:GetServiceQuota`. Service Quotas access is best-effort: when it
|
||||
@ -258,20 +260,27 @@ classes:
|
||||
|
||||
Current AWS defaults:
|
||||
|
||||
```yaml
|
||||
classes:
|
||||
standard:
|
||||
provider: aws
|
||||
serverTypes: [c7a.8xlarge, c7a.4xlarge]
|
||||
fast:
|
||||
provider: aws
|
||||
serverTypes: [c7a.16xlarge, c7a.12xlarge, c7a.8xlarge]
|
||||
large:
|
||||
provider: aws
|
||||
serverTypes: [c7a.24xlarge, c7a.16xlarge, c7a.12xlarge]
|
||||
beast:
|
||||
provider: aws
|
||||
serverTypes: [c7a.48xlarge, c7a.32xlarge, c7a.24xlarge, c7a.16xlarge]
|
||||
```text
|
||||
AWS Linux
|
||||
standard c7a.8xlarge, c7i.8xlarge, m7a.8xlarge, m7i.8xlarge, c7a.4xlarge
|
||||
fast c7a.16xlarge, c7i.16xlarge, m7a.16xlarge, m7i.16xlarge, c7a.12xlarge, c7a.8xlarge
|
||||
large c7a.24xlarge, c7i.24xlarge, m7a.24xlarge, m7i.24xlarge, r7a.24xlarge, c7a.16xlarge, c7a.12xlarge
|
||||
beast c7a.48xlarge, c7i.48xlarge, m7a.48xlarge, m7i.48xlarge, r7a.48xlarge, c7a.32xlarge, c7i.32xlarge, m7a.32xlarge, c7a.24xlarge, c7a.16xlarge
|
||||
|
||||
AWS Windows
|
||||
standard m7i.large, m7a.large, t3.large
|
||||
fast m7i.xlarge, m7a.xlarge, t3.xlarge
|
||||
large m7i.2xlarge, m7a.2xlarge, t3.2xlarge
|
||||
beast m7i.4xlarge, m7a.4xlarge, m7i.2xlarge
|
||||
|
||||
AWS Windows WSL2
|
||||
standard m8i.large, m8i-flex.large, c8i.large, r8i.large
|
||||
fast m8i.xlarge, m8i-flex.xlarge, c8i.xlarge, r8i.xlarge
|
||||
large m8i.2xlarge, m8i-flex.2xlarge, c8i.2xlarge, r8i.2xlarge
|
||||
beast m8i.4xlarge, m8i-flex.4xlarge, c8i.4xlarge, r8i.4xlarge, m8i.2xlarge
|
||||
|
||||
AWS macOS
|
||||
all mac2.metal unless `--type` is set
|
||||
```
|
||||
|
||||
Profiles choose a default class, and commands can override with `--class`.
|
||||
@ -318,7 +327,9 @@ HETZNER_TOKEN
|
||||
AWS_ACCESS_KEY_ID
|
||||
AWS_SECRET_ACCESS_KEY
|
||||
AWS_SESSION_TOKEN optional
|
||||
CRABBOX_AWS_MAC_HOST_ID optional; required only for brokered target=macos
|
||||
CRABBOX_SHARED_TOKEN
|
||||
CRABBOX_ADMIN_TOKEN optional; required for admin routes and image promotion
|
||||
CRABBOX_GITHUB_CLIENT_ID
|
||||
CRABBOX_GITHUB_CLIENT_SECRET
|
||||
CRABBOX_GITHUB_ALLOWED_ORG
|
||||
@ -326,6 +337,13 @@ CRABBOX_GITHUB_ALLOWED_ORGS optional
|
||||
CRABBOX_GITHUB_ALLOWED_TEAMS optional
|
||||
CRABBOX_DEFAULT_ORG
|
||||
CRABBOX_SESSION_SECRET
|
||||
CRABBOX_ACCESS_TEAM_DOMAIN
|
||||
CRABBOX_ACCESS_AUD
|
||||
CRABBOX_TAILSCALE_ENABLED optional
|
||||
CRABBOX_TAILSCALE_CLIENT_ID optional; required for brokered --tailscale
|
||||
CRABBOX_TAILSCALE_CLIENT_SECRET optional; required for brokered --tailscale
|
||||
CRABBOX_TAILSCALE_TAILNET optional
|
||||
CRABBOX_TAILSCALE_TAGS optional
|
||||
```
|
||||
|
||||
## Verified OpenClaw Run
|
||||
|
||||
@ -97,6 +97,26 @@ AWS_ACCESS_KEY_ID
|
||||
AWS_SECRET_ACCESS_KEY
|
||||
```
|
||||
|
||||
Conditional Worker secrets and settings:
|
||||
|
||||
```text
|
||||
AWS_SESSION_TOKEN optional
|
||||
CRABBOX_AWS_MAC_HOST_ID required only for brokered target=macos
|
||||
CRABBOX_ADMIN_TOKEN required for admin routes and image promotion
|
||||
CRABBOX_GITHUB_CLIENT_ID required for browser login
|
||||
CRABBOX_GITHUB_CLIENT_SECRET required for browser login
|
||||
CRABBOX_SESSION_SECRET required for browser login
|
||||
CRABBOX_GITHUB_ALLOWED_ORG or CRABBOX_GITHUB_ALLOWED_ORGS
|
||||
CRABBOX_GITHUB_ALLOWED_TEAMS optional
|
||||
CRABBOX_ACCESS_TEAM_DOMAIN required for Access JWT verification
|
||||
CRABBOX_ACCESS_AUD required for Access JWT verification
|
||||
CRABBOX_TAILSCALE_CLIENT_ID required for brokered --tailscale
|
||||
CRABBOX_TAILSCALE_CLIENT_SECRET required for brokered --tailscale
|
||||
CRABBOX_TAILSCALE_TAILNET optional
|
||||
CRABBOX_TAILSCALE_TAGS optional
|
||||
CRABBOX_TAILSCALE_ENABLED optional; set 0 to disable brokered Tailscale
|
||||
```
|
||||
|
||||
Cost-control secrets and settings:
|
||||
|
||||
```text
|
||||
|
||||
@ -12,7 +12,7 @@ This page maps user-facing behavior back to implementation files. Keep docs desc
|
||||
|
||||
- Command router and top-level help: `internal/cli/app.go`
|
||||
- Shared flag parsing and exit helpers: `internal/cli/flags.go`, `internal/cli/errors.go`
|
||||
- Config defaults, YAML keys, env overrides, target selection, and class maps: `internal/cli/config.go`, `internal/cli/target.go`
|
||||
- Config defaults, YAML keys, env overrides, target selection, and class maps: `internal/cli/config.go`, `internal/cli/target.go`, `worker/src/config.ts`
|
||||
- Network target resolution and Tailscale metadata: `internal/cli/network.go`
|
||||
- `crabbox init` generated repo files: `internal/cli/init.go`
|
||||
- Login/logout/whoami/config commands: `internal/cli/auth.go`, `internal/cli/config_cmd.go`
|
||||
@ -26,7 +26,8 @@ This page maps user-facing behavior back to implementation files. Keep docs desc
|
||||
- Repo claim files and reclaim checks: `internal/cli/claim.go`
|
||||
- Direct-provider labels, safe label encoding, idle touch labels, TTL cap math: `internal/cli/provider_labels.go`
|
||||
- Coordinator client request/response structs, slug lookup, heartbeats, usage, run history: `internal/cli/coordinator.go`
|
||||
- Worker lease records, public routes, slug allocation, heartbeat expiry math, alarms: `worker/src/fleet.ts`, `worker/src/types.ts`
|
||||
- Worker env/request/record types: `worker/src/types.ts`
|
||||
- Worker lease records, public routes, slug allocation, heartbeat expiry math, alarms: `worker/src/fleet.ts`
|
||||
- Worker Tailscale OAuth auth-key minting: `worker/src/tailscale.ts`
|
||||
- Worker slug generation and provider labels: `worker/src/slug.ts`, `worker/src/provider-labels.ts`
|
||||
|
||||
@ -37,8 +38,9 @@ This page maps user-facing behavior back to implementation files. Keep docs desc
|
||||
- Static SSH macOS/Windows provider: `internal/cli/static.go`
|
||||
- Blacksmith Testbox CLI wrapper: `internal/cli/blacksmith.go`
|
||||
- Worker Hetzner provider: `worker/src/hetzner.ts`
|
||||
- Worker AWS EC2 Spot provider: `worker/src/aws.ts`
|
||||
- Worker AWS EC2 provider: `worker/src/aws.ts`
|
||||
- Worker AWS AMI create/read/promote routes: `worker/src/fleet.ts`, `worker/src/aws.ts`
|
||||
- Provider feature docs: `docs/features/aws.md`, `docs/features/hetzner.md`, `docs/features/blacksmith-testbox.md`
|
||||
- CLI cloud-init bootstrap: `internal/cli/bootstrap.go`
|
||||
- Worker cloud-init bootstrap: `worker/src/bootstrap.ts`
|
||||
- Tailscale feature contract: `docs/features/tailscale.md`
|
||||
@ -47,7 +49,7 @@ This page maps user-facing behavior back to implementation files. Keep docs desc
|
||||
- VNC tunnel command: `internal/cli/vnc.go`
|
||||
- WebVNC portal bridge: `internal/cli/webvnc.go`, `worker/src/portal.ts`, `worker/src/fleet.ts`
|
||||
- Desktop screenshot command: `internal/cli/screenshot.go`
|
||||
- Interactive desktop/VNC contract: `docs/features/interactive-desktop-vnc.md`
|
||||
- Interactive desktop/VNC contract: `docs/features/interactive-desktop-vnc.md`, `docs/features/vnc-linux.md`, `docs/features/vnc-windows.md`, `docs/features/vnc-macos.md`
|
||||
|
||||
Bootstrap is intentionally tiny unless optional lease capabilities are requested:
|
||||
OpenSSH, CA certificates, curl, Git, rsync, jq, `/work/crabbox`, cache
|
||||
@ -91,6 +93,6 @@ repository-owned setup, usually through Actions hydration or repo scripts.
|
||||
- CI gate: `.github/workflows/ci.yml`
|
||||
- Release workflow and Homebrew tap fallback: `.github/workflows/release.yml`
|
||||
- GoReleaser archives and Homebrew formula config: `.goreleaser.yaml`
|
||||
- Docs link check, site builder, and Pages deployment: `scripts/check-docs-links.mjs`, `scripts/build-docs-site.mjs`, `.github/workflows/pages.yml`
|
||||
- Docs command-surface check, link check, site builder, and Pages deployment: `scripts/check-command-docs.mjs`, `scripts/check-docs-links.mjs`, `scripts/build-docs-site.mjs`, `.github/workflows/pages.yml`
|
||||
- Live provider smoke coverage: `scripts/live-smoke.sh`
|
||||
- Live coordinator auth smoke coverage: `scripts/live-auth-smoke.sh`
|
||||
|
||||
Loading…
Reference in New Issue
Block a user