Commands

code

GitHub Edit page

code

crabbox code bridges a Linux lease's code-server workspace into the authenticated coordinator portal, so you can edit the synced checkout in a browser VS Code without exposing the runner directly.

crabbox warmup --code
crabbox code --id swift-crab
crabbox code --id swift-crab --open

#Prerequisites

  • A configured coordinator login. The command refuses to run without one:

    • crabbox login --url broker.example.com first.

  • A lease created with the code capability (crabbox warmup --code). The

    • Linux bootstrap installs code-server only for leases that request it, and reusing a lease checks for the matching code=true label.

  • A coordinator-backed Linux lease on a provider that advertises the code

    • capability (hetzner, aws, azure). Static SSH hosts, Blacksmith Testbox, Windows, and macOS leases are rejected.

#How it works

crabbox code resolves the lease, ensures code-server is running on the runner's loopback interface (127.0.0.1:8080), opens an SSH tunnel to it, mints a short-lived bridge ticket from the coordinator, and registers a local bridge process. Keep the process running while you use the editor.

The data path is:

browser
  <-> coordinator /portal/leases/<lease-id>/code/
  <-> local crabbox code process (bridge)
  <-> SSH tunnel
  <-> runner 127.0.0.1:8080 (code-server)

The coordinator authenticates the browser through portal auth and authenticates the local bridge with a one-use, short-lived ticket. The CLI sends the ticket as an X-Crabbox-Bridge-Ticket WebSocket upgrade header so it stays out of WebSocket URLs while leaving ordinary coordinator authentication intact. A bearer-header retry supports older coordinators, and the coordinator accepts query tickets only from older CLIs. Because the trusted boundary is the portal plus the bridge ticket, code-server runs with auth disabled on the runner side.

The portal URL is lease-scoped:

/portal/leases/<lease-id>/code/

If the browser opens before the local bridge connects, the Code portal renders a waiting state with the exact crabbox code command, copy/reload controls, and bridge status; it opens the workspace automatically once the bridge connects.

#Folder mapping

The editor opens the synced workspace by default. If you run crabbox code from a subdirectory of the local checkout, Crabbox maps that relative path onto the remote workspace and opens the matching folder. Actions-hydrated leases open the hydration workspace instead of the default /work/crabbox/<repo> path.

#Resilience

Managed code-server starts with Default Dark Modern as its theme. The bridge chunks large HTTP responses and websocket frames so VS Code assets and extension-host traffic stay under coordinator websocket frame limits, and it reconnects automatically on transient bridge errors.

#Flags

--id <lease-id-or-slug>     Lease to bridge (also accepted as a positional arg).
--provider hetzner|aws|azure  Provider for the lease (default from config).
--target linux              Lease target OS (code requires linux).
--network auto|tailscale|public  Network mode used to reach the runner.
--local-port <port>         Local code-server tunnel port (auto-selected 8081-8180 if unset).
--open                      Open the portal Code page in a browser.
--reclaim                   Claim this lease for the current repo checkout.

Set CRABBOX_CODE_DEBUG=1 to print bridge trace output to stderr.

#Troubleshooting

lease ... was not created with code=true — warm a new lease with the capability:

crabbox warmup --code

code requires a configured coordinator login — log in to the broker:

crabbox login --url broker.example.com

The portal shows a bridge command — the browser reached the coordinator but no local bridge is registered. Run the command the portal shows (or crabbox code --id <lease> --open) and keep it running.

Check bridge health:

curl https://broker.example.com/portal/leases/<lease-id>/code/health

When authenticated, the health response reports whether the code bridge agent is currently connected.

#See also

  • webvnc — bridge a desktop lease into the portal.
  • capabilities — --desktop, --browser, --code.
  • portal — the authenticated browser UI.