Workspaces

client.workspaces manages the private file systems your agents work in. Every agent already gets a workspace when you create it, so use these methods when you want to share one workspace between agents, set its network rules, or clean it up. To learn how workspaces behave, read Workspaces.

const workspace = await client.workspaces.create({
  name: "Release files",
  networkPolicy: { mode: "allowlist", allowedHosts: ["registry.npmjs.org"] },
});

await client.agents.update({ agentId, workspaceId: workspace.id });

Every method takes one input object and accepts an optional abortSignal. Reading or changing a workspace record does not touch its files.

Available operations

Methods

create()

Creates an empty workspace.

Signature: create(input?: CreateWorkspaceBody & ResourceRequestOptions): Promise<Workspace>

const workspace = await client.workspaces.create({
  name: "Release files",
  userId: "user_42",
});

WorkspaceNetworkPolicy is one of:

• { mode: "unrestricted" }: commands can reach any host.
• { mode: "allowlist", allowedHosts: string[] }: only the listed hosts, at least one.
• { mode: "offline" }: no outbound network.

The policy applies to every agent that uses the workspace. Returns Workspace. Errors: validation_failed.

list()

Lists workspaces, newest first.

Signature: list(input?: WorkspacesListOptions): Promise<WorkspacesListResponse>

const { data, nextCursor } = await client.workspaces.list({ userId: "user_42" });

Returns WorkspacesListResponse. Errors: validation_failed, invalid_cursor.

get()

Reads one workspace.

Signature: get(input: { workspaceId: string } & ResourceRequestOptions): Promise<Workspace>

const workspace = await client.workspaces.get({ workspaceId });

Returns Workspace. Errors: validation_failed, workspace_not_found.

update()

Changes a workspace's name, metadata, or network rules.

Signature: update(input: UpdateWorkspaceBody & { workspaceId: string } & ResourceRequestOptions): Promise<Workspace>

const workspace = await client.workspaces.update({
  workspaceId,
  networkPolicy: { mode: "offline" },
});

Pass at least one field. Fields you leave out stay as they are, and userId cannot change. Returns Workspace. Errors: validation_failed, workspace_not_found.

delete()

Deletes a workspace and all its files.

Signature: delete(input: { workspaceId: string } & ResourceRequestOptions): Promise<"completed" | "pending">

const status = await client.workspaces.delete({ workspaceId });

Move every agent that uses the workspace to another one first. Returns "completed" when the workspace is fully deleted, or "pending" when the rest of the cleanup finishes in the background.

Errors:

• workspace_in_use: agents still use it. details.agentIds lists them.
• workspace_busy: the workspace is running a command. Try again shortly.
• workspace_not_found: no such workspace in your tenant.
• service_unavailable: try again with backoff.

Response types

Workspace

WorkspacesListResponse

interface WorkspacesListResponse {
  data: Workspace[];
  nextCursor: string | null;
}

Pass nextCursor to the next list() call until it is null.

Next

• Workspaces
• Agents reference
• Skills reference