Shell

Shell owns controlled Unix-like command environments. Use it when server code needs command-shaped inspection or mutation with explicit execution, filesystem, process, network, timeout, and policy boundaries.

Shell is not Sandbox. Sandbox can provide an isolated execution provider, but Shell defines the command runtime, Shell Session lifecycle, Command Analysis, Shell Observations, and Shell Boundary.

Quick start

pnpm add @vite-hub/shell

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.

Create a Shell Runtime

Use createShellRuntime() with an Execution Provider. The built-in Just Bash Provider runs Bash-compatible commands against an explicit filesystem adapter.

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 produces facts about a command before execution. The caller owns 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.

Do not treat analysis as sandbox enforcement. Execution Providers and caller-owned policy enforce the actual boundary.

Shell Observation shape

Connect it 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.

Do not expose a raw Shell Runtime to a model. Use Official capabilities so policy, metadata, driver support, and tool surfaces stay attached to the Agent Definition.

Production boundaries

Declare command, filesystem, network, process, streaming, and timeout boundaries before running commands. Shell Network Grants are explicit; normal network access is not implied.

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

• Use Workspace for file-tree state.
• Use Sandbox for isolated execution providers.
• Expose command inspection to agents through Official capabilities.