# Shell

Run simple shell commands like ls, cat, and rg from your server, with limits you control.

Hosts: Node, Docker, Cloudflare.

```ts [server/utils/docs-shell.ts]
import { createShellRuntime } from 'vite-hub/shell'
import {
  createJustBashProvider,
} from 'vite-hub/shell/providers/just-bash'
import {
  createReadonlyWorkspaceFs,
} from 'vite-hub/shell/workspace'
import { useWorkspace } from 'vite-hub/workspace'

// A shell that can only read the docs Workspace
export function docsShell() {
  const docs = useWorkspace('docs')
  return createShellRuntime({
    policy: { timeout: 10_000, maxOutputLength: 5_000 },
    // Bash in JavaScript: no real processes
    provider: createJustBashProvider({
      // The only commands it can run
      commands: ['ls', 'cat', 'rg'],
      fs: createReadonlyWorkspaceFs(docs.fs),
    }),
  })
}
```

```ts [server/api/search.get.ts]
import { defineEventHandler } from 'h3'
import { docsShell } from '../utils/docs-shell'

// Find every line that mentions "auth"
export default defineEventHandler(async () => {
  const result = await docsShell().exec('rg auth .')

  // Exit code 0 means the command worked
  return {
    exitCode: result.exitCode,
    output: result.stdout,
  }
})
```

```ts [server/api/overview.get.ts]
import { defineEventHandler } from 'h3'
import { docsShell } from '../utils/docs-shell'

// A session shares one limit across commands
export default defineEventHandler(async () => {
  const session = docsShell().createSession({
    policy: { maxShellCalls: 2 },
  })
  try {
    const files = await session.exec('ls')
    const intro = await session.exec('cat intro.md')
    return [files.stdout, intro.stdout]
  }
  finally {
    await session.dispose()
  }
})
```

```ts [server/api/check.post.ts]
import { defineEventHandler, readValidatedBody } from 'h3'
import * as v from 'valibot'
import { analyzeShellCommand } from 'vite-hub/shell'

// Read what a command does before you run it
export default defineEventHandler(async (event) => {
  const body = await readValidatedBody(event, body => v.parse(v.object({ command: v.string() }), body))
  const facts = await analyzeShellCommand(body.command)

  // For example: { commands: ['rg'], ... }
  return {
    commands: facts.commands,
    hasPipelines: facts.hasPipelines,
  }
})
```

### [Choose the allowed commands](https://vitehub.dev/docs/shell/configure#providers)

List the commands a shell can run. Network access is off unless you turn it on.

### [Work on your files](https://vitehub.dev/docs/shell/server-api#workspace-filesystem)

Commands see [Workspace](https://vitehub.dev/docs/workspace) files under `/workspace`, read-only or writable.

### [Clear results](https://vitehub.dev/docs/shell/server-api#shell-observation-shape)

Each command returns its exit code, output, and errors. A blocked command returns exit code `126`.

### [Limits across commands](https://vitehub.dev/docs/shell/server-api#use-shell-sessions)

A session shares one limit for calls, output size, and time across many commands.

### [Check a command first](https://vitehub.dev/docs/shell/server-api#analyze-commands)

`analyzeShellCommand()` lists the programs, pipes, and redirects in a command, so you decide what to allow.

### [Stop slow commands](https://vitehub.dev/docs/shell/configure#session-and-exec-options)

Set a timeout, or cancel a command with an `AbortSignal`.

Use Shell to run bounded Unix-like commands with explicit filesystem, process, network, timeout, and policy access.

Treat command text, working directory, environment, and network access as authority. Prefer an allowlist and a small working directory. Resource bounds and cancellation are part of the run contract.

Prove a permitted command, a rejected command, timeout, cancellation, output limit, and cleanup.

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

- [Overview](https://vitehub.dev/raw/docs/shell.md) (this page)
- [Get started](https://vitehub.dev/raw/docs/shell/get-started.md)
- [Configure](https://vitehub.dev/raw/docs/shell/configure.md)
- [Server API](https://vitehub.dev/raw/docs/shell/server-api.md)
- [Limits and errors](https://vitehub.dev/raw/docs/shell/limits-and-errors.md)

Next: [SHELL_R0001](https://vitehub.dev/raw/docs/shell/diagnostics/shell_r0001.md)

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