Skip to main content
A Sandbox connector translates cloud resource operations and guest primitives into the shared control-plane contract. The Sandbox Runtime continues to own Harness processes. Keep provider-specific authentication, transport, pagination and lifecycle details inside the connector; do not add provider branches to generic Run orchestration. Read architecture, acceptance, and the codebase map before changing behavior. This guide describes an extension workflow; its example is not a newly implemented or cloud-verified provider.

Start with the actual contract

The authoritative interface is SandboxConnector. Use Boat as a compact reference for HTTP operations, exact operation lookup and asynchronous deletion. Its private-port and TTL behavior is provider-specific; do not copy it without checking the new provider’s semantics. preview is required by the interface, but an implementation must not advertise public preview capability unless the complete access path works. An unsupported path should fail explicitly. Provider account keys never enter the guest or browser. Private transport must reach Runtime independently of any user-facing preview capability.

Separate adapter registration from resource implementation

A ConnectionAdapter supplies a strict configuration schema, capability list and validate(config, credential) method. Validation returns safe metadata such as the operations actually checked; it must not return upstream response bodies or tokens. A successful list request proves list access, not creation quota, image support or full execution permissions. Use this structural sketch, not a runnable implementation. ExampleConnector must implement the full interface above; every placeholder capability needs evidence before use:
Place the implementation in integrations/sandboxes and register its adapter/factory in the shared registry. Add the provider’s genuine setup URL. API and worker use that same registry. Current registration caveat: the registry’s exported adapters uniformly attach contract_tests: true and live_resource: true. Adding an entry would inherit those claims. Before exposing a new provider, obtain the matching evidence or change that mapping to provider-specific evidence metadata. Registration itself is never evidence. The retained Daytona factory is for historical cleanup, not a template for advertising an unverified candidate.

Implement lifecycle receipts before the happy path

The shared lifecycle, operation ledger and image preparation own durable intent, ownership and fencing. The connector must supply enough exact identifiers for them to reconcile after a crash.
  1. Carry the persisted operation_id into provider idempotency keys and/or exact names and labels. Never replace it after a timeout merely to obtain a successful create response.
  2. If creation returns an asynchronous operation handle, invoke request.record(resourceId, providerOperationId) when supplied before polling. If persistence fails, preserve the uncertain outcome.
  3. After response loss, reconstruct the connector and query exact operation matches. Zero matches does not universally prove non-allocation; eventual consistency and unresolved accepted operations can still require review. Multiple matches are ambiguous, not permission to adopt one arbitrarily.
  4. For asynchronous deletion implement reconcileDeletion(id, context). Persist the accepted handle with context.record, then resume polling that handle after restart. Boat demonstrates why early resource disappearance without the deletion receipt is insufficient to certify purge.
  5. Implement cleanupAssociatedResources when endpoints or other owned objects outlive compute. Never delete shared projects, account credentials or another Session’s resources.
A definitive provider refusal is different from an unknown transport outcome. SandboxCreationRejected currently encodes quota refusal; use it only when the provider proves that no resource or operation was accepted. Do not turn all 429 responses or timeouts into definitive rejection.

Declare only supported policies

Optional methods and properties cover image preparation, pause/resume, snapshots, preflight, native delegated access and associated-resource cleanup. Implement a coherent lifecycle rather than stubbing methods to succeed:
  • resumeMode: 'memory' and 'filesystem' have different recovery semantics. Filesystem resume requires Runtime restart; preserve the workspace and Harness caches under a durable root when /tmp is cleared. reconcileResume must converge on the existing resource, not allocate replacement compute silently.
  • Set control-plane expiry where required and test reconciliation after restart. A stopped control plane cannot enforce timely deletion. Provider standby, explicit pause, expiry and deletion are different states.
  • If using snapshots, persist checkpoint handles before depending on them, restore with the new operation context, and remove owned snapshots during cleanup. Account for changed compute IDs.
  • If using prepared images, implement the prepare/inspect/find/delete lifecycle and persist image/build receipts. Support public/private registry credentials only when the actual provider path supports them; credentials stay inside the control plane.
  • Reject unsupported allowlists before allocation. A declared network policy needs real allowed/denied probes. Native credential access accepts delegated proxy grants, never original upstream secrets.
See serverless lifecycle and capabilities and evidence. Do not infer capabilities from a vendor marketing label.

Ownership of private HTTP targets

SandboxHttpTarget is an internal transport object, not a preview response to return to browsers. Its url and headers let the control plane reach Runtime or a user service. Its optional release disposes of a tunnel, proxy process or connection lease owned by that request. Do not tear down the tunnel as soon as HTTP headers arrive: the body may still be streaming. Cleanup only after success is also insufficient because disconnects, errors and redirects can leave resources behind. See RuntimeClient, the preview entry and transport tests.

What the reference tests prove

Boat’s six existing deterministic tests cover reuse of a persisted deletion handle without another DELETE, recording a handle before polling, refusing to treat resource 404 without a receipt as completed purge, rejecting unsupported network policy before allocation, moving port authorization from a URL into internal request headers, and rejecting truncated command output. They use mocked fetch and never contact a Boat account. They do not validate every creation-pagination case, checkpoint, real network-isolation property or account behavior for your new connector. Add independent tests for the scenario table above, then execute the real journey. Copying reference code or running its tests is not live_resource evidence for a new Provider. The shared operation-review test complements Boat’s adapter tests: a lost create response remains unknown after zero matches; two matching resources retain multiple_resources without binding either; a later unique match is adopted without a second create. The isolated database execution record covers these assertions. This proves the shared lifecycle behavior with a controlled connector; each new provider still needs its own lookup/pagination and receipt tests.

Make response-loss tests restart the adapter

A timeout assertion alone does not exercise recovery. Give the fake provider a persistent operation store that survives connector reconstruction, and keep the connector instance separate from that store:
  1. Accept a create under operation op-a, allocate resource-a, then throw before returning the response. Assert one allocation request.
  2. Construct a fresh connector with the same fake provider store. Query findByOperation("op-a"); require the original resource and no new allocation.
  3. Return no match while the provider still reports an accepted pending operation. The lifecycle must retain uncertainty; the fixture must not equate an empty page with confirmed absence.
  4. Place two exact matches on different pages. Assert both reach the caller so reconciliation can reject ambiguity.
  5. For deletion, persist its receipt, interrupt polling, reconstruct the connector and resume with that receipt. Assert no duplicate DELETE and no completion before the provider-specific completion condition.
These are requirements for the new connector test fixture. The Boat regression suite covers deletion receipts but does not supply all five creation/restart cases for a new provider. Keep the remote fake state alive across the restart; recreating both sides as empty would erase the uncertainty being tested.

Wire the user-facing setup

The Console currently has provider-specific form rendering, configuration serialization and a provider-name list in app.js. Update all relevant paths alongside registration; catalog inclusion alone does not create a complete setup form. Provide useful field constraints, credential instructions and scoped validation feedback. Follow the Console design contract: application-owned accessible controls, complete en/zh-CN catalogs, keyboard/focus behavior and actual browser review in both languages. Keep Sandbox platform configuration separate from model endpoints and Agent Tools. Add a product integration page with prerequisites, limits, failure recovery and exact verification scope.

Verify before promoting support

Start with fake transports and the existing Boat tests. Cover these outcomes explicitly: For the existing reference implementation, the targeted command is:
For your new implementation, add its own suite and run it together with affected lifecycle, operation, expiry, checkpoint and image-preparation suites. Follow testing for database configuration and full gates. These deterministic results do not certify a real account. Then run both independent SDK journeys with a real provider and model, cross-language continuation, declared capabilities, failure/recovery and confirmed cleanup. Verify Console onboarding and authenticated preview where supported. Preserve private resource IDs and failed attempts; record the exact provider, Harness/version/digest, model protocol, SDK artifacts, scenario and date. Only that scoped evidence can promote the corresponding verified combination. Do not label all Harnesses or protocols verified from one successful row. Next: testing and evidence, resource reconciliation, verified combinations.