Local Sandbox

The local sandbox provider routes agent sessions to worker processes running directly on a developer's machine or a self-hosted Linux host. Unlike cloud providers, the platform does not provision local workers - you run the donmai daemon and it registers itself with the platform.

How local workers work

When the platform dispatches a session to a local pool, LocalSandboxProvider.provision() returns immediately with a marker handle (externalId: 'user-managed'). The actual worker is the donmai daemon process already running on your machine. It polls for work, claims the session via the registration token in its environment, clones the repository, and runs the agent.

This means:

The platform never starts or stops local workers. You manage the daemon lifecycle.
Capacity is bounded by host RAM, CPU, and the number of concurrent workers the daemon is configured to run.
Sessions on local workers have no platform-imposed duration ceiling.

Capability profile

Capability	Value
`transportModel`	`either` (dial-in via Unix socket or dial-out via token)
`supportsFsSnapshot`	false
`supportsPauseResume`	false
`supportsCapacityQuery`	true (daemon reports capacity)
`maxConcurrent`	null (host-limited)
`maxSessionDurationSeconds`	null (unlimited)
`regions`	`['*']` (wherever the machine is)
`os`	linux, macOS
`arch`	x86_64, arm64
`idleCostModel`	zero (your own hardware)
`billingModel`	fixed (no per-session billing)
`supportsGpu`	false (operator may override at runtime)
`supportsCustomNetworkPolicy`	false
`egressDefault`	allow-all

Substrate defaults

The local provider has the widest substrate defaults of any provider because the donmai worker image bakes git, Go, and Node, and the host filesystem provides full-history clones and persistent storage:

Runtime kinds: native, npm, python-pip, http, mcp-server, a2a-protocol, host-binary, workarea
Requirement kinds: persistent-storage, long-running, workarea, host-binary, network-egress, git, full-history-clone, toolchain:go, toolchain:node

host-binary is exclusive to the local provider - it means the host machine's PATH-installed binaries are available to agents.

Auth-mode pin

Sessions using host-session or local auth modes are pinned to providerId='local' pools. If no active local pool exists for the project, dispatch fails with a clear error at the profile-validation step.

These auth modes require the worker to authenticate using credentials on the local machine (e.g. CLI session tokens, Ollama local endpoint). Cloud providers cannot satisfy this requirement by definition, and the platform enforces the pin before calling provision via validateResolvedProfile.

Setting up a local pool

Install the Rensei daemon

brew install RenseiAI/tap/rensei
rensei host install

This mints a project-scoped worker registration token, writes it to ~/.rensei/daemon.yaml, and registers the dev.rensei.daemon LaunchAgent (macOS) or systemd unit (Linux). The daemon starts automatically on login.

For a multi-project org, pin the install to a specific project:

rensei host install --project my-project-slug

OSS donmai users (not on the Rensei platform) use brew install donmai and donmai daemon install instead. The OSS install path is documented at donmai.dev/docs/getting-started/install.

Authenticate and select a project

rensei auth add --user   # browser login
rensei setup             # pick your org and project

The setup wizard saves your active org and project to ~/.config/rensei/config.json. If you already ran rensei auth add, rensei host install uses the saved context automatically.

Create a local capacity pool

In Settings → Execution → Capacity, click New pool, choose Local, and give it a name. No config keys are required for a basic local pool. Activate it.

Verify the daemon is connected

rensei host status

You should see the daemon in an idle or running state with the correct platform URL and org. The Projects: N allowed line shows how many projects this host is registered to serve.

Daemon lifecycle commands

# Install as a background service (registers dev.rensei.daemon)
rensei host install

# Start / stop / restart the service
rensei host start
rensei host stop
rensei host restart

# Show current status and connected sessions
rensei host status

# Drain: stop accepting new work and wait for running sessions to complete
rensei host drain

# Uninstall the service
rensei host uninstall

The platform daemon uses the label dev.rensei.daemon (macOS LaunchAgent, Linux systemd unit). This is distinct from the OSS dev.donmai.daemon label used by the standalone donmai binary. Both can coexist on the same machine without conflict. See Upgrading for version-specific migration notes.

Local pool config keys

The local provider ignores all config JSONB keys - worker configuration is managed via the daemon on the host, not via pool config. You can store metadata in config for human reference, but none of it is read at provision time.

Multiple local pools

You can create multiple local pools in the same org. This is useful when you have several machines (e.g. a Mac for interactive work and a Linux build box for CI). Each machine's daemon registers under its own pool. Use pool names to distinguish them (e.g. "macbook-mark", "linux-ci-01").

To route a specific project to a specific local pool, set the pool on the project's capacity page.

Capacity Pools - pool management and substrate resolution
Add a Provider - SandboxProvider interface
CLI: Daemon - full daemon command reference
Model Routing: Auth Modes - host-session and local auth modes explained

On this page