---
title: "Ensure Workspace Box"
method: POST
path: "/v1/kernel/workspace-box"
tags: ["kernel"]
---

# Ensure Workspace Box

`POST /v1/kernel/workspace-box`

Bring up the box a command must be pinned to, and name it.

A caller that names a notebook gets that notebook's box; one that names
none gets the workspace's own. The gateway plane has no box a *workspace*
owns -- boxes come up only as a side effect of a notebook's kernel start --
so a command that names no notebook has nothing to run on (QUA-3067), and
a clone meets this first: the notebook it would have to open for a box is a
file at the root it requires to be empty.

Answers ``202``-style with an ``operation_id`` the caller polls at
``GET /operations/{id}``, exactly as ``/kernels/start`` does. Provisioning
is a machine plus the gateway's own 240s health wait, and a request held
open with no bytes flowing for that long is what an ALB idle timeout ends.

## Response `200`

Successful Response

- unknown

## Changes

- **2026-09-10** `3a8d4a28ae93` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/quadrillion/apis/quadrillion-cloud-api/changes/v1/kernel/workspace-box/post.md)

---

[API](https://skmtc.dev/quadrillion/apis/quadrillion-cloud-api.md) · [All operations](https://skmtc.dev/quadrillion/apis/quadrillion-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/quadrillion/apis/quadrillion-cloud-api/revisions/397ad3a1d858?raw)