Workspaces

Workspaces provide file system and sandbox capabilities for agents.

Topics

Overview - Introduction to workspaces
Filesystem - File operations in workspaces
Sandbox - Secure execution environments
LSP Inspection - Language server protocol integration
Skills - Reusable agent capabilities
Search and Indexing - Search within workspaces

Workspaces Overview

Workspaces provide agents with persistent storage and execution environments.

Features

Filesystem access - Read and write files
Sandboxed execution - Run code safely
LSP integration - Language server protocol support
Skills - Reusable agent capabilities
Search - Full-text and semantic search

Creating a Workspace

import { Workspace } from '@mastra/core';

const workspace = new Workspace({
  name: 'my-workspace',
  filesystem: {
    type: 'local',
    path: './workspace-data',
  },
  sandbox: {
    type: 'docker',
    image: 'mastra/sandbox:latest',
  },
});

Workspace Types

Local - Filesystem on the host machine
Remote - Filesystem on a remote server
Cloud - Cloud storage (S3, GCS, etc.)

Filesystem

File operations within workspaces.

Filesystem Operations

const fs = workspace.getFilesystem();

// Read a file
const content = await fs.read('project/readme.md');

// Write a file
await fs.write('output/results.txt', 'Results here');

// List directory
const files = await fs.list('project/');

// Delete a file
await fs.delete('output/temp.txt');

Filesystem Types

LocalFilesystem - Local disk storage
S3Filesystem - Amazon S3
GCSFilesystem - Google Cloud Storage
AgentFSFilesystem - Agent-managed filesystem

Path Resolution

// Resolve relative paths
const absPath = fs.resolve('relative/path');

// Normalize paths
const normPath = fs.normalize('/path/./to/../file');

Sandbox

Sandbox provides secure execution environments for agent code.

Sandbox Types

Docker - Containerized execution
E2B - Cloud-based sandbox
Daytona - Managed sandbox platform
Local - Local execution (development only)

Using the Sandbox

const sandbox = workspace.getSandbox();

// Execute code
const result = await sandbox.run(`
  const x = 10;
  const y = 20;
  return x + y;
`);

console.log(result.output); // 30

Sandbox Configuration

const sandbox = workspace.createSandbox({
  type: 'docker',
  image: 'mastra/sandbox:node18',
  timeout: '30s',
  memory: '512MB',
  network: true,
});

Security

Sandboxes provide:

Process isolation
Network restrictions
Filesystem access control
Resource limits

LSP Inspection

Language Server Protocol integration for code analysis.

LSP Features

Autocomplete - Code completion suggestions
Diagnostics - Error and warning detection
Go to definition - Navigate to definitions
Find references - Locate usage of symbols
Hover information - Documentation on hover

Using LSP

const lsp = workspace.getLSP('javascript');

const diagnostics = await lsp.analyze('src/index.ts');
console.log(diagnostics.errors);
console.log(diagnostics.warnings);

Language Support

// Configure LSP for different languages
workspace.configureLSP('python', { pyright: true });
workspace.configureLSP('rust', { rustAnalyzer: true });

Code Actions

const actions = await lsp.getCodeActions('src/index.ts', {
  line: 10,
  character: 5,
});

for (const action of actions) {
  console.log(action.title, action.command);
}

Skills

Skills are reusable agent capabilities that can be shared and composed.

What are Skills?

Skills are pre-defined agent behaviors that:

Encapsulate commonly used patterns
Can be composed together
Are easily shareable across projects
Include prompts, tools, and configurations

Built-in Skills

import { skills } from '@mastra/core';

// Use a built-in skill
const codeReviewSkill = skills.get('code-review');

Creating Skills

const mySkill = new Skill({
  name: 'my-skill',
  description: 'Does something useful',
  prompts: ['prompt1.md', 'prompt2.md'],
  tools: [myTool],
  configuration: {
    temperature: 0.7,
    maxTokens: 1000,
  },
});

Using Skills

const agent = await workspace.createAgent({
  skills: [codeReviewSkill, mySkill],
});

Publishing Skills

Create a skill package
Test the skill thoroughly
Publish to the skills registry

Search and Indexing

Full-text and semantic search within workspaces.

Search Types

Full-text Search

const results = await workspace.search('query', {
  type: 'text',
  files: ['**/*.md'],
});

for (const result of results) {
  console.log(result.file, result.matches);
}

Semantic Search

const results = await workspace.search('concept', {
  type: 'semantic',
  topK: 10,
});

for (const result of results) {
  console.log(result.content, result.score);
}

Indexing

// Index a directory
await workspace.index('src/', {
  type: 'text',
  glob: '**/*.{ts,js}',
});

// Index with semantic embeddings
await workspace.index('docs/', {
  type: 'semantic',
  embedder: 'openai',
});

Search Configuration

const config = {
  indexPath: './.workspace/index',
  maxFileSize: '10MB',
  exclude: ['node_modules', 'dist'],
  updateStrategy: 'incremental',
};