Open sourceRustMIT
isb. Sandboxes you can describe.
A platform you own.
Write down the containers or VMs you want in a small YAML file and isb makes incus match it on your own Linux machine. When a sandbox becomes an app, the same box runs it: replicas, deploys, databases, backups, a web UI, and an MCP server your agents can use.
Every agent, build tool and postinstall script runs with whatever its shell can reach. On most machines that means your SSH keys, your cloud tokens and every repository in your home directory.
Containers made for shipping one process make poor workrooms, and VMs are slow to make and hard to repeat. isb gives each task its own whole Linux machine, a system container with its own init, users, services and network, with only the one project directory it needs mounted.
Root inside is an ordinary user outside. A container is usable in about five seconds and costs almost nothing idle. When you want a separate kernel between the code and your machine, change type: container to type: vm. Same file, same commands.
One file.
The machine follows.
If you know docker compose you know the format. isb up creates what is missing and changes only what differs, every time you run it.
services:
web:
image: images:ubuntu/24.04
cpus: 2
mem_limit: 2g
idmap: auto # files made inside stay yours
volumes:
- ./site:/home/ubuntu/site
ports:
- "8000:8000" # on the host's 127.0.0.1
ready: [running, default_route]
user: ubuntu
working_dir: /home/ubuntu/site
command: python3 -u -m http.server 8000$ isb up # create it, or fix only what drifted
web | Serving HTTP on 0.0.0.0 port 8000 ...
^C # stops it; the next up starts it again
$ isb up -d # or: bring it up and carry on
$ isb exec web -- python3 -m unittest
$ isb down # delete it, host untouched
# the same file, run for months
$ isb serve install
$ isb stack deploy app # replicas, health checks, rollouts
$ isb stack rollback appWe run on it. The dev server for this website runs in an isb sandbox, one per git worktree, so its package installs never touch the host. lasso runs its frontend tooling the same way.
Who it’s
for.
Anyone with a Linux box who wants isolation they can describe, and services they can keep, without an account, a cloud or a per-minute bill.
- 01
AI agents and untrusted code
Give each agent or task its own machine with one directory mounted, instead of your home directory and its credentials. A dev server an agent starts is stopped when the agent goes away.
- 02
A dev environment per branch
One sandbox per git worktree, each with its own dependencies and dev server, side by side. A mount that is already right is never touched, so hot reload survives every
isb up. - 03
Apps that run for months
Replicated, health-checked, load-balanced services with zero-downtime rollouts and rollbacks, from the same file you develop with.
- 04
Teams that want their own platform
Orgs with quotas and their own network, members and roles, passkeys and SSO, a web UI, and apps that deploy on push, the way Dokploy works, on hardware you control.
Everything on
one binary.
A single static binary is the CLI, the daemon, the web UI and the MCP server. Python, TypeScript and Rust SDKs drive the same core, so they behave identically.
- 01 · Sandboxes
Converges, never churns
Sandboxes · isb.yamlisb planshows the difference,isb upchanges only that. Every incus call has a deadline, so a stall names the step instead of hanging. - 02 · Stacks
A swarm for one host
Stacksdeploy.replicas, health checks, a least-connections load balancer,start-firstrolling updates and one-command rollback. - 03 · Apps
Deploy on push
Projects and environments; apps from an image or a git repo (railpack, Dockerfile or nixpacks); webhooks from GitHub, GitLab and Gitea; a preview per pull request.
Deploy apps · Previews - 04 · Data
Databases and backups
Postgres, MySQL, MariaDB, MongoDB and Redis. Scheduled backups to S3, R2, B2 or MinIO with retention, restored into a new database. Cron jobs too.
Databases · Jobs - 05 · Templates
One-command apps
Uptime Kuma, Plausible, Gitea, n8n, Ghost, Umami, Vaultwarden, MinIO and more built in, plus the Dokploy template catalog.
Templates - 06 · Ingress
Real hostnames, real TLS
Caddy with Let’s Encrypt on the host, or a Cloudflare Tunnel per org, with the domains each org may use allow-listed.
Domains and ingress - 07 · Orgs
A boundary per tenant
Each org is a restricted incus project with its own bridge, quotas and egress allow-list, and its own age-encrypted secret store with break-glass recipients.
Orgs · Secrets - 08 · Access
People, roles, tokens
Passwords, passkeys, GitHub, Google or any OIDC provider; viewer to owner roles; scoped, expiring API tokens; superadmins proven by your tailnet or Cloudflare Access.
Access · Sign-in - 09 · Agents
An MCP server, with a leash
Agents deploy stacks, run sandboxes and query metrics as MCP tools, held to a policy: allowed and denied tools, a bind root, no privileged containers by default.
Agents and MCP · MCP tools - 10 · Servers
More than one box
Add servers over SSH and place an org on its own host or its own VM. Calls are forwarded over mutual TLS: federation, not clustering.
Placement · Servers - 11 · Workspaces
A home for each team
Each org gets a long-lived machine with a home that survives rebuilds, where its people and agents work. Agents there make expiring sandboxes beside it through the org’s MCP, and reach nothing outside the org.
Workspaces - 12 · Operate
See all of it
A web UI and a terminal dashboard, metrics history, a hash-chained audit log, and notifications to Slack, Discord, Telegram, email or a signed webhook.
Web UI · TUI · Audit
Quick
start.
isb needs a Linux host with incus, and access to its socket. On a Mac it runs incus in a Lima VM it manages for you.
- 01
Install incus
From your distribution, following the incus guide. Membership in
incus-adminis root-equivalent on that host, so treat it like sudo. - 02
Install isb
A static binary, nothing to compile. Prebuilt for x86_64 and aarch64 on the releases page. Install isb has every option.
$ mise use -g github:execution-associates/isb # or: cargo install isb $ pip install isb-sdk # Python, imported as isb $ bun add @execution-associates/isb # TypeScript - 03
Describe a sandbox, bring it up
Save the
isb.yamlabove next to asite/folder, thenisb up.isb downdeletes it. Your first sandbox walks through it, and your first org and app goes on to the platform. - 04
On a Mac
$ brew install lima $ isb machine init - 05
Give it to your agents
The repo’s
SKILL.mdteaches an agent to use isb correctly. For Claude Code, put it at~/.claude/skills/isb/SKILL.md.
The
documentation.
Straight from the isb repository, rebuilt with every deploy of this site.
Getting started
- Getting startedInstall isb, make your first sandbox, then run your first org and app on the isb serve daemon.
- InstallInstall incus and the isb binary on Linux or macOS, and the Python, TypeScript or Rust SDK if you want one.
- macOSHow isb runs incus in a Lima VM it manages on a Mac, with your home shared and ports forwarded to localhost.
- First sandboxDescribe a sandbox in isb.yaml, bring it up, run commands in it, change it, and delete it.
- First org and appRun the isb serve daemon, create the first admin and an org, deploy an app, and open the web UI.
- Web UIA tour of the browser UI that isb serve ships in its binary: orgs, workspaces, apps, deployments, databases, backups, members, MCP and the platform pages.
Concepts
- ConceptsThe ideas isb is built on, from a single sandbox up to orgs placed on other machines.
- SandboxesWhat a sandbox is, why isb builds on incus, and how isb makes incus match what you described.
- OrgsThe org is isb's trust boundary, an incus project with its own network, quotas and egress rules.
- AppsThe app layer over stacks, organized the way Dokploy organizes it.
- StacksLong-running services on the isb serve daemon, with replicas, health checks, a load balancer, rolling updates and rollbacks.
- WorkspacesAn org's long-lived machine, where its people and agents work, and the short-lived sandboxes they make beside it.
- PlacementWhere an org runs decides what keeps it apart from other orgs, from a shared kernel to a machine of its own.
- Security modelWhat keeps orgs apart from each other and from the host, what a remote caller may ask for, and what isb does not protect against.
- Users and rolesWho may do what in isb serve, from an org viewer to a superadmin with the host's reach.
Guides
- GuidesTask-by-task guides for running apps, data, access and agents on isb.
- Deploy appsCreate apps in a project environment, edit their environment, deploy, roll back, and deploy on every push with webhooks.
- Builds and registryTurn a source directory into an OCI image in a throwaway sandbox, push it to the host's registry, and run it from a stack or app.
- Preview deploymentsA preview of every pull request, built and served on its own URL while it is open, isolated from production.
- TemplatesDeploy ready-made sets of apps (Gitea, Umami, Ghost and more, or Dokploy's or Coolify's catalog) with settings filled in and passwords generated.
- Coming from DokployHow Dokploy's projects, applications, databases, templates and integrations map onto isb, and what works differently.
- Coming from CoolifyHow Coolify's servers, projects, resources and one-click services map onto isb, and how to deploy its templates here.
- Databases and backupsRun Postgres, MySQL, MariaDB, MongoDB or Redis as an app with generated credentials, back it up to S3 on a schedule, and restore it.
- VolumesSnapshot an org's named volumes now or on a schedule, back them up to S3, and restore beside the live volume, never over it.
- Scheduled jobsRun a command on a cron schedule against an app or stack service, in a running replica or a one-off instance, with every run's output kept.
- NotificationsTell an org's people about failed deploys, unhealthy services, certificates, backups and jobs, through webhooks, Slack, Discord, Telegram or email.
- Uptime monitoringHear about it when an app users reach is down, with uptime history, incidents, certificate expiry warnings, and a heartbeat for when the host itself dies.
- SecretsKeep passwords, tokens and keys in an org's encrypted store, and deliver them to services as files or variables.
- Domains and ingressPut a stack or app on a public hostname with HTTPS, on the server's own ports or through an org's Cloudflare Tunnel.
- Remote accessPut the daemon's web UI, MCP server and API behind Cloudflare Tunnel and Access, or serve it on a tailnet.
- Sign-inCreate the first admin, invite people, and let them sign in with a password, a passkey, GitHub, Google or your own OIDC provider.
- Agents and MCPConnect an AI agent to isb over MCP, with a token that reaches one org, and let agents in an org's workspace make their own sandboxes.
- isb for kubectl usersWhat you did with kubectl, as isb CLI commands and MCP tools: list and describe instances, exec, logs, copy files, scale, restart, events, top.
- SSH and herdrPlain ssh, scp, rsync, editors and herdr into any instance of an org, over isb's own authenticated connection, with nothing listening in the instance.
- Servers and dedicated VMsRun whole orgs on other hosts, or in a VM of their own, all managed from one control plane.
- Workspace images and recipesBuild the images workspaces start from with a recipe script, use isb's default image (Claude Code, omp, herdr, mise), and tweak each workspace on its first boot.
- Dev environmentsGive every branch, worktree or agent its own sandbox from an isb.yaml, with one project directory mounted and a dev server that dies with the session.
- SDKsCreate sandboxes, run commands and load isb.yaml files from Python, TypeScript or Rust.
- Egress and secretsConfine a sandbox's network to a list of hostnames, and give it secrets it can use but never read, for running untrusted code in a container or a VM.
Reference
- ReferenceExact, exhaustive descriptions of isb's commands, file format, tools, APIs and settings.
- CLIEvery isb command and flag, the global flags, where each command sends its work, and the exit codes.
- isb.yamlEvery field of the compose file, how variables are filled in, and exactly what isb up changes on an existing sandbox.
- MCP toolsEvery tool isb serve offers to agents, people, the web UI and the CLI, grouped by area, with who may call each.
- HTTP APIThe isb serve daemon's HTTP surfaces: MCP, REST tools, the event stream, the terminal and SSH websockets, the workspace resource and webhooks.
- Identity APIThe /api/v1/auth endpoints of isb serve, and exactly how sign-in, passkeys, sessions, tokens, CSRF protection and rate limits work.
- ConfigurationEvery isb serve flag with its environment variable and default, every other variable isb reads, and the files it keeps its settings in.
- rpc protocolisb rpc, the line-delimited JSON protocol the Python and TypeScript SDKs speak, for driving isb from any language.
- isb tuiThe terminal dashboard of stacks and sandboxes: what it shows, where its data comes from, and its keys.
Operations
- OperationsRunning isb serve on a host you look after: setup, upgrades, backups, the audit log, the history, metrics and troubleshooting.
- Host setupInstall isb serve as a service, prepare the host firewall and DNS for orgs, set up the local registry, and know what the state directory holds.
- Upgrading isbWhat to do after installing a new isb binary on a host, on a Mac, and on the servers a control plane manages, and what an upgrade changes on its own.
- Backing up isbWhat to copy so the platform itself can be restored, what isb backs up for you, and what must stay out of a backup.
- The audit logWho did what, through which door, and how it went, kept append-only with a hash chain that shows tampering.
- The historyOne persistent timeline of controller events, every incus change (made through isb or not), audit rows and markers, so any state can be traced back.
- Metrics historyA month of CPU, memory, network and disk numbers for every instance of every org, kept in tiers and queried with metrics_query.
- TroubleshootingSymptoms you may meet with isb, what causes them, and the fix, from a stalled create to a server that stopped answering.
Contributing
- ContributingHow the repository is laid out, how to build and test isb safely in a sandbox, the checks CI runs, the legibility ratchet, and measuring compile time.
- Web UIHow the web UI is built, how it talks to the daemon, how it is embedded in and served by the isb binary, its design system, and the development loop.
Rendered from execution-associates/isb/docs at platform@c3abfa6.
Want isolated agent workspaces or a self-hosted platform running for your team? We built isb, and we set it up.
Put us on it