VoltAgent · omeraplak · Feb 8, 2026 · Feb 7, 2026 · Feb 7, 2026 · Feb 7, 2026
diff --git a/.changeset/cruel-jobs-hunt.md b/.changeset/cruel-jobs-hunt.md
@@ -0,0 +1,61 @@
+---
+"@voltagent/sandbox-daytona": patch
+"@voltagent/serverless-hono": patch
+"@voltagent/server-elysia": patch
+"@voltagent/sandbox-e2b": patch
+"@voltagent/server-core": patch
+"@voltagent/server-hono": patch
+"@voltagent/core": patch
+---
+
+feat: introduce experimental Workspace support with filesystem, sandbox execution, search indexing, and skill discovery; add global workspace defaults and optional sandbox providers (E2B/Daytona). - #1008
+
+Example:
+
+```ts
+import { Agent, Workspace, LocalSandbox, NodeFilesystemBackend } from "@voltagent/core";
+
+const workspace = new Workspace({
+  id: "support-workspace",
+  operationTimeoutMs: 30_000,
+  filesystem: {
+    backend: new NodeFilesystemBackend({
+      rootDir: "./.workspace",
+    }),
+  },
+  sandbox: new LocalSandbox({
+    rootDir: "./.sandbox",
+    isolation: { provider: "detect" },
+    cleanupOnDestroy: true,
+  }),
+  search: {
+    autoIndexPaths: ["/notes", "/tickets"],
+  },
+  skills: {
+    rootPaths: ["/skills"],
+  },
+});
+
+const agent = new Agent({
+  name: "support-agent",
+  model,
+  instructions: "Use workspace tools to review tickets and summarize findings.",
+  workspace,
+  workspaceToolkits: {
+    filesystem: {
+      toolPolicies: {
+        tools: { write_file: { needsApproval: true } },
+      },
+    },
+  },
+});
+
+const { text } = await agent.generateText(
+  [
+    "Scan /tickets and /notes.",
+    "Use workspace_search to find urgent issues from the last week.",
+    "Summarize the top 3 risks and include file paths as citations.",
+  ].join("\n"),
+  { maxSteps: 40 }
+);
+```
diff --git a/.gitignore b/.gitignore
@@ -166,6 +166,8 @@ vitest.config.*.timestamp*
 # claude
 .claude
 skills
+!packages/core/src/workspace/skills
+!packages/core/src/workspace/skills/**
 
 dev-debug.log
 node_modules/
@@ -179,3 +181,7 @@ node_modules/
 
 # serena
 .serena
+
+
+# example skills
+!examples/with-workspace/workspace/skills
diff --git a/examples/README.md b/examples/README.md
@@ -83,6 +83,7 @@ Create a multi-agent research workflow where different AI agents collaborate to
 ## All Examples
 
 - [Base Starter](./base) — Minimal VoltAgent starter with a single agent, memory, and dev server.
+- [Workspace](./with-workspace) — Workspace filesystem, sandbox execution, search, and skills.
 - [Summarization](./with-summarization) — Agent summarization with a low trigger window for easy testing.
 - [Retries and Fallbacks](./with-retries-fallback) — Model fallback list with per-model retries and agent-level defaults.
 - [Middleware](./with-middleware) — Input/output middleware with retry feedback.

diff --git a/examples/with-workspace/.env.example b/examples/with-workspace/.env.example
@@ -0,0 +1 @@
+OPENAI_API_KEY=your_openai_api_key_here
diff --git a/examples/with-workspace/.gitignore b/examples/with-workspace/.gitignore
@@ -0,0 +1,3 @@
+node_modules
+dist
+.DS_Store
diff --git a/examples/with-workspace/README.md b/examples/with-workspace/README.md
@@ -0,0 +1,61 @@
+<div align="center">
+<a href="https://voltagent.dev/">
+<img width="1800" alt="435380213-b6253409-8741-462b-a346-834cd18565a9" src="https://github.com/user-attachments/assets/452a03e7-eeda-4394-9ee7-0ffbcf37245c" />
+</a>
+
+<br/>
+<br/>
+
+<div align="center">
+    <a href="https://voltagent.dev">Home Page</a> |
+    <a href="https://voltagent.dev/docs/">Documentation</a> |
+    <a href="https://github.com/voltagent/voltagent/tree/main/examples">Examples</a> |
+    <a href="https://s.voltagent.dev/discord">Discord</a> |
+    <a href="https://voltagent.dev/blog/">Blog</a>
+</div>
+</div>
+
+<br/>
+
+<div align="center">
+    <strong>VoltAgent is an open source TypeScript framework for building and orchestrating AI agents.</strong><br>
+Escape the limitations of no-code builders and the complexity of starting from scratch.
+    <br />
+    <br />
+</div>
+
+<div align="center">
+
+[![npm version](https://img.shields.io/npm/v/@voltagent/core.svg)](https://www.npmjs.com/package/@voltagent/core)
+[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.0-4baaaa.svg)](CODE_OF_CONDUCT.md)
+[![Discord](https://img.shields.io/discord/1361559153780195478.svg?label=&logo=discord&logoColor=ffffff&color=7389D8&labelColor=6A7EC2)](https://s.voltagent.dev/discord)
+[![Twitter Follow](https://img.shields.io/twitter/follow/voltagent_dev?style=social)](https://twitter.com/voltagent_dev)
+
+</div>
+
+<br/>
+
+<div align="center">
+<a href="https://voltagent.dev/">
+<img width="896" alt="VoltAgent Schema" src="https://github.com/user-attachments/assets/f0627868-6153-4f63-ba7f-bdfcc5dd603d" />
+</a>
+
+</div>
+
+## VoltAgent: Workspace Example
+
+This example shows how to attach a Workspace to an agent, giving it a persistent filesystem, sandboxed command execution, file search (BM25 + vector), and reusable skills loaded from `SKILL.md` files.
+
+## Try Example
+
+```bash
+npm create voltagent-app@latest -- --example with-workspace
+```
+
+## Highlights
+
+- Workspace filesystem rooted at `./workspace`
+- Sandbox execution with `execute_command`
+- Workspace search via `workspace_index` and `workspace_search`
+- Skills loaded from `/skills` with `workspace_list_skills` and `workspace_read_skill`
+- Filesystem extras: `stat`, `mkdir`, and `list_tree`
diff --git a/examples/with-workspace/package.json b/examples/with-workspace/package.json
@@ -0,0 +1,38 @@
+{
+  "name": "voltagent-example-with-workspace",
+  "author": "",
+  "dependencies": {
+    "@ai-sdk/openai": "^3.0.0",
+    "@voltagent/cli": "^0.1.21",
+    "@voltagent/core": "^2.3.3",
+    "@voltagent/libsql": "^2.1.0",
+    "@voltagent/logger": "^2.0.2",
+    "@voltagent/server-hono": "^2.0.4",
+    "ai": "^6.0.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^24.2.1",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
+  },
+  "keywords": [
+    "agent",
+    "ai",
+    "voltagent"
+  ],
+  "license": "MIT",
+  "private": true,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/VoltAgent/voltagent.git",
+    "directory": "examples/with-workspace"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx watch --env-file=.env ./src",
+    "start": "node dist/index.js",
+    "volt": "volt"
+  },
+  "type": "module"
+}
diff --git a/examples/with-workspace/src/index.ts b/examples/with-workspace/src/index.ts
@@ -0,0 +1,83 @@
+import path from "node:path";
+import {
+  Agent,
+  InMemoryVectorAdapter,
+  LocalSandbox,
+  Memory,
+  NodeFilesystemBackend,
+  VoltAgent,
+  Workspace,
+} from "@voltagent/core";
+import { LibSQLMemoryAdapter, LibSQLVectorAdapter } from "@voltagent/libsql";
+import { createPinoLogger } from "@voltagent/logger";
+import { honoServer } from "@voltagent/server-hono";
+
+// Create logger
+const logger = createPinoLogger({
+  name: "with-workspace",
+  level: "info",
+});
+
+// Create Memory instance with vector support for semantic search and working memory
+const memory = new Memory({
+  storage: new LibSQLMemoryAdapter(),
+  embedding: "openai/text-embedding-3-small",
+  vector: new LibSQLVectorAdapter(),
+  generateTitle: true,
+});
+
+const workspaceRoot = path.resolve(process.cwd(), "workspace");
+
+const workspace = new Workspace({
+  id: "workspace-example",
+  name: "Workspace Example",
+  filesystem: {
+    backend: new NodeFilesystemBackend({
+      rootDir: workspaceRoot,
+      virtualMode: true,
+    }),
+  },
+  sandbox: new LocalSandbox({
+    rootDir: workspaceRoot,
+  }),
+  search: {
+    autoIndexPaths: [{ path: "/", glob: "**/*.{md,txt,csv}" }],
+    embedding: "openai/text-embedding-3-small",
+    vector: new InMemoryVectorAdapter(),
+  },
+  skills: {
+    rootPaths: ["/skills"],
+  },
+});
+
+const skillsHook = workspace.createSkillsPromptHook({
+  includeAvailable: true,
+  includeActivated: true,
+});
+
+const agent = new Agent({
+  name: "Workspace Agent",
+  instructions: [
+    "You are a helpful assistant.",
+    "Use the workspace filesystem for notes under /notes and data under /data.",
+    "Use workspace_search to find relevant files before answering.",
+    "Skills live under /skills; activate them when a task matches the description.",
+  ].join(" "),
+  model: "openai/gpt-4o-mini",
+  memory,
+  workspace,
+  hooks: skillsHook,
+  workspaceToolkits: {
+    filesystem: {
+      toolPolicies: {
+        tools: { write_file: { needsApproval: true } },
+      },
+    },
+  },
+});
+
+new VoltAgent({
+  agents: { agent },
+  server: honoServer(),
+  logger,
+});
diff --git a/examples/with-workspace/tsconfig.json b/examples/with-workspace/tsconfig.json
@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "outDir": "dist",
+    "skipLibCheck": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}
diff --git a/examples/with-workspace/workspace/data/customers.csv b/examples/with-workspace/workspace/data/customers.csv
@@ -0,0 +1,6 @@
+customer_id,segment,mrr,region,plan
+C-001,mid-market,1200,NA,Pro
+C-002,enterprise,9000,EU,Enterprise
+C-003,smb,300,NA,Starter
+C-004,mid-market,1800,APAC,Pro
+C-005,enterprise,15000,NA,Enterprise
diff --git a/examples/with-workspace/workspace/notes/meeting-notes.md b/examples/with-workspace/workspace/notes/meeting-notes.md
@@ -0,0 +1,6 @@
+# Meeting Notes (2026-02-01)
+
+- Prioritize CSV import for accounts, contacts, and deals.
+- Add summary dashboard with KPIs: MRR, churn, new logos.
+- Keep UI minimal for beta: timeline + tasks + pipeline.
+- Use feature flags for beta customers.
diff --git a/examples/with-workspace/workspace/notes/project-brief.md b/examples/with-workspace/workspace/notes/project-brief.md
@@ -0,0 +1,10 @@
+# Project Brief: Atlas CRM
+
+Owner: Acme Sales Ops
+Goal: unify customer notes, tasks, and pipeline in one dashboard.
+Constraints: ship MVP by 2026-03-15, keep infra simple (Postgres + Next.js).
+Open questions:
+
+- Import path from legacy CSVs
+- Define role-based permissions
+- Decide on weekly KPI report format
diff --git a/examples/with-workspace/workspace/skills/data-analysis/SKILL.md b/examples/with-workspace/workspace/skills/data-analysis/SKILL.md
@@ -0,0 +1,19 @@
+---
+name: Workspace Data Analyst
+description: Analyze CSV files in the workspace and summarize insights.
+version: "1.0.0"
+tags:
+  - data
+  - csv
+  - analysis
+references:
+  - references/schema.md
+assets:
+  - assets/sample.csv
+---
+
+When analyzing CSV data:
+
+1. Load the file and inspect headers.
+2. Summarize totals, averages, and outliers.
+3. Provide a short insight summary and recommended next steps.
diff --git a/examples/with-workspace/workspace/skills/data-analysis/assets/sample.csv b/examples/with-workspace/workspace/skills/data-analysis/assets/sample.csv
@@ -0,0 +1,6 @@
+customer_id,segment,mrr,region,plan
+S-100,smb,220,NA,Starter
+S-101,mid-market,1400,EU,Pro
+S-102,enterprise,12000,NA,Enterprise
+S-103,mid-market,2100,APAC,Pro
+S-104,smb,180,EU,Starter
diff --git a/examples/with-workspace/workspace/skills/data-analysis/references/schema.md b/examples/with-workspace/workspace/skills/data-analysis/references/schema.md
@@ -0,0 +1,9 @@
+# CSV Schema
+
+Expected columns:
+
+- customer_id: unique identifier
+- segment: smb | mid-market | enterprise
+- mrr: monthly recurring revenue (number)
+- region: NA | EU | APAC
+- plan: Starter | Pro | Enterprise