# Workspace

A folder of files your server can read and write, with rules for each path and a record of every change.

Hosts: Node, Docker, Cloudflare, Vercel.

```ts [server/workspaces/docs.ts]
import { defineWorkspace, glob } from 'vite-hub/workspace'

// This file defines the docs Workspace.
export default defineWorkspace({
  sources: {
    // Markdown from your docs folder
    docs: glob({ cwd: 'docs', include: '**/*.md' }),
  },
  rules: {
    // Your files stay read-only
    'docs/**': { write: false },
  },
})
```

```ts [server/workspaces/handbook.ts]
import { defineWorkspace, github } from 'vite-hub/workspace'

// Files from a GitHub repository.
// Private repositories read GITHUB_TOKEN.
export default defineWorkspace({
  sources: {
    handbook: github({
      repo: 'acme/handbook',
      ref: 'main',
    }),
  },
})
```

```ts [server/api/docs.get.ts]
import { defineEventHandler } from 'h3'
import { useWorkspace } from 'vite-hub/workspace'

// List every Markdown file
export default defineEventHandler(async () => {
  const docs = useWorkspace('docs')
  return docs.fs.glob('**/*.md')
})
```

```ts [server/api/drafts.post.ts]
import { defineEventHandler } from 'h3'
import { useWorkspace } from 'vite-hub/workspace'

// Write a draft, return the change
export default defineEventHandler(async () => {
  const docs = useWorkspace('docs', { mode: 'write' })

  await docs.fs.writeFile('drafts/hello.md', '# Hello')
  return docs.diff()
})
```

```md [docs/intro.md]
# Welcome

This file is in your project.
The Workspace shows it under docs/intro.md.
```

### [One file defines it](https://vitehub.dev/docs/workspace/configure#workspace-definition-options)

Add a file to `server/workspaces`. The file name is the Workspace name.

### [Start from files you have](https://vitehub.dev/docs/workspace/configure#source-binding-options)

Show files from your project or GitHub. The originals stay unchanged.

### [Read and write from a route](https://vitehub.dev/docs/workspace/server-api#runtime-facade)

Use `readFile()`, `writeFile()`, and `glob()` from `useWorkspace()`.

### [Decide who can write where](https://vitehub.dev/docs/workspace/configure#workspace-definition-options)

Make a path read-only or limit its file types.

### [See every change](https://vitehub.dev/docs/workspace/server-api#retained-folder-history)

`diff()` lists changes. A snapshot saves a version to read later.

### [Same code in development and production](https://vitehub.dev/docs/workspace/hosts)

Files stay on disk in development. Routes do not change when you deploy.

Use Workspace for persistent file-tree state, Sources, access rules, snapshots, diffs, and sessions. A Workspace is the boundary for file authority and write-back.

Set the root, provider, mode, and write rules explicitly. Mount only the Sources an invocation needs. A mounted Source is context and does not imply write access.

Prove read, scoped write, diff, and restart or provider recovery. Inspect snapshots and generated Workspace state before relying on persistence.

<!-- vitehub-docs:section-links -->
## In this section

- [Overview](https://vitehub.dev/raw/docs/workspace.md) (this page)
- [Get started](https://vitehub.dev/raw/docs/workspace/get-started.md)
- [Configure](https://vitehub.dev/raw/docs/workspace/configure.md)
- [Server API](https://vitehub.dev/raw/docs/workspace/server-api.md)
- [Agent capability](https://vitehub.dev/raw/docs/workspace/agent-capability.md)
- [Hosts](https://vitehub.dev/raw/docs/workspace/hosts.md)
- [Limits and errors](https://vitehub.dev/raw/docs/workspace/limits-and-errors.md)
- [Workspaces and Sources](https://vitehub.dev/raw/docs/workspace/concepts.md)

Next: [WORKSPACE_R0001](https://vitehub.dev/raw/docs/workspace/diagnostics/workspace_r0001.md)

All pages: [llms.txt](https://vitehub.dev/llms.txt)
