---
title: "Create a persistent running sandbox."
description: "API reference for POST /v1/sandboxes: Create a persistent running sandbox. Review its parameters, input, response, and generated SDK method names."
canonical: "https://wildflower.computer/docs/reference/create-sandbox/"
openapi_version: "0.8.0"
source_revision: "788b7325a454b8b753a7d614247d5694bad5c967"
---

# Create a persistent running sandbox.

**POST** `/v1/sandboxes`

Creates one provider-backed sandbox and registers its opaque project-scoped ID. Provider access comes from a connected profile or an inline header override, and the selected provider remains fixed for this sandbox.

- **Operation ID:** `createSandbox`
- **Success:** **200 / 201**
- **Authentication:** **Bearer key**

## Optional provider context

These headers are inline overrides. Connected project profiles keep the same fields outside individual requests.

| Name | Type | Requirement | Meaning |
| --- | --- | --- | --- |
| `X-Provider-Workspace` | string | Optional | Optional inline provider workspace override. Required with an inline Blaxel credential and omitted when using a connected profile. |
| `Idempotency-Key` | string | Optional | Caller-generated logical operation key. Reusing it with the same request replays a completed create; conflicting, concurrent, or indeterminate attempts fail closed. |
| `X-Provider-Bridge-Url` | string | Optional | Optional inline customer-owned bridge URL. Required with an inline Cloudflare, Modal, or AgentCore credential and omitted when using a connected profile. |
| `X-Provider-Team-Id` | string | Optional | Optional inline Vercel team identifier. Required with an inline Vercel credential. |
| `X-Provider-Project-Id` | string | Optional | Optional inline Vercel project identifier. Required with an inline Vercel credential. |

## Request and response

- **Request body:** [CreateSandboxRequest](https://wildflower.computer/docs/reference/models/create-sandbox-request/)
- **Response:** [Sandbox](https://wildflower.computer/docs/reference/models/sandbox/)

## HTTP example

This credential-safe request and its representative success response are generated with the operation contract. Replace placeholder IDs and read secrets from your environment.

Request

```bash
curl --fail-with-body --request POST \
  "$WILDFLOWER_URL/v1/sandboxes" \
  -H "Authorization: Bearer $WILDFLOWER_API_KEY" \
  -H "Idempotency-Key: docs-create-example" \
  -H "Content-Type: application/json" \
  --data '{"provider":"e2b","image":"base","timeout":300}'
```

Response / 201

```json
{
  "id": "wf_e2b_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "provider": "e2b",
  "status": "creating",
  "metadata": {
    "nativeProviderId": "native-1"
  }
}
```

## SDK examples

Use the same operation through any generated client. Each snippet comes from the SDK generator rather than a hand-copied website example.

### TypeScript

```typescript
import { Wildflower } from "@wildflowercomputer/sdk";

const client = new Wildflower({
  wildflowerApiKey: process.env.WILDFLOWER_API_KEY,
});

const sandbox = await client.sandboxes.create({
  provider: "e2b",
  image: "base",
  timeout: 300,
});
console.log(sandbox.id, sandbox.status);
```

### Python

```python
import os

from wildflower import (
    E2bCreateSandboxInput,
    ReadFileInput,
    RunCommandInput,
    WriteFileInput,
    Wildflower,
)

client = Wildflower(
    wildflower_api_key=os.environ.get("WILDFLOWER_API_KEY"),
)

sandbox = client.sandboxes.create(
    E2bCreateSandboxInput(image="base", timeout=300)
)
print(sandbox.id, sandbox.status)
```

### Rust

```rust
use wildflower::{
    CreateSandboxInput, FileEncoding, ListSandboxesOptions, ReadFileInput,
    RunCommandInput, WriteFileInput,
    Wildflower,
};

let client = Wildflower::new(std::env::var("WILDFLOWER_API_KEY")?)?;

let sandbox = client.sandboxes().create(CreateSandboxInput::E2b {
    api_key: None,
    image: Some("base".to_owned()),
    timeout: Some(300),
}).await?;
println!("{} {:?}", sandbox.id, sandbox.status);
```

### Go

```go
client, err := wildflower.NewClient(os.Getenv("WILDFLOWER_API_KEY"))
if err != nil {
    return err
}

image := "base"
timeout := uint32(300)
sandbox, err := client.Sandboxes.Create(ctx, wildflower.E2BCreateSandboxInput{
    Image: &image,
    Timeout: &timeout,
})
if err != nil {
    return err
}
fmt.Println(sandbox.ID, sandbox.Status)
```

### Zig

```zig
var client = try Wildflower.init(
    allocator,
    wildflower_api_key,
    transport,
);
defer client.deinit();

var sandbox = try client.create(.{ .e2b = .{
    .api_key = null,
    .image = "base",
    .timeout = 300,
} });
defer sandbox.deinit();
std.debug.print("{s}\n", .{sandbox.value.id});
```

## Generated SDK methods

Every name below comes from the generator mapping for this operation, so a language-specific rename creates website drift.

- [TypeScript](https://wildflower.computer/sdk/typescript/): `create`
- [Python](https://wildflower.computer/sdk/python/): `create`
- [Rust](https://wildflower.computer/sdk/rust/): `create`
- [Go](https://wildflower.computer/sdk/go/): `Create`
- [Zig](https://wildflower.computer/sdk/zig/): `create`