PaperClipAI/doc/plugins/SANDBOX_PROVIDER_CAPABILITIES.md

Sandbox provider capability contract

A sandbox provider plugin declares an environment driver with kind: "sandbox_provider". Each driver can declare a set of optional sandbox capabilities. This document is the contract for a third-party provider author. It states what to declare, which worker methods each capability needs, what an omitted key means, and when the host narrows or denies a capability.

Read Sandbox file-sync lifecycle hooks for the native file-transfer hooks. Read the driver declaration shape in the plugin specification.

Fresh lease acquisition timeout

A driver can declare defaultAcquireTimeoutMs as a positive integer of at most 86,400,000 milliseconds. The host uses it for environmentAcquireLease when the resolved config has no positive finite numeric timeoutMs. A positive numeric bridgeRequestTimeoutMs can extend that budget. The host adds 30 seconds for RPC overhead. This applies to both sandbox providers and generic plugin drivers.

Daytona declares 300,000 milliseconds, and its host RPC can therefore wait 330 seconds instead of the worker's normal 30 seconds. The worker itself caps one fresh acquisition at 180 seconds. Creation, workspace setup, shell detection, expiry setup, and inline failure cleanup share that cap. A create that has not returned after 90 seconds is looked up once by its creation name: a sandbox that has started is adopted and setup continues, one still preparing its snapshot keeps waiting within the cap, and any other state ends the attempt. On timeout the provider returns the attempt's scoped cleanup record and an acquisition diagnostic whose elapsed time has reached the expired budget. The host treats that diagnostic as a transient provider failure (environment_provider_unavailable), so the run is retried with the bounded bootstrap budget while the creation reconciler removes the abandoned allocation. Late SDK results cannot admit the lease or start the next setup phase, and a late SDK failure never deletes an adopted sandbox. Drivers that omit the declaration keep the existing fallback. The host does not infer this budget from config-schema defaults: a field named timeoutMs can describe sandbox lifetime instead of the time needed to acquire it.

For reusable sandbox acquisition, the host also uses this budget for environmentResumeLease, with the same explicit-config precedence, bridge extension, and RPC margin. Resume attempts and transient retries share one deadline. Without a configured or declared budget, resume keeps its one-minute host default. Generic plugin-driver resume keeps its existing behavior.

This declaration does not change provider config, lease expiry, or other lifecycle calls. Providers must still enforce their operation timeouts and report uncertain allocations for cleanup. A bundled plugin must bump its manifest version when adding the field so existing installations receive it.

How the host resolves an effective capability

The host never trusts a declaration alone. For every run it resolves each capability as the intersection of three inputs:

effective = verified ∩ declared ∩ narrowing

• verified — the methods the live worker advertised in InitializeResult.supportedMethods. The host maps each capability to the worker methods it needs (see the table below). A capability is verified only when the worker advertises every required method. An empty or missing method list verifies nothing, so every capability resolves false.
• declared — the values in the driver declaration. A declared key is optional (see the next section).
• narrowing — a per-run restriction from the lease policy or the resolved provider config. A narrowing can only remove a capability, never add one.

A capability is effective only when all three allow it. A declaration therefore never grants a capability that the worker did not verify.

The declaration is optional and partial

Declare capabilities through the nested sandboxCapabilities object on the driver declaration:

environmentDrivers: [
  {
    driverKey: "my-provider",
    kind: "sandbox_provider",
    displayName: "My Provider",
    configSchema: { type: "object", properties: {} },
    sandboxCapabilities: {
      reusableLeases: true,
      nativeSyncIn: true,
      nativeSyncOut: true,
      persistentProcessSessions: false,
      independentControlCommands: false,
      incrementalSessionOutput: false,
    },
  },
]

Every key is optional. For a valid, identified provider each key has one of three states:

• Omitted — the host defers to verified worker discovery. The capability is effective when the worker advertises the required methods and no narrowing removes it. Omission is the correct default for a provider that follows the standard method contract. reusableLeases and incrementalSessionOutput are the two exceptions: an omitted key never grants either capability. Both are opt-in (see the next two sections).
• false — the host narrows the capability to off. The capability is never effective, even when the worker advertises the required methods.
• true — the host still requires the verified prerequisites. A true value never grants a capability without them. It documents intent and lets the host present the capability, but the worker must still advertise the required methods.

Reusable leases need an explicit opt-in

Reusable leases are the exception to the omission rule above. The host grants reusable-lease acquisition only when the declaration sets reusableLeases to true. The provider opts in through one of two fields:

• the nested sandboxCapabilities.reusableLeases: true, or
• the legacy supportsReusableLeases: true.

An omitted key leaves reusableLeases unset. An unset key does not make the provider eligible for reusable-lease acquisition, and it does not advertise provider-level reusable support. The host then always creates an ephemeral lease.

The opt-in never removes the other prerequisites. The worker must still verify all three lifecycle methods, environmentResumeLease, environmentReleaseLease, and environmentDestroyLease, and per-run narrowing still applies.

The two opt-in fields have a fixed precedence. The host keeps the legacy supportsReusableLeases field for backward compatibility, and it folds the field into sandboxCapabilities.reusableLeases.

• When only supportsReusableLeases is present, the host reads it as reusableLeases.
• When both supportsReusableLeases and sandboxCapabilities.reusableLeases are present, the nested value wins.

A manifest with legacy true and nested false therefore resolves to false. Prefer the nested sandboxCapabilities.reusableLeases in a new manifest.

Incremental session output needs an explicit opt-in

Incremental session output is the second exception to the omission rule. The host selects the session-output streaming path only when the declaration sets incrementalSessionOutput to true. An omitted key resolves the capability to false, so the host keeps the output-file poll path.

The reason is that this key is a behavioral guarantee, not a worker-method property. A generic one-shot provider can keep persistent process sessions and run independent control commands, yet it never emits incremental stdout and stderr from a live session. The two broad capabilities do not imply incremental output, so the host requires the provider to declare the behavior. A provider that streams incremental session output declares sandboxCapabilities.incrementalSessionOutput: true; every other provider omits the key and keeps the poll path.

The opt-in never removes the prerequisites. The worker must still verify environmentExecute, and per-run narrowing still applies. A config-resolution failure narrows the capability to off (see Failure behavior).

The capabilities and their worker-method prerequisites

Capability	Required worker methods	Meaning
reusableLeases	environmentResumeLease, environmentReleaseLease, and environmentDestroyLease	The host retains a provider lease and resumes it across runs.
nativeSyncIn	environmentSyncIn	The host transfers files into the sandbox through the native inbound hook.
nativeSyncOut	environmentSyncOut	The host transfers files out of the sandbox through the native outbound hook.
persistentProcessSessions	environmentExecute	The provider keeps a persistent process session open across commands.
independentControlCommands	environmentExecute	The provider runs a one-shot control command beside a long-lived command.
incrementalSessionOutput	environmentExecute	The provider streams incremental stdout and stderr from a live session. Opt-in: an omitted key resolves false.

Reusable leases need all three lifecycle methods. The host resumes a lease with environmentResumeLease, ends it with environmentReleaseLease, and tears down a stale lease with environmentDestroyLease. The reuse path destroys a stale lease when a resume fails, so a provider that cannot destroy a lease would strand it. A worker that omits any of the three methods never gets reusable leases, even with a positive declaration. The host then always creates an ephemeral lease.

The host advertises and consumes the two native sync methods as a pair. Define both or neither. See Sandbox file-sync lifecycle hooks.

Target and config narrowing

A narrowing removes a capability that the provider verified and declared but that this run cannot use.

• Ephemeral lease policy. A lease that the host does not retain never reuses. The host narrows reusableLeases to off for an ephemeral lease and keeps it on only for a reuse-by-environment lease.
• Kubernetes Job backend. A Job-backed lease, or a lease the host marked as unable to run native file sync, disables native sync. The host narrows nativeSyncIn and nativeSyncOut to off and keeps the base64-over-exec fallback.

Failure behavior

The host fails closed on two failure states. It never grants a capability from an unknown state.

• Config-resolution failure. A provider whose config the host cannot resolve is untrusted. The host narrows persistentProcessSessions and incrementalSessionOutput to off instead of allowing either through an empty config.
• Exact-plugin identity failure. A retained lease pins the exact plugin that acquired it. When that plugin is absent, or when it no longer declares this provider key with the sandbox_provider kind, the host cannot establish the declaration. It resolves every effective capability to false, no matter what methods a stale worker still advertises. An omitted sandboxCapabilities object on a valid, identified plugin is a different state; the host defers to verified discovery for that case.

Concurrency capabilities are not part of the contract

Earlier drafts listed two concurrency keys, concurrentSyncAndExec and concurrentSyncOperations. The runtime never exposed a scheduling choice that read either key, so a declaration had no effect. The host removed both keys. The strict capability validator now rejects them as unknown keys. The host can reintroduce a concurrency capability when a runtime path enforces it.

Preserving an unexported workspace

Native export recovery requires the separately discovered environmentStopLease RPC (onEnvironmentStopLease). It stops the exact allocation and preserves files regardless of its normal release policy. A failed or unconfirmed stop must throw and must never fall back to deletion. The host uses the recorded plugin ID and defers when that worker does not advertise the hook; a generic release method is insufficient evidence of stop-only support. Normal successful ephemeral release remains destructive after verified copyback.

Daytona stop-only preservation disables provider auto-delete and refreshes the provider record to confirm the disabled policy before stopping. An unavailable or unconfirmed policy leaves cleanup pending; it never falls back to stop or delete. The original ephemeral destroy policy applies only after exact accepted-result copyback and commitment.

A provider can refuse Stop while the allocation is in a provider error state. A stop-only hook may run one bounded provider recovery and then stop. When it cannot stop the allocation, it throws PluginEnvironmentStopError with a closed reason. The host treats resource_unrecoverable and recovery_failed as terminal: it escalates the pending cleanup at once and retries at its slowest interval. Deletion is never a fallback.