Workspace and Sources

A Workspace is a named persistent file tree. A Source is a named origin that exposes read-only addressable files, items, or controlled request access through a Workspace.

Workspace owns file-tree behavior. Source owns the origin. Mount only says where a Source appears inside the Workspace File Tree.

Why it exists

Agents need inspectable files, but they should not receive the project filesystem by accident. Workspace makes the file boundary explicit, and Sources make external or local read-only origins addressable.

Workspace is also useful outside agents. Server code can read, write, snapshot, diff, and open Workspace sessions through the Workspace Runtime Surface.

Define a workspace

Declare Sources inside the Workspace that owns their placement and policy.

import { defineWorkspace, glob } from '@vite-hub/workspace'

export default defineWorkspace({
  sources: {
    docs: glob({
      cwd: '.',
      include: ['README.md', 'docs/**/*.md'],
      instructions: 'Use these docs for public product behavior.',
    }),
  },
  rules: {
    '/**': { write: false },
    '/drafts/**': { write: true, mediaType: 'text/markdown' },
  },
})

instructions is Source Instruction text for model-backed Agent Drivers. It does not grant access, change Workspace Scope, or make hidden Sources visible.

Agent access

An Agent with Workspace context does not automatically get unrestricted file tools. Attach a Capability such as workspaceShell() when the model should inspect or mutate Workspace files.

Workspace Scope narrows the visible Workspace File Tree for one Agent Invocation. Access can select that scope from trusted host, auth, or invocation context, but the model does not choose the scope.

Inspect it

Use useWorkspace() from server code to inspect the runtime file tree. Add .vitehub/types/**/*.d.ts to tsconfig.json when you want generated Workspace names to narrow TypeScript types.

API-backed Sources can expose Source Request Descriptors at .vitehub/sources/<sourceKey>.json when they are visible through the selected scope. Those descriptors guide controlled shell requests without exposing credentials.

Next steps

• Read Workspace and Sources in Server primitives.
• Read Workspace context for agent-specific examples.
• Read Capabilities API before exposing Workspace tools to a model.