Optional sandbox workspaces

Devctrl can run an isolated Project workspace on a Boat sandbox. Use it for temporary experiments, dependency upgrades and parallel tasks that need a separate checkout. Boat is optional; local machines, SSH hosts, cloud VMs and their existing sessions keep working as before.

The adapter uses devctrl's existing session and workspace model. Creating a sandbox workspace is separate from granting a session access to the Boat external service. The limits below describe what this integration supports; Boat's broader platform may offer other features. See provider packages, Boat service grants (source access required) and the product overview.

Architecture

The existing model already separates a Host, a Project Workspace and an agent Session. The extension adds a durable ComputeResource associated with an isolated Host and Workspace:

Claude Code / Codex Session (existing launcher and tmux lifecycle)
  → Workspace (separate checkout and devcontainer)
    → Host (existing authenticated host-agent, terminal and resource relay)
      → ComputeResource (provider identity, lifetime, accounting, cleanup intent)
        → optional compute provider package

The Boat adapter uses its HTTP API to provision a sandbox and run the existing host enrollment installer. It does not call Boat's prompt endpoint or introduce separate Claude/Codex implementations. Once the host and container are ready, account login/import, session launch, detach/reattach, managed secrets, files, environment settings and terminal access use the normal devctl mechanisms. A Project can have its existing persistent workspace and a separate sandbox workspace concurrently; opening the sandbox targets its exact workspace and fails closed if it is missing.

The compute contract is capability-oriented and separate from traditional cloud-VM provisioning. Its manifest includes an execution class, Docker and persistence capabilities, supported sizes and the provider's creation-idempotency window. Boat-specific routes and state translation live exclusively in @devctl/provider-boat.

Install, remove and configure

@devctl/provider-boat is an optional package. It exports a versioned provider manifest and factory; the controller discovers optional dependencies marked devctlProvider.kind: compute through the shared provider registry. Missing or incompatible packages are isolated; they do not prevent controller startup. No Boat credentials are required to use the rest of devctrl.

The bundled distribution includes Boat as an optional dependency. To include/exclude it in a custom distribution, add/remove @devctl/provider-boat from the controller's optional dependencies and rebuild the controller image. To limit discovery explicitly, set DEVCTL_COMPUTE_PROVIDER_PACKAGES to a comma-separated list of installed module names. An empty value disables compute-provider loading. Adding a compatible package does not require changing controller or agent code.

Before removing a package, destroy its resources or keep it installed until their cleanup completes. Existing resource records and encrypted credentials remain durable when a package is unavailable; reinstalling it restores reconciliation. The provider expiry remains a final bound if the controller or package is unavailable.

In TUI or the streamed web UI, open Sandboxes, press a, choose Boat and enter its API key. Input is masked. The controller stores it using the existing encrypted credential keyring, separately from workspace grants. The key never enters sandbox metadata, the build image or a host enrollment command.

Use a Boat service key authorized for the sandbox lifecycle, commands and usage endpoints. Boat's own API-key scope and billing rules apply. Configure agent account credentials through the normal account UI after enrollment. Do not add Claude/OpenAI/Git credentials to a Boat account environment or reusable template for this integration.

Create and launch

  1. Add/import the Project and its Git repository URL in the normal interface.
  2. Open Sandboxes → a, choose the installed provider, Project, workspace name and size. default is recommended for building the host agent and a managed runtime; small has substantially less disk and memory.
  3. Choose Keep after completion or Delete when all sessions finish and an expiry limit of 300–86,400 seconds. The initial value is one hour. Both policies have this provider-enforced expiry.
  4. Enter the public HTTPS web console origin, without #key, path or other credentials. It must remain reachable from the sandbox for /join.sh, /host-source.tar and the authenticated host-agent endpoints. A temporary tunnel works while that tunnel remains available.
  5. For a private repository, explicitly select a connected Git account for the repository's hostname. Its credential is imported through the existing authenticated host-agent channel and scoped Git credential helper. Public repositories can use None. The account token is never passed through Boat's commands API.
  6. Create the sandbox. The adapter starts a sandbox with no inherited account environment and no snapshots, enrolls its host agent, checks out the repository, and queues the normal devcontainer start. The selected Git account only prepares this new workspace; it does not move the original Project or its other workspaces.
  7. When ready, open its details and press Enter to launch Claude Code or Codex through the existing Project launch wizard. Sign in/import the desired agent account normally on that host.

In details, r reconciles status; Shift+D, then Shift+D again explicitly destroys the sandbox. Closing the terminal or browser detaches; it does not destroy it.

Lifetimes and persistence

manual retains the live sandbox after a session exits, until explicit destruction or expiry. until-session-completes requests deletion only after at least one session existed and every session on that sandbox host has exited, with no active durable Agent Run, session restart or queued host cleanup. A detached, idle, waiting or failed session does not trigger automatic deletion. Multiple sessions can use the workspace.

Boat normally implements stop/resume through disk snapshots. Existing agent account homes and project secret files can contain credentials, so this integration always requests noEnv: true, snapshots: false. This disables background snapshots as well as explicit snapshots. It prevents credentials from being captured in reusable Boat images/snapshots, but means archive/expiry loses the sandbox disk. Consequently, enabled capabilities are:

Capability Enabled
Isolated sandbox with Docker and normal devcontainers Yes
Live session detach/reattach and normal managed launch/resume Yes, while the sandbox exists
Persistence across sandbox stop/expiry No
Suspend/resume, snapshot, fork/template No
Boat desktop/browser links and Boat public hosting No
Existing authenticated devctl terminal/resource relay Yes

No stop/resume control is advertised as safe when it would destroy the disk. Secret-safe prepared templates, provider desktop links and provider public port publishing are intentionally left for later implementations behind generic capabilities. There is no custom egress-policy layer; provider isolation and abuse controls remain Boat's responsibility.

Session IDs, workspace identity, run records and resource lifecycle history live in the controller database independently of the sandbox. Destroying a sandbox revokes its host credential, clears pending host commands and marks remaining live sessions failed, while retaining their history records. Files, local transcripts and unpublished artifacts inside the sandbox are not a controller backup: export/synchronize what you need before expiry or choose a sufficiently long retained lifetime. Destroying the sandbox cannot remove copies of secrets a workload already sent elsewhere.

Recovery and cleanup

The controller saves resource intent before any billable API call and records whether creation was attempted. Canceling before the first attempt incurs no provider creation. A lost creation response is retried only within the provider's documented idempotency window using the same durable key and request body. Cancellation during an in-flight operation remains authoritative. The controller never retries an uncertain arbitrary command; an ambiguous bootstrap requires inspection rather than possibly launching it twice.

Reconciliation runs every 15 seconds for this console's recorded resources. It does not list or delete arbitrary sandboxes from the same provider account. It resumes pending creation/destruction after controller restarts, retries outages and keeps explicit cleanup intent after errors. Provider expiry bounds the lifetime even if the controller is offline. A creation that remains ambiguous past its idempotency window is retained as unknown, with instructions to inspect the provider account; it is not silently created again.

Deletion uses the provider's permanent-delete operation and polls its operation ID. destroying remains visible until completion. If a resource disappears and the deletion operation could not be recovered, the record says the resource is gone but data erasure is unconfirmed; a 404 is not proof that every provider-side purge has completed.

Bootstrap failure, missing checkout/account, authentication failure, API outage, unexpected termination and pending deletion remain visible in the resource record. Reconcile after correcting configuration. For an ambiguous bootstrap, inspect the enrolled host and checkout before issuing the normal workspace start; completed manual recovery is recognized. Starting a session or workspace whose compute resource is being destroyed is rejected.

Observability and API

All compute routes require the console's existing administrator authorization. Session/host credentials cannot create, inspect or execute commands against other compute resources. Routes resolve a controller-owned resource ID before calling the provider; callers cannot submit arbitrary provider resource IDs.

Route Purpose
GET /v1/compute/providers Installed adapters, capabilities, sizes, configured status and Git-account choices
PUT /v1/compute/providers/:provider/credentials Store a provider key using the existing controller keyring
POST /v1/compute/resources Create an isolated workspace; returns durable intent with HTTP 202
GET /v1/compute/resources Resource inventory, ownership, state, timestamps, expiry and accounting
GET /v1/compute/resources/:id One resource with its session IDs
POST /v1/compute/resources/:id/reconcile Recheck or retry lifecycle work
DELETE /v1/compute/resources/:id Persist destruction intent and begin permanent deletion
POST /v1/compute/resources/:id/exec Operator command in an owned sandbox; arbitrary commands are never automatically retried
GET /v1/compute/resources/:id/process/:processId Detached command status and bounded output

Records include provider/resource ID, Host, Workspace, Project, lifetime policy, state, creation/start/stop/destruction/activity timestamps, CPU and memory. Boat usage is refreshed at most once per five minutes while reconciling: billable seconds and provider-reported USD list-price estimate, explicitly not the actual account invoice after plans/trials/credits. An accounting outage does not block cleanup.

Structured provider logs contain operation, HTTP status and duration, not request bodies, API keys, command text or secret-bearing desktop URLs. Inspect command output only through authorized routes; workload output can itself contain sensitive text and is not included in generic lifecycle errors.

Validation

Unit tests mock provider calls and cover capabilities/state mapping, isolated creation, execution, async deletion, failures/redaction, bounded input, authorization, ownership, lifetime policy, cancellation races, crash recovery, optional package failures, private checkout and unchanged Project placement. Normal CI never creates a Boat sandbox.

An optional live adapter smoke test is available with DEVCTL_BOAT_INTEGRATION=1 and BOAT_API_KEY supplied through the environment: pnpm --filter @devctl/provider-boat test. It creates one short-lived sandbox, runs a harmless command and requests deletion. It incurs normal provider usage. Full real Claude/Codex enrollment requires a reachable console and explicit agent login; mocked tests do not prove those external services are currently available.

Implementation was checked against the official Boat API guide, OpenAPI contract, environment isolation and snapshot/data-retention behavior. The integration uses the documented HTTP API without requiring Boat's SDK or CLI in core.