Agent setup

Runbay is an MCP server. There's no sidecar to install and no config file to write by hand — the app itself speaks the Model Context Protocol, and every running container automatically becomes a set of tools your coding agent can call.

This guide covers one-click registration, exactly what your agent sees, and a 60-second sandbox demo.

Register the MCP server (one click)

1. Open Settings ▸ MCP Server and enable the server.
2. Pick your client: Claude Code, Claude Desktop, or Cursor.
3. Click Register.

That writes a single runbay entry into the client's config and touches nothing else:

The edit is a byte-level JSON splice that preserves every unrelated key. A malformed config is refused, never clobbered — if the file won't parse, the app tells you instead of overwriting it.

The server listens locally only: a Unix socket at /tmp/runbay-mcp.sock, or localhost TCP on port 8765. There is no TLS yet, so keep it to your machine. All three MCP servers are rate-limited (100 requests/minute, 1000/hour per client) and validate every input at the boundary.

What your agent sees, automatically

Tools, per running container

For every running container:

• logs__<name> — tail recent logs
• stats__<name> — a live CPU / RAM / network snapshot
• exec__<name> — run a command from a read-only allow-list (injection vectors rejected)

For database containers (postgres, mysql, mariadb, mongodb), additionally:

• db_query__<name> — run a validated, read-only query (mutating statements are rejected)

Names are sanitized to the MCP charset — a container named my.db exposes db_query__my_db. Start or stop a container and the tool list updates itself via notifications/tools/list_changed, so the agent always sees the current reality.

Resources

• container://<name>/logs — the last N log lines (text/plain)
• container://<name>/stats — the current stats snapshot (application/json)
• container://events/recent — a ring buffer of recent lifecycle events (application/json)

Started / stopped / appeared / removed events are synthesized from the same snapshot diff that drives the tool list and pushed as MCP notifications, with resources/list_changed when the set changes.

Sandbox tools

Seven permission-gated tools manage disposable agent VMs:

sandbox_list · sandbox_create · sandbox_run · sandbox_stop · sandbox_start · sandbox_reset · sandbox_delete

Write and destructive operations surface a permission prompt in the app before they run.

Try a sandbox in 60 seconds

This is the money demo: let a coding agent work in a VM that can't touch your machine.

You (in Claude Code):  Spin up a fresh sandbox with the claude-code preset and tell me when it's ready.

Agent → sandbox_create { "profile": "claude-code" }
        (Runbay shows a permission prompt → you approve)
        (installs Node + @anthropic-ai/claude-code inside a new container machine VM)
Agent:  Sandbox "sbx-quiet-harbor" is up, isolated (--home-mount none).
        Your $HOME, SSH keys, and cloud tokens are invisible to it.

You:    Clone my repo into it and run the tests.

Agent → sandbox_run { "name": "sbx-quiet-harbor", "command": "git clone … && npm test" }
Agent:  42 passing, 1 failing. The failure is in auth.test.js — want me to open it?

You:    Nope, throw the sandbox away.

Agent → sandbox_delete { "name": "sbx-quiet-harbor" }
Agent:  Gone. Nothing was written to your host.

Prefer the UI? Sandboxes ▸ New does the same thing with an isolation picker, live setup-progress streaming, an in-app terminal into the VM, and repo copy-in via container cp.

Sandbox presets

Isolation defaults to Isolated (--home-mount none). The ro and rw options expose your home directory and say so in red — read the honest model in the sandboxes doc.

Guardrails

• Permission UI for every write or destructive operation.
• Input validation at every MCP boundary (container names, exec commands, queries).
• Rate limiting on all three servers (100/min, 1000/hr per client).
• Read-only by policy for exec__ (allow-list) and db_query__ (mutations rejected).

For the strategic "why," see the FAQ. To go deeper on the container platform itself, start with getting started.