A Local-First Runtime for AI Agents That Keeps Everything on Your Machine

You've probably wired up an agent to a model provider at some point, and then hit the awkward part: where do sessions live, where do the tools actually run, and who's holding your API keys? SandBase Harness is a local-first runtime for AI agents that answers those questions by keeping sessions, sandboxed tools, memory, credentials, audit trails, and a built-in Console on your own machine or infrastructure.

What It Does

SandBase Harness is a runtime for AI agents, distributed as a Node.js project you clone and run yourself. The architecture covers a lot of ground in one package: sessions, sandboxed tools, memory, credentials, audit trails, and a built-in Console. Rather than stitching those pieces together from separate services, you get them in a single runtime that serves both an API and a web dashboard.

Setup starts with an init command, which writes a workspace into whatever directory you run it from — an agent, a skills folder, and a config.yaml whose provider reference points at an environment variable like ${OPENAI_API_KEY}. The start command then serves the API and the Console on http://127.0.0.1:3000. The project supports OpenAI, Anthropic, MiniMax, or any OpenAI-compatible endpoint, and Docker is optional — you only need it if you want Docker-backed sandboxes.

There's also a CLI path for people who'd rather stay in the terminal. The chat command sends a single message and exits once the turn settles, or keeps the session open and streams if you omit --message.

Why It's Cool

Local-first isn't just a tagline here. The README is explicit that everything runs on your machine or in your own infrastructure. For anyone who's uncomfortable shipping credentials and conversation history through a third-party control plane, that's the whole point. Your audit trails stay yours.

The sandbox story is grounded in practicality. Docker is optional rather than mandatory. That's a small detail with real consequences — you can get an agent running without installing a container runtime, and only reach for Docker when you actually want Docker-backed sandboxes.

The Console handles the fiddly parts of setup. Two things reliably trip people up when configuring an agent runtime: getting the provider credentials active, and getting the model ID right. The README walks through both. After you paste your API key and save, the page tells you the saved configuration isn't active yet — because settings only take effect at startup. You restart, and you're live. If your provider isn't in the list, you pick the OpenAI-compatible vendor and set a base URL.

The model ID gotcha is documented, not hidden. An agent carries its own model ID, so the gpt-4o that init writes won't work for every provider. Use deepseek-chat for DeepSeek, for example. Get it wrong and the turn fails with model_not_found. It's the kind of failure that wastes an afternoon if nobody warns you, and here somebody does.

Tool approval is a first-class concept. By default, the init template parks tool calls for approval and waits for a person to answer. If you want to skip that for a given run, --tool-approval allow preauthorizes the calls the agent may make. Having that as an explicit flag — rather than an implicit default — is a sensible design choice.

It's listed in the Official MCP Registry. That's a useful signal if you're already building around the Model Context Protocol and want something that fits into that ecosystem.

How to Try It

You'll need Node.js 22+, npm 10+, and a model provider API key. Docker is optional.

1. Clone the repository at the release tag and build it:

git clone --branch v0.3.8 --depth 1 https://github.com/sandbaseai/sandbase-harness.git
cd sandbase-harness
npm ci
npm run build

1. Create a workspace and start the runtime:

mkdir ../my-agents && cd ../my-agents
node ../sandbase-harness/dist/index.js init
node ../sandbase-harness/dist/index.js start

1. Open http://127.0.0.1:3000/dashboard and go to Settings > Setup. Paste your API key into the provider form and save, then restart the runtime — stop with Ctrl+C and run start again, or use the restart button. If your provider isn't listed, choose the OpenAI-compatible vendor and set its base URL.

2. In the Agent models panel, set the model ID your provider actually serves.

3. Send a message. From the Console, open Sessions, create a session for the agent, and type into the composer. Or from a terminal:

node ../sandbase-harness/dist/index.js chat agent_assistant --message "hello" --tool-approval allow

The repository is at github.com/sandbaseai/sandbase-harness. There's also an independent DeepSeek Harness Handbook with runtime guides and troubleshooting if you're building on DeepSeek specifically.

Final Thoughts

SandBase Harness is aimed at developers who want agent infrastructure they actually control — sessions, sandboxes, credentials, and audit logs without handing them to someone else's cloud. The setup has a couple of deliberate steps (restarting after saving provider config, matching the model ID to your provider) that the README documents clearly, which suggests the maintainers know where people get stuck. If you're running agents locally or in your own infrastructure and you're tired of assembling the surrounding pieces yourself, this is worth a look.