Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.open-harness.dev/llms.txt

Use this file to discover all available pages before exploring further.

Providers abstract how agents interact with the filesystem and shell. Instead of coupling tool logic to Node.js APIs, OpenHarness defines two interfaces — FsProvider and ShellProvider — that you can implement for any environment. This lets you run the same agent code locally, in a sandbox, or in the cloud, just by swapping the provider.

​
Interfaces

​
FsProvider

interface FsProvider {
  readFile(path: string): Promise<string>;
  writeFile(path: string, content: string): Promise<void>;
  exists(path: string): Promise<boolean>;
  stat(path: string): Promise<FileStat>;
  readdir(path: string): Promise<DirEntry[]>;
  mkdir(path: string, options?: { recursive?: boolean }): Promise<void>;
  remove(path: string, options?: { recursive?: boolean }): Promise<void>;
  rename(oldPath: string, newPath: string): Promise<void>;
  resolvePath(path: string): string;
}

​
ShellProvider

interface ShellProvider {
  exec(
    command: string,
    options?: {
      timeout?: number;
      cwd?: string;
      env?: Record<string, string>;
    }
  ): Promise<ShellResult>;
}

​
Environment

The Environment type combines both providers: 
interface Environment {
  fs: FsProvider;
  shell: ShellProvider;
}

​
Built-in Providers

​
NodeFsProvider

The default filesystem provider for Node.js environments. Uses node:fs under the hood. 
import { createFsTools, NodeFsProvider } from "@openharness/core";

const fsTools = createFsTools(new NodeFsProvider());
Options:
OptionDefaultDescription
cwdprocess.cwd()Working directory for resolving relative paths
maxFileSize10 MBMaximum file size readFile will load
const fs = new NodeFsProvider({
  cwd: "/home/user/project",
  maxFileSize: 20 * 1024 * 1024, // 20 MB
});
Safety features:
  • File size guard — throws FileTooLargeError if a file exceeds maxFileSize
  • Auto-mkdir — writeFile creates parent directories automatically
  • Path resolution — relative paths are resolved from cwd

​
NodeShellProvider

The default shell provider for Node.js. Runs commands via bash -c. 
import { createBashTool, NodeShellProvider } from "@openharness/core";

const { bash } = createBashTool(new NodeShellProvider());
Options:
OptionDefaultDescription
cwdprocess.cwd()Default working directory for commands
maxStdout50,000 charsTruncate stdout beyond this length
maxStderr10,000 charsTruncate stderr beyond this length
const shell = new NodeShellProvider({
  cwd: "/home/user/project",
  maxStdout: 100_000,
});
The exec method supports per-call timeout (default 30s), cwd, and env overrides.

​
VfsFsProvider

A virtual filesystem provider from the @openharness/provider-vfs package. Provides sandboxed, in-memory, or SQLite-backed file access — ideal for testing, isolated execution, or environments without a real filesystem. 
npm install @openharness/provider-vfs

import { createFsTools } from "@openharness/core";
import { VfsFsProvider } from "@openharness/provider-vfs";

const fsTools = createFsTools(new VfsFsProvider());
By default, VfsFsProvider uses an in-memory backend mounted at /workspace. It initializes lazily on first use. Options:
OptionDefaultDescription
vfs—Pre-created VirtualFileSystem instance (skips auto-creation)
providerMemoryProviderVFS storage backend
vfsOptions{ moduleHooks: false, virtualCwd: true }Options passed to vfs.create()
mountPoint"/workspace"Mount point for the virtual filesystem
maxFileSize10 MBMaximum file size readFile will load

​
Storage Backends

The VFS provider supports three backends via @platformatic/vfs (or the future node:vfs):
In-memory filesystem — fast, ephemeral, no persistence:
const fs = new VfsFsProvider(); // MemoryProvider is the default

​
Accessing the VFS Instance

For advanced use cases, you can access the underlying VirtualFileSystem: 
const provider = new VfsFsProvider();
const vfs = await provider.getVfs();

​
Custom Providers

Implement the FsProvider and/or ShellProvider interfaces to support any environment: 
import type { FsProvider, ShellProvider } from "@openharness/core";

class MyCloudFsProvider implements FsProvider {
  async readFile(path: string) { /* ... */ }
  async writeFile(path: string, content: string) { /* ... */ }
  // ... implement all methods
}
Possible targets:
  • E2B sandboxes for isolated code execution
  • Cloudflare Workers for edge deployment
  • Daytona for managed dev environments
  • Docker containers for reproducible builds
  • Custom APIs wrapping remote filesystems