Explanation / API boundaries

Small concepts, explicit behavior.

Wildflower Computer normalizes the common persistent sandbox lifecycle while keeping meaningful provider differences visible. These concepts are the contract your integration can rely on today.

Persistent lifecycle

Creating a sandbox returns a provider-backed resource. Later get and runCommand calls address that same native sandbox, so its filesystem and process-level state persist until deletion or provider-side lifetime behavior ends it.

1. Create a sandbox for one explicit provider.
2. Get its current normalized state when needed.
3. Run commands in the existing sandbox through the/exec HTTP endpoint.
4. Delete it when your work is complete.

Capability discovery

GET /v1/providers returns a typed catalog of stable provider IDs, display names, normalized published prices, image and timeout modes, output streams, and lifecycle capabilities. It requires the Wildflower Computer bearer key, but not a sandbox-provider credential. Callers can inspect this catalog instead of inferring behavior or pricing from provider names.

Idempotent sandbox creation

Create accepts an optional caller-generated Idempotency-Key. A completed request replayed with the same key, body, and non-secret provider connection context returns the original sandbox. Reusing a key with different input, racing a concurrent request, or retrying an outcome the API cannot prove fails closed.

The returned metadata.operationId identifies the logical create operation. Static-key mode keeps idempotency records in process memory; configured PostgreSQL keeps them across API restarts. Provider-profile storage is a separate encrypted project-scoped boundary.

Routeable sandbox IDs

Wildflower Computer returns an opaque ID with a provider prefix, such aswf_e2b_…, wf_modal_…, orwf_vercel_…. The API uses that ID to route later operations to the correct adapter.

Responses also expose the provider-native identifier atmetadata.nativeProviderId for debugging. When the provider exposes a runtime or protocol version, it can appear at metadata.nativeProviderVersion.

Two credential boundaries

The API and provider credentials have different jobs:

• Authorization: Bearer <key> authenticates the caller to the Wildflower Computer API.
• A connected project profile or X-Provider-Api-Key inline override supplies the customer's provider credential.

PostgreSQL mode encrypts connected project profiles at rest. Static local mode retains profiles in process memory. Inline overrides are ephemeral.

Provider connection context

Blaxel requires a workspace; bridge providers require a bridge URL; Vercel requires team and project IDs. Profiles store this non-secret routing context, while generated clients keep inline values typed and separate from JSON.

Inline SDK overrides

Generated SDKs keep inline provider access within the current client process for later lifecycle calls. A fresh process should use a connected project profile or explicitly receive the same provider access again. See the generated TypeScript lifecycle for the current method names and credential-safe example.

Models and sandboxes

An AI model decides what work to do. A sandbox supplies an isolated environment where commands can run. Your application can pair any model integration with a supported sandbox provider, but those are separate decisions.

Normalized status

Provider state is mapped to a common status vocabulary:creating, running, paused,stopped, deleting, deleted,error, or unknown. A cold Sprite can initially reportstopped and wakes on its first command.