---
title: "Link a sandbox to the chat, or create one for it. Replaces any earlier link."
method: POST
path: "/ai/conversations/{public_id}/sandbox"
tags: ["AI Chat"]
---

# Link a sandbox to the chat, or create one for it. Replaces any earlier link.

`POST /ai/conversations/{public_id}/sandbox`

## Request

- Base URL: `/api` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/api/ai/conversations/{public_id}/sandbox`
- Auth: HTTP bearer

## Path parameters

- `public_id` string, required

## Request body

- LinkSandboxRequest: Link an existing sandbox (`sandbox_id`) or create a new one (`create`).
  - `create` boolean: Create a fresh sandbox for this chat instead.
  - `sandbox_id` string, nullable: Public id of one of the caller's own sandboxes.

## Response `200`

Sandbox linked

- ChatSandboxStatus: What a chat can do with a sandbox, and the one it is linked to.
  - `configured` boolean, required: Whether this chat can use a sandbox at all.
  - `connected_projects` integer[], required: Projects whose services the linked sandbox is connected to: its commands run with credentials for a database of its own on each.
  - `connected_services` ConnectedService[], required: Every service the linked sandbox is connected to, whether or not it was connected through a project.
    - `project_id` integer, nullable: The project the link was made through, if it was made through one.
    - `service_id` integer, required
  - `linked` SandboxLink: The sandbox a chat is linked to, as stored.
    - `linked_at` string, date-time, required: ISO 8601 time the link was made.
    - `name` string, required: Display name of the sandbox when it was linked.
    - `sandbox_id` string, required: Public id of the sandbox (`sbx_…`).
  - `offered` boolean, required: True once the assistant has asked the user to link a sandbox.
  - `preview` ChatPreview: How to reach a page served from the chat's sandbox.
    - `port` integer, nullable: The port the assistant last confirmed serving a page, if it has.
    - `url` string, nullable: Address of that page, served by Temps.
    - `url_template` string, required: Address for any port: `{port}` stands for the port number.
  - `reason` string, nullable: Why it cannot, when `configured` is false.
  - `runtime` 'running' | 'asleep': Whether a linked sandbox's compute is running.
  - `setup_path` string, nullable: Console path where the user can fix it, when there is one.

## Other responses

- `400`: Neither or both of sandbox_id and create were sent
- `401`: Unauthorized
- `403`: Insufficient permissions
- `404`: Conversation or sandbox not found
- `409`: The sandbox cannot be linked
- `500`: Internal server error
- `503`: This server has no sandbox backend

## Changes

> 81 revisions in range; 1 not diffed.

- **2026-10-20** `79089e9f49ee`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/gotempsh/apis/temps/changes/ai/conversations/:public_id/sandbox/post.md)

---

[API](https://skmtc.dev/gotempsh/apis/temps.md) · [All operations](https://skmtc.dev/gotempsh/apis/temps/llms.txt) · [OpenAPI document](https://skmtc.dev/gotempsh/apis/temps/revisions/ab6d5d19e930?raw)