diff --git a/docs/README.md b/docs/README.md
index aad568d..16b0c6d 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -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).
 
diff --git a/docs/features/providers.md b/docs/features/providers.md
index 73f85a6..5f7e160 100644
--- a/docs/features/providers.md
+++ b/docs/features/providers.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)
diff --git a/docs/providers/README.md b/docs/providers/README.md
new file mode 100644
index 0000000..374344d
--- /dev/null
+++ b/docs/providers/README.md
@@ -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)
diff --git a/docs/providers/aws.md b/docs/providers/aws.md
new file mode 100644
index 0000000..44770a2
--- /dev/null
+++ b/docs/providers/aws.md
@@ -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)
diff --git a/docs/providers/blacksmith-testbox.md b/docs/providers/blacksmith-testbox.md
new file mode 100644
index 0000000..a8ce7db
--- /dev/null
+++ b/docs/providers/blacksmith-testbox.md
@@ -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)
diff --git a/docs/providers/daytona.md b/docs/providers/daytona.md
new file mode 100644
index 0000000..fc1cd5c
--- /dev/null
+++ b/docs/providers/daytona.md
@@ -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)
diff --git a/docs/providers/hetzner.md b/docs/providers/hetzner.md
new file mode 100644
index 0000000..92fd526
--- /dev/null
+++ b/docs/providers/hetzner.md
@@ -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)
diff --git a/docs/providers/islo.md b/docs/providers/islo.md
new file mode 100644
index 0000000..c250917
--- /dev/null
+++ b/docs/providers/islo.md
@@ -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)
diff --git a/docs/providers/ssh.md b/docs/providers/ssh.md
new file mode 100644
index 0000000..dfc2d35
--- /dev/null
+++ b/docs/providers/ssh.md
@@ -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)
diff --git a/docs/source-map.md b/docs/source-map.md
index 670fc50..9af27e9 100644
--- a/docs/source-map.md
+++ b/docs/source-map.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`