docs
// EEM Guides

Connect a Chat to an EEM

A chat's tool calls reach an Erebine Execution Manager (EEM) only through an operational workspace: the one the chat lives in, or the one it is linked to. Start the chat there, move it there, or link it, from any client or from erectl.

Overview

A chat started in an operational workspace lives there and runs its tools there. Its memories, decisions, files and graph stay in that workspace, and only owners and operators can open it. Every turn is offered the tools the EEM serving the workspace advertises.

A chat in a chat workspace has no execution scope, so the model is offered no execution tools. Link it to an operational workspace that an EEM serves to run tools there while the conversation stays where it is, or move the chat into the operational workspace.

Who Can Link

Owners and operators of the project set, change and remove the link, and only they can read it. Members never see the control.

Members may run tools here is off by default. Turned on, members of the project who can open the chat run its tools in the linked workspace. Turning it on asks for confirmation first, because members act in a workspace they cannot see or manage. The switch grants no approval rights: who may approve a call is set separately, see Approvals. Unlinking the chat turns the switch off.

On the Web

To start a chat in an operational workspace, select it on the Workspaces page and press New Chat, or start one from a template. The chat lives there and runs its tools there. Its Chats, Artifacts, Knowledge and Graph tabs hold what its chats produce. It has no Client tab: connect an editor client to a chat workspace.

To link a chat in a chat workspace:

  1. Open the chat and its tools menu.
  2. Choose Execute in, or press Alt+X.
  3. Pick an operational workspace from the list. The first choice, This chat's own workspace, is the unlinked state.
  4. Set Members may run tools here if members should run tools, then press Save.

Unlink returns the chat to its own workspace. The chat keeps its history. A chat that lives in an operational workspace has nothing to link: Execute in says its tools run there.

An operational workspace's Chats tab also lists the chats linked to it from other workspaces, marked tools in, each with Move here.

On the Desktop

To create an operational workspace, open Workspaces, press New workspace and choose Operational. Give it a lowercase, hyphenated name, choose one or more types, and name the credential file for each family the types suggest. An owner or operator edits the types and credentials later from the workspace's Edit.

In a chat, open Tools under the composer, or Actions in the chat header, and choose Execute in.... The sheet offers the same list, the same switch, Save and Unlink.

A linked chat names its workspace under the chat title: Tool calls run in prod-k8s. Click the line to change the link.

Scope the chat list to an operational workspace to see its chats and the chats linked to it; a linked chat names the workspace it lives in. New chat there, or New chat here on the workspace in Workspaces, creates the chat in the operational workspace. Actions, Move to workspace... moves the open chat.

After you create a code workspace in the Execution Manager, the workspaces sheet offers Link a chat... on the new workspace. Choose the chat whose tool calls should run there. See Desktop Execution Manager.

On iOS

In Advanced, in a chat, open the chat menu at the top right and choose Execute in. Pick a workspace, set the members switch, and press Save. Unlink returns the chat to its own workspace.

An operational workspace lists its chats and the chats linked to it, in Chats with the workspace picked in the chip at the top, and on its workspace page. The compose button creates the chat in the operational workspace.

To move a chat, press and hold it in Chats and choose Move to workspace. The sheet offers the same choices, switch and words as the web and the desktop.

With erectl

bashlink, read, unlink
erectl chats link-exec-workspace "Release triage" prod-k8s erectl chats exec-workspace "Release triage" erectl chats unlink-exec-workspace "Release triage" erectl chats move "Release triage" prod-k8s

A successful link prints linked "Release triage" (chat_...) -> prod-k8s (ws_...).

Chats and workspaces are named by id (chat_..., ws_...) or by name: an exact match, a case-insensitive match, or a unique prefix. An ambiguous name is refused, and the CLI lists the candidates with their ids.

Add --allow-members to link-exec-workspace to let members run the chat's tools in that workspace. Without it, the link is owner and operator only.

chats move puts the chat in the workspace, with its messages, memories, files and artifacts. Moving into a chat workspace keeps the chat's tools where they run unless --drop-exec-workspace is given.

From the API

A /v1/chat/completions or /v1/responses call runs EEM tools in a linked chat's workspace when it names the chat in X-Chat-Id, by the chat_... id the CLI and the API show. A call that names no chat, or a chat with no link, in a chat workspace has no operational workspace, and each EEM tool call it makes fails with the tool error exec_workspace_required without reaching an EEM. Link the chat, move it with PATCH /v1/chats/{id} and workspace_id, or call POST /v1/exec/invocations with an operational workspace. See erectl exec.

When No EEM Serves the Workspace

The picker marks such a workspace No EEM serves this workspace yet. On the web, the desktop and iOS it also offers Set up an EEM in Operations, which opens the Operations page. The link saves, but tool calls have nowhere to run until an online EEM declares the workspace by name. Declare it with erectl workspaces declare --workspace NAME, with erectl deploy eem --workspace NAME, or from the desktop app. See Deploy Your First EEM.

Troubleshooting

Response Meaning
403 exec_workspace_forbidden You are not an owner or operator, or the workspace does not exist or is not usable from this chat. The answer is the same on purpose: it does not reveal which workspaces exist.
422 exec_workspace_not_operational The target is a chat workspace. Pick an operational workspace.