# Build a Sandbox Template snapshot

Source: <https://everruns.com/docs/api/operations/start_sandbox_template_build/>

[Docs](https://everruns.com/docs/)/[API reference](https://everruns.com/docs/api/)/[Operations & billing](https://everruns.com/docs/api/groups/operations-billing/)/Build a Sandbox Template snapshot

# Build a Sandbox Template snapshot

Preview

Run an install script in fresh isolated compute and bake a reusable provider snapshot. Does not revise the template.

Public APIEverruns Cloud and self-hosted Platform

POST`/v1/sandbox-templates/{id}/builds`

See [authentication](https://everruns.com/docs/sre/runbooks/authentication/) for credentials and permissions.

## Parameters

### Path Parameters

**id**

required

string

Prefixed public identifier

## Request Bodyrequired

Media typeapplication/json

Inputs for a single isolated installation and reusable filesystem snapshot. Build compute receives no workload credentials or private Session state.

object

**build_network**

One of:

* object

  One of:

  * object

    object

    **mode**

    required

    string

    Allowed values: deny

  * object

    object

    **allowed_hosts**

    required

    Array\<string>

    **mode**

    required

    string

    Allowed values: allowlist

  * object

    object

    **mode**

    required

    string

    Allowed values: allow

* null

  object

  **mode**

  required

  string

  Allowed values: deny

* object

  object

  **allowed_hosts**

  required

  Array\<string>

  **mode**

  required

  string

  Allowed values: allowlist

* object

  object

  **mode**

  required

  string

  Allowed values: allow

* object

  null

**install_script**

required

POSIX shell install script, 1–32768 UTF-8 bytes. Keep secrets out of it.

string

### Example

```plaintext
python -m venv /home/daytona/.venvs/devtools
/home/daytona/.venvs/devtools/bin/pip install httpie==3.2.4
```

**metadata_path**

Optional bounded, author-supplied Markdown captured from the builder.

string | null

### Example

```plaintext
/home/daytona/.everruns/sandbox.md
```

**source_revision_id**

required

Source revision to guard against concurrent template edits.

string

### Example

```plaintext
sbxtplrev_01933b5a000070008000000000000001
```

**timeout_seconds**

Total build deadline, including installation and fresh verification, in seconds.

integer format: int64

\>= 60 <= 1800

### Example

```json
600
```

**verification_command**

Optional check run after installation and again in fresh snapshot compute.

string | null

### Example

```plaintext
/home/daytona/.venvs/devtools/bin/http --version
```

## Responses

200Success

### 200

Success

Media typeapplication/json

Tenant-scoped build attempt, retained inputs, bounded output, and provider artifact. Management credentials are stored separately and never appear in this record.

object

**applied_revision_id**

Immutable template revision created by applying this artifact, if applied.

string | null

**builder_id**

Disposable installation compute identifier or its persisted submission name.

string | null

**cancel_requested**

required

Whether cancellation was accepted; stale worker saves cannot erase this request.

boolean

**cleanup_pending**

required

Whether provider resources still require confirmed cleanup or reconciliation.

boolean

**created_at**

required

Time this build attempt was accepted.

string format: date-time

**error**

Bounded failure explanation, absent when no failure has been recorded.

string | null

**id**

required

Unique build attempt identifier.

string

**logs**

required

UTF-8 execution-output tail, bounded to 32 KiB.

string

**request**

required

Original immutable installation and verification inputs.

object

**build_network**

One of:

* object

  One of:

  * object

    object

    **mode**

    required

    string

    Allowed values: deny

  * object

    object

    **allowed_hosts**

    required

    Array\<string>

    **mode**

    required

    string

    Allowed values: allowlist

  * object

    object

    **mode**

    required

    string

    Allowed values: allow

* null

  object

  **mode**

  required

  string

  Allowed values: deny

* object

  object

  **allowed_hosts**

  required

  Array\<string>

  **mode**

  required

  string

  Allowed values: allowlist

* object

  object

  **mode**

  required

  string

  Allowed values: allow

* object

  null

**install_script**

required

POSIX shell install script, 1–32768 UTF-8 bytes. Keep secrets out of it.

string

**metadata_path**

Optional bounded, author-supplied Markdown captured from the builder.

string | null

**source_revision_id**

required

Source revision to guard against concurrent template edits.

string

**timeout_seconds**

Total build deadline, including installation and fresh verification, in seconds.

integer format: int64

\>= 60 <= 1800

**verification_command**

Optional check run after installation and again in fresh snapshot compute.

string | null

**sandbox_template_id**

required

Parent template whose immutable source revision supplied the build configuration.

string

**snapshot_id**

Provider snapshot identifier, present once the artifact has been resolved.

string | null

**snapshot_name**

required

Deterministic provider artifact name used to reconcile uncertain submissions.

string

**snapshot_requested_at**

Submission time used when reconciling a snapshot response lost in transport.

string | null format: date-time

**software_notes**

Up to 16 KiB of author-supplied Markdown, presented as untrusted reference data.

string | null

**source_spec**

required

Exact source spec; no runtime credentials or workspace are attached.

object

**bootstrap**

Reproducible commands run when physical compute is initialized.

object

**commands**

Ordered commands replayed when creating or recovering physical compute.

Array\<string>

**containment**

One of:

* object

  Requested isolation policy; resolution supplies an honest target default.

  object

  **escalation**

  Whether the runtime may widen containment after Session creation.

  string

  Allowed values: never approval auto

  **filesystem**

  Filesystem mutation boundary for command execution.

  object

  **writable_roots**

  Absolute roots the runtime may mutate; empty means provider default.

  Array\<string>

  **level**

  required

  Isolation mechanism the provider must supply.

  string

  Allowed values: none native isolated

  **network**

  One of:

  * object

    object

    **mode**

    required

    string

    Allowed values: deny

  * object

    object

    **allowed_hosts**

    required

    Array\<string>

    **mode**

    required

    string

    Allowed values: allowlist

  * object

    object

    **mode**

    required

    string

    Allowed values: allow

* null

  object

  **mode**

  required

  string

  Allowed values: deny

* object

  object

  **allowed_hosts**

  required

  Array\<string>

  **mode**

  required

  string

  Allowed values: allowlist

* object

  object

  **mode**

  required

  string

  Allowed values: allow

* object

  null

**durability**

One of:

* string

  Requested recovery guarantee; resolution supplies a target default.

  string

  Allowed values: checkpointed provider_snapshot none

* null

  null

**lifecycle**

Idle lifecycle policy controlled by Everruns.

object

**delete_after_seconds**

How long a paused Sandbox is kept, counted from its last activity, before Everruns deletes it with its files. The Session stays; its next Sandbox call provisions a fresh one. `null` keeps paused Sandboxes until their Session is deleted.

integer | null format: int64

**idle_action**

Action Everruns requests after the idle interval.

string

Allowed values: checkpoint_and_stop stop keep_running delete

**idle_after_seconds**

Inactivity interval before applying `idle_action`.

integer format: int64

**target**

required

Provider-neutral target plus its concrete adapter binding.

object

**connection_id**

Credential/transport binding for a registered machine target.

string | null

**credential**

Provider credential source. User and Agent bindings are resolved to an exact virtual user when the Session starts; organization bindings also pin the exact connection.

object

**connection_id**

Exact connection for organization grants, which may have several accounts for one provider.

string | null format: uuid

**source**

required

Identity scope from which the provider credential is resolved.

string

Allowed values: none session_user agent organization platform

**virtual_user_id**

Exact virtual-user owner for user, Agent, and organization grants.

string | null format: uuid

**kind**

required

Provider-neutral target class.

string

Allowed values: host machine vfs container managed

**options**

Provider-owned, non-secret configuration. Credentials are references, never values in this object.

object

**provider**

Concrete adapter for target kinds with more than one implementation.

string | null

**template_revision_id**

Immutable Sandbox Template revision this specification was copied from. The specification remains complete so Agent snapshots are portable and later template revisions cannot change an existing snapshot.

string | null

**status**

required

Persisted lifecycle state; inspect cleanup_pending before applying a Ready build.

string

Allowed values: queued running ready failed cancelled applied discarded

**step**

required

Current execution or cleanup step.

string

**updated_at**

required

Time of the last persisted build update.

string format: date-time

**verification_sandbox_id**

Disposable fresh-snapshot verification compute identifier or submission name.

string | null

### Example

```json
{
  "applied_revision_id": "sbxtplrev_01933b5a000070008000000000000002",
  "builder_id": "550e8400-e29b-41d4-a716-446655440001",
  "cancel_requested": false,
  "cleanup_pending": false,
  "created_at": "2026-10-29T00:00:00Z",
  "error": "Command failed with exit code 23",
  "id": "sbxbuild_01933b5a000070008000000000000001",
  "logs": "HTTPie 3.2.4\nVerification passed\n",
  "request": {
    "build_network": {
      "mode": "deny"
    },
    "install_script": "python -m venv /home/daytona/.venvs/devtools\n/home/daytona/.venvs/devtools/bin/pip install httpie==3.2.4",
    "metadata_path": "/home/daytona/.everruns/sandbox.md",
    "source_revision_id": "sbxtplrev_01933b5a000070008000000000000001",
    "timeout_seconds": 600,
    "verification_command": "/home/daytona/.venvs/devtools/bin/http --version"
  },
  "sandbox_template_id": "sbxtpl_01933b5a000070008000000000000001",
  "snapshot_id": "550e8400-e29b-41d4-a716-446655440000",
  "snapshot_name": "everruns-build-01933b5a000070008000000000000001",
  "snapshot_requested_at": "2026-10-29T00:00:00Z",
  "software_notes": "# Installed tools\n- HTTPie 3.2.4",
  "source_spec": {
    "containment": {
      "escalation": "never",
      "level": "none",
      "network": {
        "mode": "deny"
      }
    },
    "durability": "checkpointed",
    "lifecycle": {
      "delete_after_seconds": 259200,
      "idle_action": "checkpoint_and_stop",
      "idle_after_seconds": 300
    },
    "target": {
      "connection_id": "conn_01933b5a000070008000000000000001",
      "credential": {
        "connection_id": "00000000-0000-0000-0000-000000000002",
        "source": "none",
        "virtual_user_id": "00000000-0000-0000-0000-000000000001"
      },
      "kind": "host",
      "provider": "daytona"
    }
  },
  "status": "queued",
  "step": "installing",
  "updated_at": "2026-10-29T00:01:00Z",
  "verification_sandbox_id": "550e8400-e29b-41d4-a716-446655440002"
}
```

FetchcURL

Request

```js
const url = 'https://app.everruns.com/api/v1/sandbox-templates/example/builds';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"build_network":{"mode":"deny"},"install_script":"python -m venv /home/daytona/.venvs/devtools\n/home/daytona/.venvs/devtools/bin/pip install httpie==3.2.4","metadata_path":"/home/daytona/.everruns/sandbox.md","source_revision_id":"sbxtplrev_01933b5a000070008000000000000001","timeout_seconds":600,"verification_command":"/home/daytona/.venvs/devtools/bin/http --version"}'
};


try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

Request

```sh
curl --request POST \
  --url https://app.everruns.com/api/v1/sandbox-templates/example/builds \
  --header 'Content-Type: application/json' \
  --data '{ "build_network": { "mode": "deny" }, "install_script": "python -m venv /home/daytona/.venvs/devtools\n/home/daytona/.venvs/devtools/bin/pip install httpie==3.2.4", "metadata_path": "/home/daytona/.everruns/sandbox.md", "source_revision_id": "sbxtplrev_01933b5a000070008000000000000001", "timeout_seconds": 600, "verification_command": "/home/daytona/.venvs/devtools/bin/http --version" }'
```

Additional language examples require JavaScript. The default request example is available above.

200

200 · Success

```json
{
  "applied_revision_id": "sbxtplrev_01933b5a000070008000000000000002",
  "builder_id": "550e8400-e29b-41d4-a716-446655440001",
  "cancel_requested": false,
  "cleanup_pending": false,
  "created_at": "2026-10-29T00:00:00Z",
  "error": "Command failed with exit code 23",
  "id": "sbxbuild_01933b5a000070008000000000000001",
  "logs": "HTTPie 3.2.4\nVerification passed\n",
  "request": {
    "install_script": "python -m venv /home/daytona/.venvs/devtools\n/home/daytona/.venvs/devtools/bin/pip install httpie==3.2.4",
    "metadata_path": "/home/daytona/.everruns/sandbox.md",
    "source_revision_id": "sbxtplrev_01933b5a000070008000000000000001",
    "timeout_seconds": 600,
    "verification_command": "/home/daytona/.venvs/devtools/bin/http --version"
  },
  "sandbox_template_id": "sbxtpl_01933b5a000070008000000000000001",
  "snapshot_id": "550e8400-e29b-41d4-a716-446655440000",
  "snapshot_name": "everruns-build-01933b5a000070008000000000000001",
  "snapshot_requested_at": "2026-10-29T00:00:00Z",
  "software_notes": "# Installed tools\n- HTTPie 3.2.4",
  "source_spec": {
    "target": {
      "connection_id": "conn_01933b5a000070008000000000000001",
      "provider": "daytona"
    }
  },
  "status": "queued",
  "step": "installing",
  "updated_at": "2026-10-29T00:01:00Z",
  "verification_sandbox_id": "550e8400-e29b-41d4-a716-446655440002"
}
```

## Matching endpoints