Web workbench guide

This guide is for users trying DataFoundry in the browser. After reading it, you can create data tasks, select resources, stop runs, view trace and outputs, and restore server sessions.

How to start

Start the full local stack from the repository root:

npm run dev

Open:

http://127.0.0.1:3000/data-tasks

Start frontend and backend separately:

npm run dev:api
npm run dev:web

The frontend connects to the local backend by default:

NEXT_PUBLIC_AGENT_RUNTIME_URL=http://127.0.0.1:8787/api/copilotkit
NEXT_PUBLIC_CONFIG_API_URL=http://127.0.0.1:8787

If you only set NEXT_PUBLIC_AGENT_RUNTIME_URL, the frontend derives the configuration API root from the /api/copilotkit URL.

Identity and first-run guide

In local development, the Web workbench starts with a development user and the default workspace. The user menu at the bottom of the left pane shows the current user. Local development can switch users through the dev identity API; production password mode shows sign-in, account creation, password reset, and sign-out screens instead.

The Web workbench sends the same identity to configuration REST calls and CopilotKit agent runs. When the user changes, the workbench remounts the data-task workspace so sessions, selected resources, files, artifacts, live run state, and quick-start progress stay scoped to that user.

First-time users see a quick-start guide. Use the round ? button near the user area to reopen it. The guide can fill an example prompt into the chat input and waits for you to send the task before moving to the console step.

Layout

The Web workbench has three columns:

Area	Purpose
Left	Manage sessions and workspace resources.
Center	Enter questions; view agent replies, step cards, and human confirmations.
Right	Overview, trace, outputs, step details, and workspace files.

On narrow windows, the right console collapses into a drawer. Use the console entry at the top of the chat area to reopen it.

Run your first task

1. Click New data task on the left.
2. Keep the built-in DuckDB demo data source.
3. Select Server default or your configured model next to the input box.
4. Enter a question and send.

Example:

List the tables in this data source and describe the main fields of each table.

After sending, the center shows agent replies and step cards. The right console shows run status, trace, and outputs in sync.

Left panel: sessions and resources

The left panel manages two kinds of content:

Content	What you can do
Data tasks	Create, switch, rename, pin, and delete tasks.
Workspace resources	Manage data sources, knowledge bases, agent tools, and assets.
User menu	View the current user, open settings, sign out, or switch local development users.

Resource entry points:

Resource	Purpose
Data Sources	Add sources, test connections, fetch schema, browse table structure, and preview table data.
Knowledge	Create knowledge bases, upload documents, import file assets, rebuild indexes.
Agent Tools	Manage MCP servers and Skills.
Assets	View, download, and delete reusable workspace files.

Model selection is not in the left resource area. Use the model selector next to the input box for the model used in the current analysis.

Center: conversation, steps, and confirmations

The center panel handles questions and shows the agent analysis process. During a run you see:

• Streaming agent replies.
• Step cards for schema inspection, SQL execution, file reads, and similar actions.
• States such as waiting for input, running, completed, failed, or canceled.
• Human confirmation flows when the backend asks you to choose an option or add information.

Click a step card to open its details in the right console. Use this path to verify inputs, tool calls, and outputs for each step.

Input box features

Feature	Purpose
Model selection	Choose an LLM profile for this analysis.
Session resource toggles	Control data sources, knowledge bases, MCP servers, and Skills available in this session.
@ mentions	Pin a data source, file, or resource for a single question.
File upload	Upload attachments needed for this analysis.
Stop run	Cancel the running agent run.

Resource selection has three layers:

1. Workspace defaults: long-term configuration in the left resource panel.
2. Session resources: toggles below the input box; affect only the current task.
3. Question resources: @ mentions for a single turn.

For a first trial, keep the defaults.

Right panel: task console

Overview

Overview shows the current question, step count, success rate, output count, token usage, and a live step list. Use it to tell whether the task is still running, failed, or already produced files or tables.

Trace

Trace shows the agent execution chain in time order. Common entries:

1. Start run.
2. Inspect data source schema.
3. Run read-only SQL or read files.
4. Create table, chart, SQL, report, or file outputs.

When you need to explain where a result came from, start with trace, then open step details.

Outputs

Outputs are reusable results left by the agent:

Type	Actions
Tables	Preview, search, sort, download, or export CSV/XLSX.
Charts	Preview, download, or export supported backend formats.
SQL	View queries executed by the agent.
Reports	View structured conclusions and Markdown content.
Files	Download, or add to the workspace and reference in later tasks.

File outputs can be promoted to cross-session workspace files with Add to workspace. Table and chart download/export use /api/v1/artifacts/:id/download and /api/v1/artifacts/:id/export.

Details

Details show inputs, outputs, token usage, tool call arguments, and tool results for a single step. Open details from a center step card or from the trace list.

Workspace files

The workspace files panel supports:

• Listing reusable files.
• Downloading file content.
• Deleting file references.

Chat attachments are uploaded from the input box via /api/v1/chat/uploads. After a file output is added to the workspace, it appears in the workspace file list.

Data source browsing

The data source panel supports two read-only views:

Feature	API
Schema browse	GET /api/v1/datasources/:id/schema
Table preview	GET /api/v1/datasources/:id/tables/:table/preview

Schema browse supports search by table or field name. Table preview supports schema, limit, offset, and orderBy query parameters.

Stop run

When a run takes too long or the question was wrong, use the stop button near the input box. The frontend calls:

POST /api/v1/runs/:id/cancel

The backend cancels the active run or marks a persisted run as canceled. Events and outputs already produced remain available for troubleshooting.

Session restore

The Web workbench restores history through server session APIs:

API	Purpose
GET /api/v1/sessions	Read the left session list.
PATCH /api/v1/sessions/:id	Update session title.
GET /api/v1/sessions/:id/conversation	Restore conversation, tool calls, pending interactions, and run events.
GET /api/v1/artifacts?sessionId=:id	Restore outputs for that session.

After refresh or reopening the workbench, restore prior tasks from the left task list. The center shows conversation history; the right console can replay run events and outputs. New questions continue the session context for that task.

Example questions

Scenario	Example
Explore tables	What tables are in this data source? What are the main fields?
Metric aggregation	Count orders and GMV by channel.
Trend analysis	Analyze GMV trend over the last 30 days and find the day with the largest swing.
Follow-up	Break that down by category.
Named source	Using the sales-pg data source, summarize orders over the last 7 days.

Capability boundaries

• File upload is controlled by chat.fileUpload and files capabilities.
• Image input is controlled by chat.imageInput.
• Knowledge, MCP, and Skill behavior depends on workspace configuration and knowledge, mcp, and skills capabilities.
• Database queries go through Data Gateway on read-only analysis paths only.
• Credentials are submitted only when creating or updating resources; read APIs do not return plaintext secrets.

Continue with Data sources guide.