Workspaces

Sandbox file system for AI agents

Overview

Workspaces provide agents with an isolated sandbox file system. When an agent uses agent reasoning mode, it has access to built-in file tools (write, read, edit, grep, delete) that operate on workspace files.

Workspaces must be enabled for agents to use file tools, edit mode (chat_mode: 'edit'), and plan mode (chat_mode: 'plan'). When workspace is disabled, these tools are removed and chat mode falls back to ask.

Each workspace is scoped per-agent and per-user:

• Authenticated users — each user gets their own workspace per agent
• Anonymous users — each chat conversation gets an isolated workspace

Workspaces can also be published. A published workspace gives generated files or pages a public URL, and eligible plans can attach a custom domain.

Built-in File Tools

When an agent runs in agent reasoning mode, these tools are automatically available:

Tool	Description	Approval
write	Create or overwrite a file	Conditional
read	Read file content (supports line ranges)	Auto
edit	Exact string replacement in a file	Conditional
grep	Regex search across workspace files	Auto
delete	Soft-delete a file	Conditional

Tools marked “Conditional” require user approval before execution (configurable per agent). Tools marked “Auto” execute without approval.

write

Create a new file or overwrite an existing one:

Parameter	Type	Required	Description
file_path	string	Yes	Virtual file path (e.g., /src/app.js)
content	string	Yes	Full file content
language	string	No	Programming language hint

read

Read a file’s content, optionally by line range:

Parameter	Type	Required	Description
file_path	string	Yes	Virtual file path to read
start_line	integer	No	Start line (1-based)
end_line	integer	No	End line (1-based, inclusive)

edit

Apply an exact string replacement to a file:

Parameter	Type	Required	Description
file_path	string	Yes	Virtual file path to edit
old_string	string	Yes	Exact text to find (must match uniquely)
new_string	string	Yes	Replacement text (empty string to delete)

grep

Search across workspace files using regex:

Parameter	Type	Required	Description
pattern	string	Yes	Search pattern (regex supported)
file_path	string	No	Restrict to a specific file
include	string	No	File extension filter (e.g., .js)

delete

Remove a file from the workspace (soft delete):

Parameter	Type	Required	Description
file_path	string	Yes	Virtual file path to delete

REST API

Manage workspaces and files programmatically. All endpoints require API key authentication.

List Workspaces

GET /v1/bot/workspace/readall?project_id={project_id}&bot_id={bot_id}

Response:

{
  "workspaces": [
    {
      "uuid": "ws_abc123",
      "name": "Default",
      "is_default": 1,
      "created_at": "2026-02-01T12:00:00Z"
    }
  ]
}

Create Workspace

POST /v1/bot/workspace/create

Parameter	Type	Required	Description
project_id	string	Yes	Project ID
bot_id	string	Yes	Bot ID
name	string	Yes	Workspace name
description	string	No	Workspace description

Delete Workspace

DELETE /v1/bot/workspace/delete?project_id={project_id}&bot_id={bot_id}&workspace_uuid={uuid}

The default workspace cannot be deleted.

List Files

GET /v1/bot/workspace/files?project_id={project_id}&bot_id={bot_id}&workspace_uuid={uuid}

Response:

{
  "files": [
    {
      "uuid": "file_xyz",
      "file_path": "/src/app.js",
      "language": "javascript",
      "version": 3,
      "created_at": "2026-02-01T12:00:00Z"
    }
  ]
}

Read File

GET /v1/bot/workspace/file?project_id={project_id}&bot_id={bot_id}&workspace_uuid={uuid}&file_uuid={file_uuid}

Create File

POST /v1/bot/workspace/file

Parameter	Type	Required	Description
project_id	string	Yes	Project ID
bot_id	string	Yes	Bot ID
workspace_uuid	string	Yes	Workspace UUID
file_path	string	Yes	Virtual file path (e.g., /src/app.js)
content	string	No	File content
language	string	No	Programming language

Update File

PUT /v1/bot/workspace/file

Parameter	Type	Required	Description
project_id	string	Yes	Project ID
bot_id	string	Yes	Bot ID
workspace_uuid	string	Yes	Workspace UUID
file_uuid	string	Yes	File UUID
content	string	Yes	New file content

Delete File

DELETE /v1/bot/workspace/file?project_id={project_id}&bot_id={bot_id}&workspace_uuid={uuid}&file_uuid={file_uuid}

Rename/Move File

PUT /v1/bot/workspace/file/rename

Parameter	Type	Required	Description
project_id	string	Yes	Project ID
bot_id	string	Yes	Bot ID
workspace_uuid	string	Yes	Workspace UUID
old_path	string	Yes	Current file path
new_path	string	Yes	New file path
is_folder	boolean	No	Move all files under path prefix (folder rename)

Publishing

Publish a workspace when the agent has created a deliverable that should be shared publicly, such as a page, report, prototype, or client-facing document.

Suggest Subdomain

GET /v1/bot/workspace/suggest-subdomain?project_id={project_id}&bot_id={bot_id}&workspace_uuid={uuid}

Returns an available workspace subdomain and root domain.

Publish Workspace

PUT /v1/bot/workspace/publish

Parameter	Type	Required	Description
project_id	string	Yes	Project ID
bot_id	string	Yes	Bot ID
workspace_uuid	string	Yes	Workspace UUID
subdomain	string	Yes	Public workspace subdomain

Response:

{
  "published": true,
  "published_url": "https://client-report.boostgpt.co"
}

Unpublish Workspace

PUT /v1/bot/workspace/unpublish

Parameter	Type	Required	Description
project_id	string	Yes	Project ID
bot_id	string	Yes	Bot ID
workspace_uuid	string	Yes	Workspace UUID

A workspace with an attached custom domain must have the custom domain removed before it can be unpublished.

Custom Domains

Workspace custom domains require a plan that includes custom domains and a published workspace.

Add Custom Domain

POST /v1/bot/workspace/domain/add

Parameter	Type	Required	Description
project_id	string	Yes	Project ID
bot_id	string	Yes	Bot ID
workspace_uuid	string	Yes	Workspace UUID
custom_domain	string	Yes	Domain to attach, e.g. report.example.com

The response includes the DNS target. The domain starts as pending until verification completes.

Domain Status

GET /v1/bot/workspace/domain/status?project_id={project_id}&bot_id={bot_id}&workspace_uuid={uuid}

Refreshes and returns the custom domain verification status.

Domain Info

GET /v1/bot/workspace/domain/info?project_id={project_id}&bot_id={bot_id}&workspace_uuid={uuid}

Returns the workspace subdomain URL, custom domain URL, DNS target, and custom domain status.

Remove Custom Domain

DELETE /v1/bot/workspace/domain/remove?project_id={project_id}&bot_id={bot_id}&workspace_uuid={uuid}

Next Steps

Chat API

Send messages and receive AI responses

API Reference

Complete API documentation