SandBase Harness

SandBase Harness

English | 中文

A local-first runtime for AI agents. Sessions, sandboxed tools, memory,credentials, audit trails, and a built-in Console — all running on yourmachine or in your own infrastructure.

Building with DeepSeek Harness? The independent DeepSeek Harness Handbook provides source-backed runtime guides, multilingual troubleshooting, and a regularly updated Agent-first resource map.

Looking for a lightweight bridge instead of a full runtime? SandBase CLIconnects 25 AI client targets to 2,000+ models and APIs through a local stdio MCP bridge.If it fits your workflow, star SandBase CLIso other agent users can discover it.

Need hosted model and media APIs instead? SandBase provides one interface forLLM, image, and video generation APIs,with the API quickstart covering keys and first calls.

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

Choose SandBase Harness when you need more than a model loop:

If this runtime solves a real agent-infrastructure problem for you,star the repository so other builders can find it.

Find SandBase Harness

The project is also discoverable through these independent ecosystem directories:

• Official MCP Registry
• PluginBench
• DSH Hub
• DSH Packs
• dshbase
• FindHarness
• dsh-market

These listings are independent directories; the repository and its release metadataremain the source of truth.

Try it in Codespaces

The included development container installs dependencies and builds the runtime.When the terminal is ready, start the server on the forwarded port:

node dist/index.js start --host 0.0.0.0

Open the forwarded SandBase Harness Console port, then configure a model inSettings > Models. Codespaces usage may be billed by GitHub; the localquick start below remains free and keeps all runtime data on your machine.

Why

Agent SDKs handle the model loop. Production agents need more: persistentsessions, tool governance, sandbox boundaries, credential handling, memory,auditability, and a UI for humans to inspect what happened. managed-agentsis that runtime layer — not a visual workflow builder and not another model SDK.

Features

• Claude Managed Agents-style /v1 API and local Console
• SQLite-backed agents, sessions, environments, credential vaults, memorystores, files, skills, and API keys — SQLite metadata by default
• local file/skill bytes stored in the workspace state directory
• Resumable Server-Sent Events for session replay and debugging
• One active model provider boundary configured through Settings V2
• Sandbox backends: local process, Docker (per-session containers), Kubernetes(kubectl exec/cp), self-hosted worker queue
• Settings V2: one workspace model vendor, loop engine, storage, memory,sandbox — with validation, form/JSON modes, and restart flow
• MCP toolsets, permission policies, built-in tools, and skill packages
• DeepSeek Harness bridge over MCP stdio for agents, sessions, streamed turns,artifacts, and cancellation
• TypeScript SDK at managed-agents/sdk
• Release gate: npm run release:check

Screenshots

Console overview	Settings	API reference

Start with a use case

See the Showcase for three practical paths: an auditablecoding agent, DeepSeek Harness as an interactive front end, and controlled codeexecution across Local, Docker, Kubernetes, and self-hosted sandboxes.

Requirements

• Node.js 22+
• npm 10+
• A model provider API key (OpenAI, Anthropic, MiniMax, or an OpenAI-compatible endpoint)
• Docker (optional, for Docker-backed sandboxes)

DeepSeek Harness

Run this project as a DSH plugin instead of treating dsh-plugin as discoverymetadata only. Install the bundle into a DSH profile, start managed-agents,then boot that profile:

export MANAGED_AGENTS_URL=http://127.0.0.1:3000
# Preferred: install a local source checkout after `npm run build`.
dsh plugin --profile web add -w ../sandbase-harness
# Git URL fallback. Keep HTTPS; do not convert the spec to SSH.
# dsh plugin --profile web add git+https://github.com/sandbaseai/sandbase-harness.git
dsh web

The profile installs the verified source checkout directly; it does not resolvethe unrelated unscoped npm package. A git-hosted install runs prepare onlywhen dist/ is missing. Keep the HTTPS git spec; converting it to SSH fails onWindows hosts without GitHub SSH access. The patch starts the bundled MCP entry overstdio. DSH can then list agents,create and run sessions, inspect results and artifacts, and stop work throughnative mcp__sandbase__* tools. Seeexamples/deepseek-harness for the fulltool list and authenticated-runtime configuration.

For a walkthrough that starts with DSH and adds this runtime as a realthird-party plugin, read theDeepSeek Harness developer guide.

Pair the plugin with SandBase Skills to give the same DSH project a portable,source-verifiable research workflow:

npx --yes github:sandbaseai/sandbase-skills add multi-source-search
dsh web

This installs the complete Skill into .dsh/skills/multi-source-search, DSH'sproject-scoped discovery directory. It runs from GitHub source and needs noSandBase account when DSH already provides web/search tools.

For a complete, reproducible workflow that combines the evidence ledger withsandboxed execution, credentials, audit, and replay, readBuild an Auditable Research Agent.

New to DSH profiles, plugin composition, tool policy, or session semantics? Theindependent DeepSeek Harness Handbookprovides source-backed quickstarts, architecture maps, and troubleshooting forthe runtime layers used by this integration. Start with the local-browserInstall Doctorfor installation evidence, or use theFailure Routerto identify the first broken runtime boundary.

Quick Start

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, go to Settings > Models, paste yourAPI key, and you're running.

The unscoped managed-agents name on npm is not this project. Until anofficial scoped package is announced in this repository, install only from thetagged GitHub source release shown above. Do not run npx managed-agents ornpm install managed-agents.

The six-tool MCP bridge is published as a multi-architecture OCI image. Startthe 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. Thecontainer image contains only the MCP bridge; agent sessions and sandbox workremain in the connected Harness runtime. Every release image is built from thematching Git tag for linux/amd64 and linux/arm64, includes OCI source andMCP ownership metadata, and receives a GitHub build-provenance attestation.

Portable Agent Plugin

Copilot CLI, VS Code, and other Agent Plugins 1.0 clients can install the sameOCI-backed MCP bridge directly from this repository. Start the Harness API andDocker first, then expose its URL to the plugin process:

export MANAGED_AGENTS_URL=http://host.docker.internal:3000
# Optional when the runtime requires authentication:
export MANAGED_AGENTS_API_KEY=your-runtime-key

copilot plugin install sandbaseai/sandbase-harness:agent-plugin

The plugin passes these environment variables through to the pinnedghcr.io/sandbaseai/sandbase-harness-mcp:0.3.8 image. It does not store a keyin plugin.json, mcp.json, or the installed plugin files. On Linux, theplugin's Docker command maps host.docker.internal through host-gateway.

For development from the latest main branch:

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

Workspace Layout

my-agents/
├── agents/                  # Seed agent definitions (YAML)
│   └── assistant.yaml
├── skills/                  # Seed skill packages
│   └── example-skill/
│       └── SKILL.md
└── .managed-agents/         # Runtime state (gitignored)
    ├── config.yaml          # Workspace configuration
    ├── data.db              # SQLite metadata
    ├── logs/runtime.log
    ├── files/               # Uploaded file bytes
    ├── skills/              # Uploaded skill packages
    ├── snapshots/           # Session workspace snapshots
    └── sandbox/             # Local session sandboxes

Configuration

.managed-agents/config.yaml:

model:
  provider: openai
  api_key: ${OPENAI_API_KEY}

storage:
  metadata: { provider: sqlite, options: {} }
  artifacts: { provider: local, options: { base_path: files } }

Agents pick concrete model IDs (gpt-4o, claude-sonnet-4-20250514,openai/gpt-5.5). The workspace config only says how to reach the modelservice.

For DeepSeek V4 Pro/Flash configuration, including maximum reasoning effort,see DeepSeek V4.

For first-class MiniMax configuration, regional endpoints, and the supportedMiniMax-M3 and MiniMax-M2.7 model IDs, see MiniMax.

CLI

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 an environment (local sandbox):

curl -X POST http://127.0.0.1:3000/v1/environments \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Default local",
    "config": { "hosting_type": "local", "sandbox_provider": "local" }
  }'

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"
  }'

Send a message:

curl -X POST http://127.0.0.1:3000/v1/sessions/SESSION_ID/messages \
  -H "Content-Type: application/json" \
  -d '{ "content": "Investigate the alert." }'

Resume the event stream:

curl -N http://127.0.0.1:3000/v1/sessions/SESSION_ID/events/stream \
  -H "Last-Event-ID: 42"

SDK

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

The /v1 API follows Claude Managed Agents resource shapes, so you can alsopoint the Anthropic SDK at the local runtime:

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: process.env.MANAGED_AGENTS_API_KEY ?? 'local-dev-key',
  baseURL: 'http://127.0.0.1:3000',
});

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

Authentication

Open by default. Authentication activates when at least one API key exists:

# Static key via environment
export MANAGED_AGENTS_API_KEY=sk-local-example

# Or create a managed key
curl -X POST http://127.0.0.1:3000/v1/api-keys \
  -H "Content-Type: application/json" \
  -d '{ "name": "Local Console" }'

Clients send Authorization: Bearer <key>.

Agent Definition

Agents are YAML files in agents/:

name: Incident commander
description: Triages alerts and coordinates response.
model: gpt-4o
system: |-
  You are an on-call incident commander.
mcp_servers:
  - name: sentry
    type: url
    url: https://mcp.sentry.dev/mcp
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy: { type: always_ask }
    configs:
      - name: bash
        permission_policy: { type: always_ask }
  - type: mcp_toolset
    mcp_server_name: sentry
skills:
  - type: custom
    skill_id: skill_...
metadata:
  template: incident-commander

Development

npm ci
npm run typecheck    # src + tests
npm test             # vitest
npm run build        # runtime + console + SDK
npm run release:check  # full local release gate

release:check runs typecheck, tests, both builds, npm pack --dry-run, CLIinit smoke, and examples/basic startup smoke.

SandBase Ecosystem

• SandBase Skills — 88 installableAgent Skills for research, social intelligence, marketing, and businessworkflows across Codex, Claude Code, Cursor, Gemini CLI, and other clients.
• SandBase CLI — connect Cursor, Claude Code,Codex, Windsurf, Gemini CLI, OpenCode, and other MCP clients to 2,000+ AImodels and APIs with one onboarding command.
• DSH Plugin Store — discover,filter, install, and manage community DeepSeek Harness plugins from the nativeSettings experience.
• SandBase — hosted agent infrastructure, model access,tools, and managed sandboxes.

Documentation

• Machine-readable project metadata
• Agent / MCP installation guide
• Installation
• Usage Guide
• API Reference
• Skills
• Deployment
• Architecture
• Contributing
• Changelog

Community Guides

• Self-host the SandBase agent runtimeby SSD Nodes — an independent VPS walkthrough covering installation, agentconfiguration, MCP servers, sandbox modes, and reverse-proxy deployment. Thearticle demonstrates v0.3.2; use the current release command above for v0.3.8.

License

Apache-2.0