docs: add provider reference pages
This commit is contained in:
Peter Steinberger
parent
b1298621fc
commit
9680656ec9
@ -78,7 +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 or add a target:** [Providers](features/providers.md), [Provider backends](provider-backends.md), [AWS](features/aws.md), [Hetzner](features/hetzner.md), [Blacksmith Testbox](features/blacksmith-testbox.md), [Daytona](features/daytona.md), [Islo](features/islo.md), [Interactive desktop and VNC](features/interactive-desktop-vnc.md).
|
||||
- **Pick or add a target:** [Provider reference](providers/README.md), [Providers feature overview](features/providers.md), [Provider backends](provider-backends.md), [AWS](providers/aws.md), [Hetzner](providers/hetzner.md), [Static SSH](providers/ssh.md), [Blacksmith Testbox](providers/blacksmith-testbox.md), [Daytona](providers/daytona.md), [Islo](providers/islo.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).
|
||||
|
||||
|
||||
@ -30,11 +30,13 @@ islo Islo sandboxes with delegated command execution
|
||||
|
||||
## 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.
|
||||
- [Daytona](daytona.md): Daytona SDK/toolbox sandbox leases.
|
||||
- [Islo](islo.md): delegated Islo sandbox execution.
|
||||
- [Provider reference](../providers/README.md): one page per built-in backend.
|
||||
- [AWS](../providers/aws.md): EC2 Linux, Windows, WSL2, EC2 Mac, capacity, AMIs, and security groups.
|
||||
- [Hetzner](../providers/hetzner.md): Linux-only managed provider behavior, classes, and cleanup.
|
||||
- [Static SSH](../providers/ssh.md): existing Linux, macOS, and Windows SSH hosts.
|
||||
- [Blacksmith Testbox](../providers/blacksmith-testbox.md): delegated Testbox backend behavior.
|
||||
- [Daytona](../providers/daytona.md): Daytona SDK/toolbox sandbox leases.
|
||||
- [Islo](../providers/islo.md): delegated Islo sandbox execution.
|
||||
- [Provider backends](../provider-backends.md): implementation guide for adding a new provider/backend/plugin.
|
||||
|
||||
## Hetzner Summary
|
||||
@ -172,11 +174,12 @@ contract and needs `git`, `rsync`, `tar`, and SSH.
|
||||
Related docs:
|
||||
|
||||
- [Infrastructure](../infrastructure.md)
|
||||
- [AWS](aws.md)
|
||||
- [Hetzner](hetzner.md)
|
||||
- [Provider reference](../providers/README.md)
|
||||
- [AWS](../providers/aws.md)
|
||||
- [Hetzner](../providers/hetzner.md)
|
||||
- [Tailscale](tailscale.md)
|
||||
- [Blacksmith Testbox](blacksmith-testbox.md)
|
||||
- [Daytona](daytona.md)
|
||||
- [Islo](islo.md)
|
||||
- [Blacksmith Testbox](../providers/blacksmith-testbox.md)
|
||||
- [Daytona](../providers/daytona.md)
|
||||
- [Islo](../providers/islo.md)
|
||||
- [Runner bootstrap](runner-bootstrap.md)
|
||||
- [Cost and usage](cost-usage.md)
|
||||
|
||||
77
docs/providers/README.md
Normal file
77
docs/providers/README.md
Normal file
@ -0,0 +1,77 @@
|
||||
# Provider Reference
|
||||
|
||||
Read when:
|
||||
|
||||
- choosing a Crabbox provider for a repo or one-off command;
|
||||
- debugging provider-specific provisioning, sync, or command execution;
|
||||
- changing provider registration, flags, config, or backend behavior.
|
||||
|
||||
Crabbox supports managed SSH lease providers, delegated run providers, and one
|
||||
static SSH provider for existing machines.
|
||||
|
||||
| Provider | Backend kind | Targets | Best for |
|
||||
| --- | --- | --- | --- |
|
||||
| [AWS](aws.md) | SSH lease | Linux, Windows, macOS | broad managed capacity, Windows, EC2 Mac |
|
||||
| [Hetzner](hetzner.md) | SSH lease | Linux | fast Linux capacity at low cost |
|
||||
| [Static SSH](ssh.md) | SSH lease | Linux, macOS, Windows | reusing an existing host |
|
||||
| [Blacksmith Testbox](blacksmith-testbox.md) | delegated run | Linux | existing Blacksmith Testbox workflows |
|
||||
| [Daytona](daytona.md) | hybrid delegated run + SSH | Linux | Daytona snapshot sandboxes |
|
||||
| [Islo](islo.md) | delegated run | Linux | Islo-owned sandbox execution |
|
||||
|
||||
## Shared Rules
|
||||
|
||||
Core Crabbox owns provider selection, config loading, friendly slugs, local repo
|
||||
claims, timing summaries, command rendering, and normalized list/status output.
|
||||
Providers own only their backend boundary: provisioning or delegated command
|
||||
execution.
|
||||
|
||||
Use `--provider <name>` for one command, or set `provider: <name>` in Crabbox
|
||||
config. Provider flags are registered by provider packages before command-line
|
||||
parsing, so provider-specific flags work even when that provider is not the
|
||||
default.
|
||||
|
||||
```sh
|
||||
crabbox warmup --provider aws --class beast
|
||||
crabbox run --provider hetzner -- pnpm test
|
||||
crabbox run --provider blacksmith-testbox --id tbx_123 -- pnpm test
|
||||
```
|
||||
|
||||
## Brokered Versus Direct
|
||||
|
||||
AWS and Hetzner can run through the Crabbox coordinator or directly from the CLI.
|
||||
Coordinator mode is the normal shared-team path: the Worker owns cloud
|
||||
credentials, cost state, cleanup alarms, and lease accounting.
|
||||
|
||||
Direct mode is for local operator debugging or non-brokered setups. It uses local
|
||||
provider credentials and best-effort cleanup through provider labels.
|
||||
|
||||
Delegated providers do not use the Crabbox coordinator:
|
||||
|
||||
- Blacksmith uses the authenticated Blacksmith CLI.
|
||||
- Daytona uses Daytona API and SDK/toolbox APIs.
|
||||
- Islo uses the Islo API and SDK auth.
|
||||
|
||||
## Feature Matrix
|
||||
|
||||
| Provider | `run` | `warmup` | `ssh` | VNC/code | Crabbox sync | Provider sync |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| AWS | yes | yes | yes | yes | yes | no |
|
||||
| Hetzner | yes | yes | yes | Linux VNC/code | yes | no |
|
||||
| Static SSH | yes | resolves host | yes | host-dependent | yes | no |
|
||||
| Blacksmith Testbox | yes | yes | no | no | no | yes |
|
||||
| Daytona | yes | yes | yes | no | archive via Daytona toolbox | no |
|
||||
| Islo | yes | yes | no | no | no | yes |
|
||||
|
||||
Actions runner hydration requires a normal SSH lease on Linux and is core-over-SSH.
|
||||
Use AWS, Hetzner, or Static SSH for that path.
|
||||
|
||||
## Implementation
|
||||
|
||||
Provider implementation lives under `internal/providers/<name>`. The command
|
||||
orchestration and renderer surface stays in `internal/cli`.
|
||||
|
||||
Related docs:
|
||||
|
||||
- [Provider backends](../provider-backends.md)
|
||||
- [Feature overview](../features/providers.md)
|
||||
- [Source map](../source-map.md)
|
||||
121
docs/providers/aws.md
Normal file
121
docs/providers/aws.md
Normal file
@ -0,0 +1,121 @@
|
||||
# AWS Provider
|
||||
|
||||
Read when:
|
||||
|
||||
- choosing `provider: aws`;
|
||||
- debugging EC2 capacity, quotas, AMIs, security groups, or EC2 Mac hosts;
|
||||
- changing `internal/providers/aws` or brokered AWS provisioning.
|
||||
|
||||
AWS is the broad managed provider. It supports Linux, native Windows, Windows
|
||||
WSL2, and EC2 Mac leases. The backend is an SSH lease provider: after
|
||||
provisioning, Crabbox owns SSH readiness, sync, command execution, results,
|
||||
desktop tunnels, and cleanup.
|
||||
|
||||
## When To Use
|
||||
|
||||
Use AWS when you need:
|
||||
|
||||
- managed Windows or WSL2 test machines;
|
||||
- EC2 Mac desktops through a configured Dedicated Host;
|
||||
- broad Linux capacity with Spot and On-Demand fallback;
|
||||
- coordinator-owned cloud credentials and cost accounting.
|
||||
|
||||
Use Hetzner for cheaper Linux-only capacity. Use Static SSH when a known host
|
||||
already exists.
|
||||
|
||||
## Commands
|
||||
|
||||
```sh
|
||||
crabbox warmup --provider aws --class beast
|
||||
crabbox run --provider aws --class beast -- pnpm test
|
||||
crabbox run --provider aws --market on-demand -- pnpm check
|
||||
crabbox warmup --provider aws --target windows --desktop
|
||||
crabbox warmup --provider aws --target windows --windows-mode wsl2
|
||||
crabbox warmup --provider aws --target macos --desktop --market on-demand
|
||||
```
|
||||
|
||||
`--type` is exact. If EC2 rejects that type, Crabbox fails instead of silently
|
||||
choosing another instance. Use `--class` when fallback is desired.
|
||||
|
||||
## Config
|
||||
|
||||
```yaml
|
||||
provider: aws
|
||||
target: linux
|
||||
class: beast
|
||||
market: spot
|
||||
aws:
|
||||
region: us-east-1
|
||||
ami: ""
|
||||
securityGroupId: ""
|
||||
subnetId: ""
|
||||
instanceProfile: ""
|
||||
rootGB: 120
|
||||
sshCIDRs: []
|
||||
```
|
||||
|
||||
Important direct-mode environment:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
Brokered AWS credentials belong in the Worker, not on developer machines.
|
||||
|
||||
## Targets
|
||||
|
||||
| Target | Notes |
|
||||
| --- | --- |
|
||||
| Linux | Ubuntu bootstrap, SSH, rsync, optional desktop/browser/code. |
|
||||
| Windows native | EC2Launch, OpenSSH, Git for Windows, TightVNC, archive sync. |
|
||||
| Windows WSL2 | Nested virtualization families; POSIX sync and commands through WSL. |
|
||||
| macOS | Requires `CRABBOX_AWS_MAC_HOST_ID` or `aws.macHostId`; On-Demand only. |
|
||||
|
||||
## Lifecycle
|
||||
|
||||
1. Import or reuse the lease SSH key.
|
||||
2. Select region, market, instance type, subnet, AMI, and security group.
|
||||
3. Launch EC2 instance, Spot request, Windows instance, or EC2 Mac host-backed
|
||||
instance.
|
||||
4. Tag instance, volumes, and Spot requests with Crabbox lease labels.
|
||||
5. Wait for SSH and `crabbox-ready`.
|
||||
6. Let core sync and run over SSH.
|
||||
7. Terminate on release, cleanup, or coordinator expiry.
|
||||
|
||||
Brokered cleanup is coordinator-owned. Direct cleanup is best-effort through
|
||||
provider labels and `crabbox cleanup`.
|
||||
|
||||
## Capabilities
|
||||
|
||||
- SSH: yes.
|
||||
- Crabbox sync: yes.
|
||||
- Desktop/browser/code: yes, target-dependent.
|
||||
- Tailscale: Linux managed leases.
|
||||
- Actions hydration: Linux SSH leases only.
|
||||
- Coordinator: yes.
|
||||
|
||||
## Gotchas
|
||||
|
||||
- Spot capacity and quota errors are normal. Prefer classes over exact `--type`
|
||||
when you want fallback.
|
||||
- Windows WSL2 needs nested virtualization instance families.
|
||||
- EC2 Mac needs an explicit Dedicated Host id.
|
||||
- VNC stays behind SSH tunnels; do not expose VNC ports directly.
|
||||
|
||||
Related docs:
|
||||
|
||||
- [Feature: AWS](../features/aws.md)
|
||||
- [Windows VNC](../features/vnc-windows.md)
|
||||
- [macOS VNC](../features/vnc-macos.md)
|
||||
- [Provider backends](../provider-backends.md)
|
||||
103
docs/providers/blacksmith-testbox.md
Normal file
103
docs/providers/blacksmith-testbox.md
Normal file
@ -0,0 +1,103 @@
|
||||
# Blacksmith Testbox Provider
|
||||
|
||||
Read when:
|
||||
|
||||
- choosing `provider: blacksmith-testbox`;
|
||||
- wrapping an existing Blacksmith Testbox workflow with Crabbox;
|
||||
- changing `internal/providers/blacksmith`.
|
||||
|
||||
Blacksmith Testbox is a delegated run provider. Crabbox does not provision,
|
||||
bootstrap, rsync, or expose VNC for the remote machine. It shells out to the
|
||||
authenticated Blacksmith CLI and keeps Crabbox ergonomics around IDs, slugs,
|
||||
repo claims, timing, and normalized output.
|
||||
|
||||
## When To Use
|
||||
|
||||
Use Blacksmith when the repo already has a Testbox workflow and the remote
|
||||
workspace should be owned by Blacksmith. Use AWS, Hetzner, Static SSH, or Daytona
|
||||
when Crabbox must own SSH sync and interactive access.
|
||||
|
||||
## Commands
|
||||
|
||||
Reuse an existing Testbox:
|
||||
|
||||
```sh
|
||||
crabbox run --provider blacksmith-testbox --id tbx_123 -- pnpm test
|
||||
crabbox status --provider blacksmith-testbox --id tbx_123
|
||||
crabbox stop --provider blacksmith-testbox tbx_123
|
||||
```
|
||||
|
||||
Warm a fresh Testbox:
|
||||
|
||||
```sh
|
||||
crabbox warmup \
|
||||
--provider blacksmith-testbox \
|
||||
--blacksmith-org openclaw \
|
||||
--blacksmith-workflow .github/workflows/ci-check-testbox.yml \
|
||||
--blacksmith-job test \
|
||||
--blacksmith-ref main
|
||||
```
|
||||
|
||||
`blacksmith` is accepted as an alias, but docs and scripts should prefer
|
||||
`blacksmith-testbox`.
|
||||
|
||||
## Config
|
||||
|
||||
```yaml
|
||||
provider: blacksmith-testbox
|
||||
blacksmith:
|
||||
org: openclaw
|
||||
workflow: .github/workflows/ci-check-testbox.yml
|
||||
job: test
|
||||
ref: main
|
||||
idleTimeout: 90m
|
||||
```
|
||||
|
||||
Environment variables can provide the same defaults:
|
||||
|
||||
```text
|
||||
CRABBOX_BLACKSMITH_ORG
|
||||
CRABBOX_BLACKSMITH_WORKFLOW
|
||||
CRABBOX_BLACKSMITH_JOB
|
||||
CRABBOX_BLACKSMITH_REF
|
||||
```
|
||||
|
||||
Blacksmith authentication stays in the Blacksmith CLI. Run
|
||||
`blacksmith auth login` before using this provider.
|
||||
|
||||
## Lifecycle
|
||||
|
||||
Crabbox forwards:
|
||||
|
||||
```sh
|
||||
blacksmith testbox warmup ...
|
||||
blacksmith testbox run ...
|
||||
blacksmith testbox list
|
||||
blacksmith testbox list --all
|
||||
blacksmith testbox stop ...
|
||||
```
|
||||
|
||||
Crabbox stores a per-Testbox SSH key locally, claims the Testbox for the current
|
||||
repo, maps IDs to friendly slugs, and prints a normal Crabbox timing summary.
|
||||
|
||||
## Capabilities
|
||||
|
||||
- SSH: no Crabbox SSH lease.
|
||||
- Crabbox sync: no.
|
||||
- Provider sync: yes, Blacksmith-owned.
|
||||
- Desktop/browser/code: no Crabbox VNC/code surface.
|
||||
- Actions hydration: Blacksmith-owned workflow setup, not Crabbox SSH hydration.
|
||||
- Coordinator: no.
|
||||
|
||||
## Gotchas
|
||||
|
||||
- `--sync-only`, `--checksum`, and `--force-sync-large` do not apply because
|
||||
Blacksmith owns sync.
|
||||
- `list` and `status` are core-rendered from parsed Blacksmith CLI output.
|
||||
- `blacksmith.workflow` is required only when Crabbox needs to create a Testbox.
|
||||
Reusing an existing ID or slug does not need workflow config.
|
||||
|
||||
Related docs:
|
||||
|
||||
- [Feature: Blacksmith Testbox](../features/blacksmith-testbox.md)
|
||||
- [Provider backends](../provider-backends.md)
|
||||
105
docs/providers/daytona.md
Normal file
105
docs/providers/daytona.md
Normal file
@ -0,0 +1,105 @@
|
||||
# Daytona Provider
|
||||
|
||||
Read when:
|
||||
|
||||
- choosing `provider: daytona`;
|
||||
- configuring Daytona API auth, snapshots, or SSH access;
|
||||
- changing `internal/providers/daytona`.
|
||||
|
||||
Daytona is a hybrid provider. `run` and `warmup` use Daytona SDK/toolbox APIs
|
||||
for sandbox lifecycle, archive upload, extraction, and process execution.
|
||||
Explicit `ssh` access mints a short-lived Daytona SSH token and then uses the
|
||||
normal Crabbox SSH client.
|
||||
|
||||
## When To Use
|
||||
|
||||
Use Daytona when the sandbox image should come from a Daytona snapshot and
|
||||
command execution should stay inside Daytona's toolbox APIs. Use AWS, Hetzner,
|
||||
or Static SSH when you need a normal long-lived SSH lease for Actions hydration
|
||||
or VNC/code workflows.
|
||||
|
||||
## Commands
|
||||
|
||||
```sh
|
||||
crabbox warmup --provider daytona --daytona-snapshot crabbox-ready
|
||||
crabbox run --provider daytona --daytona-snapshot crabbox-ready -- pnpm test
|
||||
crabbox run --provider daytona --id blue-lobster -- pnpm test:changed
|
||||
crabbox ssh --provider daytona --id blue-lobster
|
||||
crabbox stop --provider daytona blue-lobster
|
||||
```
|
||||
|
||||
## Auth
|
||||
|
||||
Use an API key:
|
||||
|
||||
```sh
|
||||
export DAYTONA_API_KEY=...
|
||||
```
|
||||
|
||||
or JWT auth:
|
||||
|
||||
```sh
|
||||
export DAYTONA_JWT_TOKEN=...
|
||||
export DAYTONA_ORGANIZATION_ID=...
|
||||
```
|
||||
|
||||
`DAYTONA_ORGANIZATION_ID` is required with JWT auth.
|
||||
|
||||
## Config
|
||||
|
||||
```yaml
|
||||
provider: daytona
|
||||
target: linux
|
||||
daytona:
|
||||
apiUrl: https://app.daytona.io/api
|
||||
snapshot: crabbox-ready
|
||||
target: ""
|
||||
user: daytona
|
||||
workRoot: /home/daytona/crabbox
|
||||
sshGatewayHost: ssh.app.daytona.io
|
||||
sshAccessMinutes: 30
|
||||
```
|
||||
|
||||
Provider flags:
|
||||
|
||||
```text
|
||||
--daytona-api-url
|
||||
--daytona-snapshot
|
||||
--daytona-target
|
||||
--daytona-user
|
||||
--daytona-work-root
|
||||
--daytona-ssh-gateway-host
|
||||
--daytona-ssh-access-minutes
|
||||
```
|
||||
|
||||
## Lifecycle
|
||||
|
||||
1. Create or resolve a Daytona sandbox from `daytona.snapshot`.
|
||||
2. Store Crabbox labels and local repo claims.
|
||||
3. For `run`, build the Crabbox sync manifest, create a gzipped tar archive,
|
||||
stream the archive to Daytona toolbox upload, extract it, and execute through
|
||||
Daytona process APIs.
|
||||
4. For `ssh`, request short-lived SSH access, parse Daytona's `sshCommand`, and
|
||||
redact the token in normal output.
|
||||
5. Delete the sandbox on release unless the lease is kept.
|
||||
|
||||
## Capabilities
|
||||
|
||||
- SSH: yes, explicit short-lived token access.
|
||||
- Crabbox sync: yes, archive sync through Daytona toolbox.
|
||||
- Desktop/browser/code: no current Crabbox VNC/code surface.
|
||||
- Actions hydration: no.
|
||||
- Coordinator: no.
|
||||
|
||||
## Gotchas
|
||||
|
||||
- `daytona.snapshot` is required when creating a sandbox.
|
||||
- Snapshot contents own CPU, memory, disk, and installed tooling in this mode.
|
||||
- Daytona `run` is delegated to toolbox APIs; it is not the same as core-over-SSH
|
||||
execution.
|
||||
- `--actions-runner` is rejected because it needs a normal SSH lease host.
|
||||
|
||||
Related docs:
|
||||
|
||||
- [Feature: Daytona](../features/daytona.md)
|
||||
- [Provider backends](../provider-backends.md)
|
||||
94
docs/providers/hetzner.md
Normal file
94
docs/providers/hetzner.md
Normal file
@ -0,0 +1,94 @@
|
||||
# Hetzner Provider
|
||||
|
||||
Read when:
|
||||
|
||||
- choosing `provider: hetzner`;
|
||||
- debugging Hetzner capacity, quotas, images, locations, or SSH readiness;
|
||||
- changing `internal/providers/hetzner` or brokered Hetzner provisioning.
|
||||
|
||||
Hetzner is the Linux-only managed provider. It is an SSH lease backend: Hetzner
|
||||
creates the server, then Crabbox owns SSH readiness, sync, command execution,
|
||||
VNC tunnels, results, and cleanup.
|
||||
|
||||
## When To Use
|
||||
|
||||
Use Hetzner for fast Linux CI-style work when you do not need managed Windows,
|
||||
macOS, or EC2-specific capacity controls. It is the simplest managed path for
|
||||
Linux desktop/browser leases.
|
||||
|
||||
## Commands
|
||||
|
||||
```sh
|
||||
crabbox warmup --provider hetzner --class beast
|
||||
crabbox run --provider hetzner --class standard -- pnpm test
|
||||
crabbox warmup --provider hetzner --desktop --browser
|
||||
crabbox ssh --provider hetzner --id blue-lobster
|
||||
crabbox stop --provider hetzner blue-lobster
|
||||
```
|
||||
|
||||
## Config
|
||||
|
||||
```yaml
|
||||
provider: hetzner
|
||||
target: linux
|
||||
class: beast
|
||||
hetzner:
|
||||
image: ubuntu-24.04
|
||||
location: fsn1
|
||||
sshKey: ""
|
||||
```
|
||||
|
||||
Important direct-mode environment:
|
||||
|
||||
```text
|
||||
HCLOUD_TOKEN
|
||||
HETZNER_TOKEN
|
||||
CRABBOX_HETZNER_IMAGE
|
||||
CRABBOX_HETZNER_LOCATION
|
||||
CRABBOX_HETZNER_SSH_KEY
|
||||
```
|
||||
|
||||
Brokered Hetzner credentials belong in the Worker.
|
||||
|
||||
## Lifecycle
|
||||
|
||||
1. Import or reuse the lease SSH key.
|
||||
2. Pick the configured location, image, and class server-type candidates.
|
||||
3. Create a Hetzner server with Crabbox labels.
|
||||
4. Wait for SSH and `crabbox-ready`.
|
||||
5. Let core sync and run over SSH.
|
||||
6. Delete on release, cleanup, or coordinator expiry.
|
||||
|
||||
## Classes
|
||||
|
||||
```text
|
||||
standard ccx33, cpx62, cx53
|
||||
fast ccx43, cpx62, cx53
|
||||
large ccx53, ccx43, cpx62, cx53
|
||||
beast ccx63, ccx53, ccx43, cpx62, cx53
|
||||
```
|
||||
|
||||
Explicit `--type` is exact. Class-based provisioning can fall back across the
|
||||
candidate list when Hetzner rejects capacity or quota.
|
||||
|
||||
## Capabilities
|
||||
|
||||
- SSH: yes.
|
||||
- Crabbox sync: yes.
|
||||
- Desktop/browser/code: Linux only.
|
||||
- Tailscale: Linux managed leases.
|
||||
- Actions hydration: yes, Linux SSH leases.
|
||||
- Coordinator: yes.
|
||||
|
||||
## Gotchas
|
||||
|
||||
- Hetzner does not provide managed Windows or macOS targets in Crabbox.
|
||||
- Dedicated-core types can hit account quota. Use class fallback before pinning
|
||||
exact types.
|
||||
- Direct mode has no coordinator alarm; use `crabbox cleanup`.
|
||||
|
||||
Related docs:
|
||||
|
||||
- [Feature: Hetzner](../features/hetzner.md)
|
||||
- [Linux VNC](../features/vnc-linux.md)
|
||||
- [Provider backends](../provider-backends.md)
|
||||
96
docs/providers/islo.md
Normal file
96
docs/providers/islo.md
Normal file
@ -0,0 +1,96 @@
|
||||
# Islo Provider
|
||||
|
||||
Read when:
|
||||
|
||||
- choosing `provider: islo`;
|
||||
- configuring Islo sandbox image, size, snapshot, or gateway profile;
|
||||
- changing `internal/providers/islo`.
|
||||
|
||||
Islo is a delegated run provider. Crabbox uses the Islo SDK for sandbox
|
||||
lifecycle and a streaming exec endpoint for command output. Islo owns sandbox
|
||||
state and workspace setup; Crabbox owns local config, repo claims, slugs,
|
||||
timing summaries, and normalized list/status rendering.
|
||||
|
||||
## When To Use
|
||||
|
||||
Use Islo when the remote sandbox should be owned by Islo and command execution
|
||||
should happen through Islo's API. Use AWS, Hetzner, Static SSH, or Daytona when
|
||||
you need Crabbox SSH access.
|
||||
|
||||
## Commands
|
||||
|
||||
```sh
|
||||
crabbox warmup --provider islo --islo-image docker.io/library/ubuntu:24.04
|
||||
crabbox run --provider islo -- pnpm test
|
||||
crabbox run --provider islo --id blue-lobster --shell 'pnpm install && pnpm test'
|
||||
crabbox status --provider islo --id blue-lobster
|
||||
crabbox stop --provider islo blue-lobster
|
||||
```
|
||||
|
||||
## Auth
|
||||
|
||||
```sh
|
||||
export ISLO_API_KEY=ak_...
|
||||
```
|
||||
|
||||
`ISLO_BASE_URL` or `islo.baseUrl` can override the default
|
||||
`https://api.islo.dev`.
|
||||
|
||||
## Config
|
||||
|
||||
```yaml
|
||||
provider: islo
|
||||
target: linux
|
||||
islo:
|
||||
baseUrl: https://api.islo.dev
|
||||
image: docker.io/library/ubuntu:24.04
|
||||
workdir: crabbox
|
||||
gatewayProfile: ""
|
||||
snapshotName: ""
|
||||
vcpus: 2
|
||||
memoryMB: 4096
|
||||
diskGB: 20
|
||||
```
|
||||
|
||||
Provider flags:
|
||||
|
||||
```text
|
||||
--islo-base-url
|
||||
--islo-image
|
||||
--islo-workdir
|
||||
--islo-gateway-profile
|
||||
--islo-snapshot-name
|
||||
--islo-vcpus
|
||||
--islo-memory-mb
|
||||
--islo-disk-gb
|
||||
```
|
||||
|
||||
## Lifecycle
|
||||
|
||||
1. Create or resolve a Crabbox-owned Islo sandbox.
|
||||
2. Store a local lease ID with the `isb_` prefix and a friendly slug.
|
||||
3. Execute commands through Islo's streaming exec endpoint.
|
||||
4. Require an exit event before treating a stream as successful.
|
||||
5. Delete the sandbox on release unless kept.
|
||||
|
||||
## Capabilities
|
||||
|
||||
- SSH: no.
|
||||
- Crabbox sync: no.
|
||||
- Provider sync: yes, Islo-owned.
|
||||
- Desktop/browser/code: no Crabbox VNC/code surface.
|
||||
- Actions hydration: no.
|
||||
- Coordinator: no.
|
||||
|
||||
## Gotchas
|
||||
|
||||
- `--sync-only`, `--checksum`, and `--force-sync-large` are rejected because
|
||||
Crabbox cannot apply local rsync semantics.
|
||||
- `--shell` passes the raw shell string to the remote shell path.
|
||||
- IDs can be Crabbox slugs, `isb_...` lease IDs, or Crabbox-created sandbox
|
||||
names. Non-Crabbox Islo sandboxes are rejected.
|
||||
|
||||
Related docs:
|
||||
|
||||
- [Feature: Islo](../features/islo.md)
|
||||
- [Provider backends](../provider-backends.md)
|
||||
131
docs/providers/ssh.md
Normal file
131
docs/providers/ssh.md
Normal file
@ -0,0 +1,131 @@
|
||||
# Static SSH Provider
|
||||
|
||||
Read when:
|
||||
|
||||
- choosing `provider: ssh`, `provider: static`, or `provider: static-ssh`;
|
||||
- reusing an existing Linux, macOS, or Windows host;
|
||||
- changing `internal/providers/ssh` or static-host sync behavior.
|
||||
|
||||
Static SSH is the provider for machines Crabbox does not create. The backend
|
||||
resolves a configured SSH target and then core owns sync, command execution,
|
||||
results, tunnels, and status rendering.
|
||||
|
||||
## When To Use
|
||||
|
||||
Use Static SSH when:
|
||||
|
||||
- the machine already exists and should not be provisioned by Crabbox;
|
||||
- you need a local Mac Studio, LAN host, VM, or persistent Windows box;
|
||||
- cloud provider cleanup and cost accounting do not apply.
|
||||
|
||||
Use AWS or Hetzner when you want Crabbox to create and delete the machine.
|
||||
|
||||
## Commands
|
||||
|
||||
```sh
|
||||
crabbox run --provider ssh --static-host mac-studio.local -- pnpm test
|
||||
crabbox ssh --provider ssh --id mac-studio.local
|
||||
crabbox run --provider static-ssh --target windows --static-host win-dev.local -- pwsh -NoProfile -Command '$PSVersionTable'
|
||||
```
|
||||
|
||||
`warmup` for Static SSH does not provision a new machine. It validates and
|
||||
returns the configured target as a lease-like object for common workflows.
|
||||
|
||||
## Linux Or macOS Config
|
||||
|
||||
```yaml
|
||||
provider: ssh
|
||||
target: macos
|
||||
static:
|
||||
host: mac-studio.local
|
||||
user: steipete
|
||||
port: "22"
|
||||
workRoot: /Users/steipete/crabbox
|
||||
```
|
||||
|
||||
Linux uses the same POSIX contract:
|
||||
|
||||
```yaml
|
||||
provider: ssh
|
||||
target: linux
|
||||
static:
|
||||
host: buildbox.local
|
||||
user: crabbox
|
||||
port: "22"
|
||||
workRoot: /work/crabbox
|
||||
```
|
||||
|
||||
## Windows Config
|
||||
|
||||
Native Windows mode uses PowerShell over OpenSSH and archive sync:
|
||||
|
||||
```yaml
|
||||
provider: ssh
|
||||
target: windows
|
||||
windows:
|
||||
mode: normal
|
||||
static:
|
||||
host: win-dev.local
|
||||
user: Peter
|
||||
port: "22"
|
||||
workRoot: C:\crabbox
|
||||
```
|
||||
|
||||
WSL2 mode keeps the POSIX contract inside WSL:
|
||||
|
||||
```yaml
|
||||
provider: ssh
|
||||
target: windows
|
||||
windows:
|
||||
mode: wsl2
|
||||
static:
|
||||
host: win-dev.local
|
||||
user: Peter
|
||||
port: "22"
|
||||
workRoot: /home/peter/crabbox
|
||||
```
|
||||
|
||||
## Host Requirements
|
||||
|
||||
POSIX hosts need:
|
||||
|
||||
- SSH access for the configured user;
|
||||
- `git`, `rsync`, `tar`, `sh`, and a writable `static.workRoot`;
|
||||
- optional desktop/browser/code tooling if those flags are requested.
|
||||
|
||||
Windows native hosts need:
|
||||
|
||||
- OpenSSH server;
|
||||
- PowerShell;
|
||||
- tar support for archive sync;
|
||||
- optional TightVNC/browser tooling for desktop flows.
|
||||
|
||||
WSL2 hosts need:
|
||||
|
||||
- WSL installed and reachable through `wsl.exe`;
|
||||
- Linux tools inside the default WSL distribution;
|
||||
- `static.workRoot` as a WSL path.
|
||||
|
||||
## Capabilities
|
||||
|
||||
- SSH: yes.
|
||||
- Crabbox sync: yes.
|
||||
- Desktop/browser/code: host-dependent.
|
||||
- Tailscale: use the host's existing tailnet address or MagicDNS name.
|
||||
- Actions hydration: Linux SSH hosts only.
|
||||
- Coordinator: no.
|
||||
|
||||
## Gotchas
|
||||
|
||||
- Crabbox does not clean up static hosts. `stop` removes local claims only.
|
||||
- Static hosts can drift. Run `crabbox doctor` and a small `crabbox run` before
|
||||
long jobs.
|
||||
- `target` and `windows.mode` must match the real host. Crabbox cannot infer
|
||||
whether a Windows host should run native PowerShell or WSL2 commands.
|
||||
|
||||
Related docs:
|
||||
|
||||
- [Provider overview](README.md)
|
||||
- [Sync](../features/sync.md)
|
||||
- [SSH keys](../features/ssh-keys.md)
|
||||
- [Provider backends](../provider-backends.md)
|
||||
@ -55,6 +55,7 @@ This page maps user-facing behavior back to implementation files. Keep docs desc
|
||||
- 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`, `docs/features/daytona.md`, `docs/features/islo.md`
|
||||
- Provider reference docs: `docs/providers/README.md`, `docs/providers/aws.md`, `docs/providers/hetzner.md`, `docs/providers/ssh.md`, `docs/providers/blacksmith-testbox.md`, `docs/providers/daytona.md`, `docs/providers/islo.md`
|
||||
- Provider/backend authoring guide: `docs/provider-backends.md`
|
||||
- CLI cloud-init bootstrap: `internal/cli/bootstrap.go`
|
||||
- Worker cloud-init bootstrap: `worker/src/bootstrap.ts`
|
||||
|
||||
Loading…
Reference in New Issue
Block a user