Providers

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:

Option	Default	Description
`cwd`	`process.cwd()`	Working directory for resolving relative paths
`maxFileSize`	`10 MB`	Maximum 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:

Option	Default	Description
`cwd`	`process.cwd()`	Default working directory for commands
`maxStdout`	`50,000` chars	Truncate stdout beyond this length
`maxStderr`	`10,000` chars	Truncate 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:

Option	Default	Description
`vfs`	—	Pre-created `VirtualFileSystem` instance (skips auto-creation)
`provider`	`MemoryProvider`	VFS storage backend
`vfsOptions`	`{ moduleHooks: false, virtualCwd: true }`	Options passed to `vfs.create()`
`mountPoint`	`"/workspace"`	Mount point for the virtual filesystem
`maxFileSize`	`10 MB`	Maximum file size `readFile` will load

Storage Backends

The VFS provider supports three backends via @platformatic/vfs (or the future node:vfs):

Memory (default)
SQLite
Real FS

In-memory filesystem — fast, ephemeral, no persistence:

const fs = new VfsFsProvider(); // MemoryProvider is the default

SQLite-backed filesystem — persistent, supports larger datasets:

import { getVfsModule } from "@openharness/provider-vfs";

const vfsModule = await getVfsModule();
const fs = new VfsFsProvider({
  provider: new vfsModule.SqliteProvider("./agent-fs.db"),
});

Real filesystem scoped to a root directory — sandboxed access to a real path:

import { getVfsModule } from "@openharness/provider-vfs";

const vfsModule = await getVfsModule();
const fs = new VfsFsProvider({
  provider: new vfsModule.RealFSProvider("/path/to/sandbox"),
});

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

Getting Started

Core Concepts

Tools

Advanced

UI Integration

Resources

Interfaces

FsProvider

ShellProvider

Environment

Built-in Providers

NodeFsProvider

NodeShellProvider

VfsFsProvider

Storage Backends

Accessing the VFS Instance

Custom Providers

​Interfaces

​FsProvider

​ShellProvider

​Environment

​Built-in Providers

​NodeFsProvider

​NodeShellProvider

​VfsFsProvider

​Storage Backends

​Accessing the VFS Instance

​Custom Providers

Interfaces

FsProvider

ShellProvider

Environment

Built-in Providers

NodeFsProvider

NodeShellProvider

VfsFsProvider

Storage Backends

Accessing the VFS Instance

Custom Providers