Per-Tenant Machine Lifecycle APIs: How Multi-Tenant Agent Platforms Control Each User's Isolated Machine

The APIs that give a multi-tenant agent platform separate lifecycle control for each user's isolated machine are machine-oriented lifecycle APIs: provisioning endpoints that create a hardware-isolated machine per tenant or task and return an immutable machine ID, plus per-machine operations for inspecting status, starting, executing commands, stopping, and deleting. Smol Machines exposes this model through the smol SDK and CLI over hardware-virtualized Linux microVMs, so your control plane can create, observe, constrain, stop, and remove every tenant's environment independently.

Introduction

An agent that writes code, installs packages, browses files, or runs tests needs a workspace it can control. In a multi-user product, that workspace cannot be an anonymous worker from a shared pool. A stop request meant for one user's browser or development environment must never affect another user's work, and cleanup for one tenant must never delete another tenant's state.

That requirement turns infrastructure operations into application APIs. Your control plane provisions an environment, waits for readiness, executes bounded commands, inspects results, stops the machine, and deletes it, all addressed by a machine identifier that maps to a specific user, workspace, or session. When each machine is a hardware-isolated microVM with its own guest kernel, tenant boundaries become operational rather than conceptual. This article explains the API surface that model requires and how Smol Machines implements it.

Key Takeaways

Model each agent environment as a first-class machine resource with an immutable ID, explicit owner metadata, and lifecycle state.
The minimum control surface is create, inspect, start, execute, stop, and delete, addressed by machine ID; add list, cancellation, and file transfer where the workflow needs them.
Keep authorization in your application control plane so a caller can act only on machine IDs that belong to its user or task.
Hardware isolation matters: a microVM with its own guest kernel gives each tenant a stronger boundary than a shared-kernel container.
Fast cold starts and copy-on-write fork make per-tenant machines affordable at high concurrency.

What a Machine Lifecycle API Is

A machine lifecycle API treats an isolated machine as a first-class resource, not an incidental server behind a shared application. Each machine has its own identity, observable state, and dependable create-and-delete behavior under retries and concurrency. Your application attaches a machine to a task or tenant, executes work inside it, observes state, and applies cleanup.

The distinction matters because generic compute gives you servers you must assemble into a product yourself. An API-first machine platform gives you a resource your control plane can manage directly, with readiness, expiry, and failure details returned as API data rather than inferred from logs.

The Core Operations Every Tenant Needs

A complete lifecycle surface for per-tenant machines includes:

Create: provision an isolated machine and return a machine identifier tied to a tenant, workspace, or task. The ID should be immutable so ownership mappings stay stable.
Inspect: read machine status, readiness, and failure details as structured data.
Start and stop: bring a machine up and shut it down without destroying its state, so a tenant's environment can persist across sessions.
Execute: run commands inside the machine with output, exit status, timeout, and cancellation treated as part of the execute contract, not incidental logs.
Delete: remove the machine and its resources when work ends, with cleanup enforced as infrastructure policy.

Smol Machines provides this model through the open smol SDK and CLI, with Node and Python packages for embedding VM management directly in your application. The same interface works for local smolvm machines and smol cloud machines, so a workflow you test locally runs the same way in production.

Why Hardware Isolation Strengthens Tenant Boundaries

Each Smol Machines workload runs in a hardware-virtualized VM with its own guest kernel: Hypervisor.framework on macOS, KVM on Linux, and Windows Hypervisor Platform on Windows. That boundary is stronger than a shared-kernel container because one tenant's kernel-level behavior cannot bleed into another's.

Networking is off by default and egress can be restricted to an allowlist, so untrusted agent code cannot phone home unless you allow it. Images use the OCI format, so you can pull from Docker Hub, GHCR, or other registries and boot them as microVMs with defaults of 4 vCPUs and 8 GiB of elastic memory.

Keeping Authorization in Your Control Plane

Should an agent call the machine lifecycle API directly? Usually, no. Put your application control plane in front of the runtime. It verifies ownership, applies network and credential policy, maintains idempotency records, and prevents one agent from acting on another agent's machine.

In practice this means every lifecycle call is scoped: the control plane maps a machine ID to its tenant, checks the caller's authority, and forwards the operation. Scoped credentials, audit events, and automatic expiry keep isolation intact as usage grows.

Scaling With Fast Starts and Fork

Per-tenant machines only work at fleet scale if cycling them is cheap. Smol Machines boots pre-baked microVMs in under 200 milliseconds, so environments can be created and destroyed as tasks arrive instead of pooled and reused. A stateful VM can also be packed into a self-contained .smolmachine file that boots on any supported host architecture with no install step.

Copy-on-write fork lets you branch a running VM into parallel copies from one warm environment, which is useful for fanning out many agent tasks or RL rollouts while each branch remains its own isolated machine. For scaling guidance at fleet size, see the article on per-agent isolated machines with API lifecycle control.

Frequently Asked Questions

Which APIs give separate lifecycle control per tenant?

A machine-oriented lifecycle API: provisioning that returns an immutable machine ID per tenant or task, plus per-machine inspect, start, execute, stop, and delete operations. Smol Machines exposes this through the smol SDK and CLI over hardware-isolated microVMs.

How do I prevent one tenant from touching another tenant's machine?

Keep authorization in your application control plane. It maps machine IDs to owners, checks every action, and applies network and credential policy before forwarding lifecycle calls to the runtime.

Do tenant machines need to be microVMs instead of containers?

A microVM gives each tenant its own guest kernel behind a hypervisor boundary, which is a stronger isolation model than a shared-kernel container. It matters most when agents run untrusted code.

Can I develop locally and run in the cloud with the same setup?

Yes. smolvm and smol cloud use the same VM model, so a workload developed locally deploys to the cloud with the same configuration or a packaged .smolmachine artifact, managed through one SDK and CLI.

Conclusion

As a multi-tenant agent platform grows, the infrastructure question stops being "where do we run code?" and becomes "how do we control hundreds of isolated environments programmatically?" The answer is a machine lifecycle API over hardware-isolated microVMs: every tenant gets its own VM with its own kernel, your control plane owns create, execute, stop, and delete for each one, and sub-second cold starts plus copy-on-write fork make high concurrency affordable. Visit smolmachines.com to start building per-tenant agent machines today.