How to Self-Host SandBase Agent Runtime for VPS
Run SandBase Harness v0.3.8 for your own VPS with tagged install, agent YAML, MCP servers, sandbox modes, and Anthropic SDK baseURL setup.
Wetin you go get when you self-host SandBase agent runtime
Self-hosting SandBase agent runtime mean say you dey run SandBase Harness for server wey belong to you. Sessions, credentials, memory and audit trails go dey your disk instead of another person own. Na Node service be this. E dey listen for 127.0.0.1:3000, e dey serve /v1 HTTP API and web console, and e dey keep state for SQLite beside your agent files.
The /v1 API follow the shape of Claude Managed Agents (CMA), wey be the hosted managed-agent API. Na this make the runtime useful for both directions: you fit write code with Anthropic SDK and point its baseURL to your own server, then later move the same code go hosted deployment.
SandBase Harness no come with model. E dey call model. As of 12 October 2026, e support OpenAI, Anthropic, MiniMax, and OpenAI-compatible endpoints. This one cover self-hosted gateways and providers like DeepSeek V4. MiniMax become first-class provider for v0.3.3, with option to use global or mainland China endpoint. You still need provide API key, or local server wey dey speak OpenAI API.
Wetin you need before you start
- One VPS wey dey run Ubuntu 24.04 and get at least 2 GB RAM. The TypeScript build na the heaviest step for the installation.
- Node.js 22 or newer, and npm 10 or newer. The project set both as hard minimums.
git, plus API key for any model provider wey you plan to use.- Docker, but na only if you want per-session container sandboxes.
Ubuntu 24.04 get Node 18.19 for im own repository, but e below the minimum. So use NodeSource to install Node instead.
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs git
node -v
npm -vnode -v suppose print v22 or higher, and npm -v suppose print 10 or higher. If node -v still print v18.19.1, the distribution package still dey installed and e dey win for PATH. Remove am before you continue, because the build go use whichever node the shell find.
Install SandBase from the v0.3.8 tag
Install from tag, no be from branch wey dey change. Bare clone of main go give you anything wey land one hour ago, and config keys below fit no match am. v0.3.8, wey dem publish on 30 August 2026, na the current tag as of 12 October 2026, and na this tag the project own installation doc pin.
sudo install -d -o "$USER" -g "$USER" /opt/sandbase
cd /opt/sandbase
git clone --branch v0.3.8 --depth 1 https://github.com/sandbaseai/sandbase-harness.git
cd sandbase-harness
npm ci
npm run buildUse npm ci, no be npm install. ci installs the exact versions wey dey inside the committed lockfile, so your tree go match the tree wey maintainers test. npm install fit resolve newer versions, and na so pinned tag fit quietly stop to dey pinned.
Now create workspace. Workspace na separate directory wey hold your agent files and all runtime state. If you keep am outside source checkout, you fit pull newer tag without touching your data.
mkdir -p /opt/sandbase/workspace
cd /opt/sandbase/workspace
node /opt/sandbase/sandbase-harness/dist/index.js init
node /opt/sandbase/sandbase-harness/dist/index.js startinit writes one .managed-agents/ directory inside workspace. start starts the console for http://127.0.0.1:3000/dashboard and the API for http://127.0.0.1:3000/v1. Your laptop no fit reach either one yet, and that one correct; we go cover am further down. For now, reach the console through SSH:
ssh -N -L 3000:127.0.0.1:3000 you@your-serverThat long node .../dist/index.js path fit tire person, so give am name.
alias sandbase='node /opt/sandbase/sandbase-harness/dist/index.js'The commands below dey written as sandbase <command> based on that.
No install am from npm
The project talk am for its own installation doc: the unscoped managed-agents package wey dey visible for npm no be this project. So npx managed-agents and npm install -g managed-agents go fetch something wey no relate to the runtime wey you want. Install from the tagged GitHub source until the maintainers announce official scoped package. This no be small footnote for the project history: v0.3.1 dey mainly to replace the old npm quick start with the pinned tagged-source path.
Workspace make use model provider
init dey write .managed-agents/config.yaml. You configure one provider for the whole workspace, then individual agents choose the exact model IDs.
model:
provider: openai
api_key: ${OPENAI_API_KEY}
storage:
metadata:
provider: sqlite
options: {}
artifacts:
provider: local
options:
base_path: files${OPENAI_API_KEY} form dey take value from process environment. So the key no go dey inside config file or any backup of that file. Put am inside environment file wey only root fit read, because systemd dey read EnvironmentFile= as root before e drop privileges.
sudo install -d -m 750 /etc/sandbase
sudo touch /etc/sandbase/runtime.env
sudo chmod 600 /etc/sandbase/runtime.envOpen that file with editor and add one line, OPENAI_API_KEY=sk-.... Provider keys belong for here. Secrets wey an agent use during session belong for runtime credential vaults instead. Na different matter be that, with different blast radius. Read how to keep secrets away from AI agents before you paste production token into either place.
YAML wey agent dey use: mcp_servers, tools and permission policies
Agents dey defined as YAML files inside workspace agents/ directory. Na this part of the runtime you go spend time on. The keys go clear more once you don write small agent loop by hand, because each one na control for something wey you for otherwise code yourself: system prompt, tool list, and check wey dey run before tool start.
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
metadata:
template: incident-commanderLoad am and check say e enter correctly:
sandbase reload
sandbase list
sandbase chat agent_assistant --message "hello"reload dey import the seed YAML into SQLite. list suppose now print the agent with an ID. If list no show am, the file no parse, and .managed-agents/logs/runtime.log na where dem write the reason.
mcp_servers dey declare MCP (model context protocol) endpoints. type: url mean say the runtime dey use HTTP talk to server wey dey run for another place, so anything wey you already operate fit work here, including MCP servers wey dey hosted for the same VPS as the runtime. Web search na usually the first tool people dey use, and handing agent your own SearXNG instance worth reading before you connect one, because tool wey dey return pages written by strangers dey put untrusted text directly inside model context. The easier first setup na the opposite shape: read-only endpoint over data wey you already own. Na wetin openGym exposes beside the workout tracker itself do next, so agent fit answer questions about your training history without being able to rewrite anything.
Declaring server no mean say agent don get access to its tools. The tools list dey give that access, through mcp_toolset entry wey mcp_server_name match the name above. If agent dey behave as if MCP tools no exist, compare those two strings character by character before you check anywhere else.
agent_toolset_20260401 na the built-in tool set. The dated suffix na schema version, so agent wey pin to am go keep the tool definitions wey dem write am against. default_config dey set policy for every tool inside the set, and each entry under configs dey override one tool by name, bash for the example.
permission_policy na where runtime show say e better pass bare model call. always_ask dey pause the session and wait for human approval before the call run. always_allow dey allow am pass. Setting bash to always_ask mean say agent no fit run shell command without you first seeing the exact command, na the same control wey you go use when you dey run Claude Code safely for VPS. If you also dey run DeepSeek Harness, the same controls dey come there as add-ons instead of YAML keys, and the plugins wey limit budgets and control tool calls na the closest equivalent to this block.
Sandbox mode four, and when each one fit
Tool calls wey dey execute code dey run inside sandbox. Backend dey choose per environment through sandbox_provider inside the environment config object, or you fit set am as workspace default for console under Settings, inside Sandbox editor under Advanced. You dey create environments through API for POST /v1/environments.
local dey run code as child process of runtime, for host, with runtime own user. Na the default whenever environment no name any backend, and e reasonable while na only you dey use am and agent only dey read files wey belong to you. If environment name backend wey runtime no fit load, runtime go reject am instead of quietly running am here. This one no be isolation. Tool call wey delete files go delete your files, and tool call wey read /etc/sandbase/runtime.env go read your provider key.
docker dey start one container for every session.
{
"sandbox_provider": "docker",
"image": "node:22-slim",
"resources": { "memory": "1g", "cpu": 1 }
}Session get its own filesystem, and runtime go remove the container together with session. Memory and CPU caps no dey part of this mode: runtime only adds --memory and --cpus to the container when environment resources block set dem, as the example show. So environment wey no get that block go get container wey no get its own limit. Leave out image and runtime go use ghcr.io/sandbaseai/sandbase-harness-sandbox:latest. Switch to this mode immediately when agent dey run code wey you no write. The cost be say runtime user need access to Docker socket, and membership of docker group mean almost the same thing as root for host. Per-session containers get the same setup as self-hosted agent sandboxes wey get one container for every run, so the explanation of wetin escaped process fit reach still apply here without change.
kubernetes dey run session workload as pod and control am with kubectl exec and kubectl cp. Runtime image need to get kubectl, and its ServiceAccount need RBAC (role-based access control) permission to create, delete, get, list, and watch pods for target namespace, plus exec subresource. This mode worth the setup only if you already dey run cluster.
self-hosted worker dey named remote for Settings and self_hosted for an Environment, and e no dey run tool code for this box at all. Runtime go put the work for queue, then external worker, with worker API URL and key from Settings, go claim and complete the queued items outside this host. E fit work when the code suppose run for machine wey no hold your provider key. Only docker and kubernetes dey enforce resource limits, so na worker host responsibility to cap worker.
Why runtime dey bound to 127.0.0.1?
Because e dey start with authentication off. Runtime dey enable bearer-token authentication when at least one API key dey exist, and fresh init no dey create any. If you bind am to 0.0.0.0 with that default, unauthenticated agent runtime wey dey hold shell tools and your provider key go dey public internet.
So when you want make people reach am, leave the bind address as e dey and do two other things.
First, turn authentication on. Set MANAGED_AGENTS_API_KEY for the service environment file, or create key with POST /v1/api-keys. E go return one secret_key field, and e no go show am again. Clients go then send Authorization: Bearer <key> for every API request, or send the same key as x-api-key, but never use both at the same time. The key dey protect the API, not the console: dashboard pages and their static assets fit load without key, and /v1/x/health and /v1/x/metrics too. One key na one shared identity. So if wetin you really want na separate sandboxed agent for each teammate, with provider keys kept inside one gateway, OneCLI na for this kind setup.
Second, put reverse proxy for front and terminate TLS (transport layer security) there. Runtime dey serve plain HTTP by design, and e expect another service to handle certificates.
server {
listen 443 ssl;
server_name agents.example.com;
ssl_certificate /etc/letsencrypt/live/agents.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/agents.example.com/privkey.pem;
location / {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Connection "";
proxy_buffering off;
proxy_read_timeout 3600s;
}
}Two of those lines no be decoration. proxy_buffering off matter because sessions dey stream through server-sent events (SSE). When buffering dey on, nginx go hold the response until its buffer fill up. The console no go show anything while agent dey work, then e go dump everything at the end. proxy_read_timeout 3600s matter because the default na 60 seconds. So if stream quiet for more than one minute, proxy go close am in the middle of one turn, and the failure go look like runtime crash.
For the firewall, open 22 and 443. Leave 3000 closed because proxy dey reach am through loopback, and nothing outside the machine suppose reach am. Because /v1/x/metrics dey answer without key, add location = /v1/x/metrics { return 404; } to the server block if you no want publish runtime metrics.
Point Anthropic SDK go your own box
The runtime dey implement a CMA-shaped /v1 surface, so Anthropic SDK client fit talk to am after you change one field.
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'
});E also accept the beta headers wey Claude Managed Agents clients dey send, anthropic-beta: managed-agents-2026-04-01 and anthropic-beta: agent-memory-2026-07-22. Plain request wey no get compatibility header dey accepted as local caller. Request wey carry x-api-key, anthropic-version or anthropic-beta dey follow hosted rules: version 2023-06-01 and managed-agents beta dey required, except say /v1/memory_stores routes need agent-memory beta and reject the two together. The headers dey make code wey dem write for hosted deployment run here without change.
Compatibility dey close, but e no complete. Read docs/api-matrix.md for the checkout before you assume say surface dey available, because the project document the gaps wey e get there, including client-side custom tools. Those ones still need named registration above the current event-result protocol.
Plain HTTP work the same way, and na the fastest way to confirm say runtime dey alive:
curl -N -X POST http://127.0.0.1:3000/v1/sessions/SESSION_ID/messages \
-H "Content-Type: application/json" \
-d '{"content": "Hello", "stream": true}'Healthy response na stream of events wey dey continue to arrive. If connection drop, resume from the last event wey you see instead of replaying the whole turn:
curl -N http://127.0.0.1:3000/v1/sessions/SESSION_ID/events/stream \
-H "Last-Event-ID: EVENT_ID"That resumable stream na why session fit survive when laptop close. The events dey persisted for server, so client dey replay a log instead of holding the only copy.
Credentials, memory and audit trails dey for disk
Everything wey the runtime own dey under .managed-agents/ for the workspace.
.managed-agents/
├── config.yaml
├── data.db
├── logs/runtime.log
├── files/
├── skills/
├── snapshots/
└── sandbox/data.dbna the SQLite metadata: agents, sessions, credential vault entries, memory store entries and API keys.files/dey hold uploaded file bytes, whileskills/dey hold uploaded skill packages.snapshots/dey hold session workspace snapshots, whilesandbox/dey hold working directories for local-mode sessions.logs/runtime.logna the first place to check whenever something silently no do anything.
Credential vaults na groups of secrets. You add each one with an auth_type like environment_variable, then attach am to a session through vault_ids when you create the session. Memory stores dey hold named entries wey you mount inside a session as a memory_store with its own access setting and instructions. Both dey inside data.db. Na exactly this one be the difference between this and a raw model call: the runtime dey remember across sessions, and e dey record wetin happen.
Because na one directory, back am up as one unit.
sudo systemctl stop sandbase
sudo tar czf /root/sandbase-$(date +%F).tgz -C /opt/sandbase/workspace .managed-agents
sudo systemctl start sandbaseStop the service first. If you copy a SQLite database while the runtime dey write to am, the copy fit capture a file wey no go open when you restore am. You fit only discover this on the day wey you need the backup. If you prefer keep agent YAML for git and state for another place, the deployment doc support pinning the state location with --data-dir for start.
To restore am, do the reverse: check out the same tag for a fresh box, unpack the archive inside the workspace, then start the service. Your provider key no dey inside the archive if you use the ${OPENAI_API_KEY} form, so keep the key for another place wey you go still get access to.
Run am under systemd
Give the runtime e own user so one tool call for local sandbox mode no fit act like you.
sudo adduser --system --group --no-create-home --home /opt/sandbase sandbase
sudo chown -R sandbase:sandbase /opt/sandbaseSave dis as /etc/systemd/system/sandbase.service.
[Unit]
Description=SandBase Harness runtime
After=network-online.target
[Service]
User=sandbase
Group=sandbase
WorkingDirectory=/opt/sandbase/workspace
EnvironmentFile=/etc/sandbase/runtime.env
ExecStart=/usr/bin/node /opt/sandbase/sandbase-harness/dist/index.js start --host 127.0.0.1 --port 3000
Restart=on-failure
RestartSec=5
[Install]
WantedBy=multi-user.targetThe project own deployment example dey call a managed-agents binary for PATH. Tagged-source install no create one, so ExecStart dey run node against the built entry point instead.
sudo systemctl daemon-reload
sudo systemctl enable --now sandbase
sudo systemctl status sandbase
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3000/dashboardHealthy result na active (running) from status and 200 from curl. If anything else happen, read journalctl -u sandbase -n 50 first and .managed-agents/logs/runtime.log second. enable --now na the part wey matter, because process wey you start by hand go disappear after the next reboot.
Wetin fit spoil, and the message wey you go see
npm run build dey die without npm showing error. For 1 GB VPS, kernel out-of-memory killer dey stop the TypeScript compile. E dey report am for kernel log instead of npm. Confirm am with journalctl -k | grep -i "out of memory", wey go print one line wey name the process node wey dem kill. Add swap, or build am for a bigger instance and copy dist/ go there.
Error: listen EADDRINUSE: address already in use 127.0.0.1:3000. Another process don already hold the port. sudo ss -lntp | grep 3000 go name am. Stop that process, or start the runtime with --port 3001 and update the proxy.
Dashboard no go load from your laptop. Na the expected behaviour be that, because the runtime dey bind to loopback. Use the SSH tunnel wey dey above, or complete the reverse proxy. No use --host 0.0.0.0 take repair am, because authentication dey off until key dey available.
Docker sandboxes dey fail with permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock. User sandbase no dey inside group docker. Fix am with sudo usermod -aG docker sandbase and restart the service. Understand wetin you grant: that group get root power for the host, so e cancel part of the reason wey make you give the runtime im own user.
Kubernetes sandboxes dey fail with Error from server (Forbidden). ServiceAccount no get pod permissions or exec subresource dey missing. Check am directly with kubectl auth can-i create pods/exec -n <namespace>, wey go answer yes or no.
API requests dey return 401 after you add API key. Authentication go switch on when the first key dey available. E cover the API but e no cover the console: dashboard pages and their static assets remain public, so console go continue load, then e need the key for im API calls. Send Authorization: Bearer <key> or x-api-key: <key>, no send both, because request wey carry both headers go reject with 401 even when authentication dey off. If you lose the key, create another one, because secret_key dey return only once and dem store am as hash only.
Tools from one MCP server never dey show for session. Check the mcp_server_name inside the tools block against the name inside mcp_servers. Then check say runtime fit reach the URL from the server itself with curl -i <url>. URL-type MCP server na network dependency, and VPS dey resolve names and route traffic differently from your laptop.
FAQ
I fit run SandBase Harness without OpenAI or Anthropic key?
Yes, if you get MiniMax key or OpenAI-compatible endpoint. The runtime support OpenAI, Anthropic, MiniMax and OpenAI-compatible providers, so local server wey speak OpenAI API go work. Set workspace provider for .managed-agents/config.yaml and point api_key plus the endpoint go am. The runtime no include any model by itself, so something must answer the calls.
E safe to expose the runtime for public port?
No, not as e dey installed. E bind to 127.0.0.1:3000 and start with authentication off, and the fix no be to use another bind address. Create API key, or set MANAGED_AGENTS_API_KEY, so bearer-token authentication go turn on for the API. Then put nginx or Caddy in front for TLS, and keep port 3000 closed for the firewall so na only through the proxy person fit enter.
Wetin be the difference between local, Docker and Kubernetes sandboxes?
local dey run tool code as child process of the runtime for the host, with permissions of the runtime user and no isolation. docker dey give every session its own container and filesystem, then remove am when the session end. E only limit memory and CPU if the environment resources block set dem. kubernetes dey run the session as pod and control am with kubectl exec. This one need kubectl inside the runtime image, plus RBAC for pods and the exec subresource for the target namespace. Another backend, the self-hosted worker, dey queue the work for external worker, so the code dey run away from the host.
Exactly wetin I need back up?
The .managed-agents/ directory inside the workspace. E hold config.yaml, the data.db SQLite database wey get agents, sessions, credential vault entries and memory entries, plus uploaded files, skill packages and session snapshots. Stop the service before you copy am, so SQLite no go write while archive dey happen. Provider API keys wey ${OPENAI_API_KEY} reference no dey inside the backup, so store dem separately.
Why clone v0.3.8 tag instead of main?
Tag na fixed tree, so the config keys and CLI commands wey you read about na the ones wey you go actually get. main dey change, and dem fit rename config key between when person write guide and when you run am. The project still warn say the unscoped managed-agents package for npm no be this project, so npx managed-agents go install something wey no relate. Release v0.3.1 mainly dey replace that npm quick start with the pinned tagged-source path.