Shell

Use Shell when server code needs to inspect or change files through Unix-like commands. You choose which commands, files, processes, network access, and timeouts each provider supports.

Shell runs commands through a provider. Sandbox can supply an isolated provider, but it doesn't replace Shell's sessions, command analysis, or execution policy.

Quick start

pnpm add @vite-hub/shell @vite-hub/workspace

import { createShellRuntime } from '@vite-hub/shell'
import { createJustBashProvider } from '@vite-hub/shell/providers/just-bash'
import { createReadonlyWorkspaceFs, workspaceMountPoint } from '@vite-hub/shell/workspace'
import { useWorkspace } from '@vite-hub/workspace'

const workspace = useWorkspace('docs')
const shell = createShellRuntime({
  provider: createJustBashProvider({
    commands: ['pwd', 'ls', 'cat', 'rg'],
    cwd: workspaceMountPoint,
    fs: createReadonlyWorkspaceFs(workspace.fs),
  }),
})

await shell.exec('rg auth docs', { cwd: workspaceMountPoint })

Public imports

Shell Runtime, Session, Policy, Boundary, Observation, Provider, process, and Workspace filesystem types are exported from these entrypoints.

Providers

Shell providers implement ShellExecutionProvider. Shell has provider adapters, not Vite Integration output.

For Cloudflare Workers agents that use Cloudflare's structured shell runtime, install the Cloudflare packages beside ViteHub Shell:

pnpm add @cloudflare/shell @cloudflare/codemode

@cloudflare/shell exposes structured state.* and Git tools through @cloudflare/codemode; it is not a Bash interpreter. Use createCloudflareShellProvider() when the Cloudflare runtime provides a command-execution client. Use a custom ShellExecutionProvider to translate ViteHub Shell calls into @cloudflare/shell state operations.

Create a Shell runtime

Pass an execution provider to createShellRuntime(). The built-in Just Bash provider runs Bash-compatible commands against the filesystem adapter you supply.

import { createShellRuntime } from '@vite-hub/shell'
import { createJustBashProvider } from '@vite-hub/shell/providers/just-bash'
import { createReadonlyWorkspaceFs, workspaceMountPoint } from '@vite-hub/shell/workspace'
import { useWorkspace } from '@vite-hub/workspace'

export async function searchDocs() {
  const workspace = useWorkspace('docs')
  const runtime = createShellRuntime({
    provider: createJustBashProvider({
      commands: ['pwd', 'ls', 'cat', 'rg'],
      cwd: workspaceMountPoint,
      fs: createReadonlyWorkspaceFs(workspace.fs),
    }),
  })

  return runtime.exec('rg auth docs', {
    cwd: workspaceMountPoint,
  })
}

The provider controls available commands. The Workspace filesystem controls whether file writes can happen.

Runtime options

runtime.exec(command, options?) creates a short-lived session, runs one command, disposes the session, and returns a Shell Observation.

Use Shell sessions

A Shell Session adds stateful policy around repeated commands, output size, timeouts, and process budget.

import { createShellRuntime } from '@vite-hub/shell'

export async function inspect(runtime: ReturnType<typeof createShellRuntime>) {
  const session = runtime.createSession({
    policy: {
      maxOutputLength: 10_000,
      maxShellCalls: 4,
      timeout: 30_000,
    },
  })

  try {
    return await session.exec('pwd')
  }
  finally {
    await session.dispose()
  }
}

Session and exec options

Analyze commands

Command Analysis reports facts about a command before execution. The caller makes the final policy decision.

import { analyzeShellCommand } from '@vite-hub/shell'

export async function analyze(command: string) {
  return analyzeShellCommand(command)
}

analyzeShellCommand(command, options?) uses sh-syntax and returns ok, parser name, command names, and flags for pipelines, redirects, heredocs, and command substitution. ShellAnalyzeOptions accepts maxInputBytes and timeoutMs.

Don't treat analysis as sandbox enforcement. The execution provider and caller policy control what the command can do.

Shell observation shape

Connect Shell to Agents

Agents use Shell through Capabilities, usually workspaceShell(). That Capability exposes shell-shaped Workspace inspection and optional structured Workspace mutation tools through Workspace Scope, Workspace rules, and Shell policy.

The global Agent bash tool is separate from the Shell runtime. Capabilities register executables, and ViteHub sends each structured call through an executable Workspace Session. Read the Bash concept for the Agent contract.

Don't expose a raw Shell runtime to a model. Use Official capabilities so its policy, metadata, driver support, and tools stay attached to the Agent Definition.

Production checks

Configure command, filesystem, network, process, streaming, and timeout access before running commands. A Shell Network Grant permits only the network access it names.

Use Sandbox when the app needs provider-managed isolation. Use Shell when the app needs controlled command semantics over a declared Shell Workspace.

Next steps

• Understand the model-facing Bash tool.
• Use Workspace for file-tree state.
• Use Sandbox for isolated execution providers.
• Expose command inspection to agents through Official capabilities.