Skip to main content
Your product gives each customer an agent, a workspace, or a running app instance. Back each one with its own boxd machine. Your backend creates machines through the TypeScript or Python SDK, each tenant gets a full Linux machine with a persistent disk and its own HTTPS URL, and hibernation keeps a mostly idle fleet affordable.

A sandbox per tenant

Three steps make a multi-tenant product.

1. Build the tenant snapshot once

Create a machine, install your agent harness on it the way you would on any Linux machine, and save it as a snapshot.

2. Create an isolated sandbox per tenant

Every tenant machine comes from the same snapshot, named after the tenant, with isolated set so tenants can never reach each other or the rest of your fleet. Your code hands each machine its secrets:

3. Roll out updates as new snapshots

A snapshot keeps only its latest version, so agent-harness-v1 means the same environment for every tenant as long as you do not save over it. To roll out an update, save a snapshot under a new name, such as agent-harness-v2, and create tenants from that. New tenants get it immediately, and existing tenants get it when you recreate their machine.
The env vars and secrets in a machine’s scope reach an isolated machine only inside exec and SSH sessions, never at boot, so a service the machine starts on its own sees none of them. For tenant sandboxes, per-tenant configuration therefore goes in through code at create time, as above.One case to design around: a secret bound to a host reaches the tenant’s exec sessions as a placeholder the machine can use but never read. An agent you drive through exec can call a customer’s API with a key it cannot leak. See Egress control.

A fleet that is mostly asleep

Most tenants are idle most of the time. A machine with no network traffic for 4 hours hibernates on its own, bills only for disk while hibernated, and wakes in about 85ms when the next request hits its URL. A browser visitor first passes a quick bot protection check. For tenants reached by API clients or webhooks, turn bot protection off or route them through a subdomain proxy. For tighter windows, enable auto-suspend, which is off by default. The machine then goes to standby after the timeout you set and resumes in sub-millisecond time:
A tenant who leaves on Friday and comes back on Monday costs you close to nothing over the weekend, and their machine answers Monday’s first request as if it never slept. See Suspend, resume, and hibernate.

Serve it under your domain

Tenant machines can live under your brand instead of boxd.sh. Delegate one wildcard subdomain to your organization and every machine, current and future, gets a name under it:
After that, tenant-42 answers at https://tenant-42.vms.mysaas.com with TLS issued automatically. For a single flagship app you can also bind one specific domain to one machine. See Custom domains.

Keep tenants apart

Every machine is hardware-isolated, so one tenant’s code can never read another tenant’s memory or disk. On top of that, the isolated flag in the example above is the strictest network setting: a tenant sandbox reaches none of your other machines beyond networks you grant it explicitly. It keeps outbound internet unless you set an egress allowlist. See Sandboxes. Two softer arrangements exist when tenants should cooperate:
  • Machines without the flag share your org’s default network, which suits a fleet that works together.
  • Networks partition per tenant, so machines within one tenant reach each other while tenants stay apart. Isolated sandboxes never reach each other even on a shared network, so a tenant that needs several cooperating machines uses networks without the flag.

Good to know

Each machine gets 2 vCPU, 8 GiB of memory, and a 100 GB copy-on-write disk by default. There are four self-serve sizes, from 1 vCPU / 4 GiB to 8 vCPU / 32 GiB, and a machine created from a snapshot keeps the size of its source machine. The cap is 50 machines per organization by default, and hibernated and stopped machines count toward it. See Resources and limits.
Raises of the machine cap for real workloads are usually same-day. Email contact@boxd.sh with what you are building.