SandBase Harness: Local-First AI Agent Runtime with Sandboxed Sessions

Introduction

SandBase Harness is a local-first, self-hosted runtime for AI agents, developed by sandbaseai. This TypeScript-based project provides a robust infrastructure for managing and observing AI agents, featuring sandboxed sessions, memory, credentials, audit/replay capabilities, and a built-in local Console. It is designed to run on your local machine or within your own infrastructure, offering complete control over your AI agent deployments.

Why Use It and Key Benefits

While Agent SDKs handle the core model loop, production-grade AI agents require more sophisticated capabilities. SandBase Harness addresses these needs by providing a comprehensive runtime layer, not just a visual workflow builder or another model SDK.

Key benefits include:

Secure Code Execution: Run generated code safely within local, Docker, Kubernetes, or self-hosted worker sandboxes.
Agent Observability: Inspect long-running agents with persistent sessions, resumable event streams, audit trails, and replay functionality.
Granular Tool Access Control: Manage tool access using Model Context Protocol (MCP) toolsets, credential vaults, permission policies, and approval mechanisms.
Broad Model Compatibility: Operate with various models, including OpenAI, Anthropic, MiniMax, and OpenAI-compatible providers like DeepSeek V4.
Data Sovereignty: Maintain control over your infrastructure with local-first SQLite and file storage, eliminating the need for a hosted control plane.
Comprehensive API and Console: Features a Claude Managed Agents-style /v1 API and a user-friendly local Console for management.
TypeScript SDK: A dedicated SDK for seamless integration and development.

Installation

To get started with SandBase Harness, ensure you have Node.js 22+ and npm 10+ installed. Docker is optional, required only for Docker-backed sandboxes.

Quick Start (Local):

git clone --branch v0.3.8 --depth 1 https://github.com/sandbaseai/sandbase-harness.git
cd sandbase-harness
npm ci
npm run build
mkdir ../my-agents && cd ../my-agents
node ../sandbase-harness/dist/index.js init
node ../sandbase-harness/dist/index.js start

Open http://127.0.0.1:3000/dashboard, navigate to Settings > Models, paste your API key, and you're ready to run agents.

Docker MCP Bridge:

The six-tool MCP bridge is available as a multi-architecture OCI image. Start the Harness API, then add this stdio command to an MCP client:

docker pull ghcr.io/sandbaseai/sandbase-harness-mcp:0.3.8
docker run --rm -i \
  -e MANAGED_AGENTS_URL=http://host.docker.internal:3000 \
  ghcr.io/sandbaseai/sandbase-harness-mcp:0.3.8

For an authenticated remote runtime, also pass MANAGED_AGENTS_API_KEY.

Examples

CLI Examples:

managed-agents init
managed-agents start [--host 127.0.0.1] [--port 3000]
managed-agents list
managed-agents reload
managed-agents chat <agent-id> --message "hello"
managed-agents template list | install <name> | create <name>

API Examples:

Create an agent:

curl -X POST http://127.0.0.1:3000/v1/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Incident commander",
    "model": "gpt-4o",
    "system": "You are an on-call incident commander.",
    "tools": [{ "type": "agent_toolset_20260401" }]
  }'

Create a Docker-isolated environment:

curl -X POST http://127.0.0.1:3000/v1/environments \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Docker sandbox",
    "config": {
      "sandbox_provider": "docker",
      "image": "node:22-slim",
      "resources": { "memory": "1g", "cpu": 1 }
    }
  }'

Start a session:

curl -X POST http://127.0.0.1:3000/v1/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "agent_...",
    "environment_id": "env_...",
    "title": "Triage SENTRY-123"
  }'

SDK Example:

import { ManagedAgentsClient } from 'managed-agents/sdk';

const client = new ManagedAgentsClient({
  baseUrl: 'http://127.0.0.1:3000',
});

const session = await client.sessions.create({
  agent: 'agent_...',
  environment_id: 'env_...',
});

for await (const event of client.sessions.chat(session.id, 'Hello')) {
  if (event.type === 'agent.message_chunk') {
    process.stdout.write(event.delta ?? '');
  }
}