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

This repository profile is provided by osrepos.com, an open source repository discovery platform.

Source: osrepos.com
Repository profile: https://osrepos.com/repo/sandbaseai-sandbase-harness
Generated for open source discovery and AI-assisted research.

SandBase Harness is a local-first, self-hosted runtime for AI agents, offering sandboxed sessions, memory, and credentials. This TypeScript-based project provides a robust infrastructure for managing and observing AI agents, ensuring auditability and secure execution on your own machine or infrastructure.

GitHub: https://github.com/sandbaseai/sandbase-harness
OSRepos URL: https://osrepos.com/repo/sandbaseai-sandbase-harness

## Summary

SandBase Harness is a local-first, self-hosted runtime for AI agents, offering sandboxed sessions, memory, and credentials. This TypeScript-based project provides a robust infrastructure for managing and observing AI agents, ensuring auditability and secure execution on your own machine or infrastructure.

## Topics

- AI Agents
- Agent Runtime
- Self-Hosted
- TypeScript
- Docker
- Kubernetes
- Local-First
- AI Infrastructure

## Repository Information

Last analyzed by OSRepos: Sun Sep 13 2026 20:24:02 GMT+0100 (Western European Summer Time)
Detail views: 2
GitHub clicks: 0

## Safety Notice

OSRepos shares public repositories for knowledge and discovery only. Review source code, dependencies, licenses, and security implications before running or installing anything.

## Content

## 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)**:

bash
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:

bash
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**:

bash
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:

bash
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:

bash
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:

bash
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**:

typescript
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 ?? '');
  }
}


## Links

*   **GitHub Repository**: [sandbaseai/sandbase-harness](https://github.com/sandbaseai/sandbase-harness)
*   **Official MCP Registry**: [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.sandbaseai%2Fsandbase-harness)
*   **DeepSeek Harness Handbook**: [sandbaseai/deepseek-harness-handbook](https://github.com/sandbaseai/deepseek-harness-handbook)
*   **SandBase CLI**: [sandbaseai/cli](https://github.com/sandbaseai/cli)
*   **SandBase Skills**: [sandbaseai/sandbase-skills](https://github.com/sandbaseai/sandbase-skills)
*   **SandBase (Hosted Services)**: [www.sandbase.ai](https://www.sandbase.ai)
*   **Installation Guide**: [llms-install.md](https://github.com/sandbaseai/sandbase-harness/blob/main/llms-install.md)
*   **API Reference**: [docs/api.md](https://github.com/sandbaseai/sandbase-harness/blob/main/docs/api.md)
*   **Architecture Overview**: [docs/spec/architecture.md](https://github.com/sandbaseai/sandbase-harness/blob/main/docs/spec/architecture.md)