---
title: "Small concepts, explicit behavior."
description: "Understand Wildflower Computer lifecycle, persistence, credentials, routeable IDs, connection context, errors, and model boundaries."
canonical: "https://wildflower.computer/docs/concepts/"
openapi_version: "0.8.0"
source_revision: "788b7325a454b8b753a7d614247d5694bad5c967"
---

# 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.

> **No failover**
>
> A sandbox stays attached to the provider selected at creation. Wildflower Computer does not automatically move or fail over a sandbox between providers.

## 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 as`wf_e2b_…`, `wf_modal_…`, or`wf_vercel_…`. The API uses that ID to route later operations to the correct adapter.

Responses also expose the provider-native identifier at`metadata.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](https://wildflower.computer/sdk/typescript/) 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.

> **Current product boundary**
>
> Wildflower Computer does not execute models and does not implement an agent runtime.

## 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 report`stopped` and wakes on its first command.