Grant Access by Declaration: Sandbox APIs That Make Mounts, Sockets, Routes, and Credentials Explicit

The sandbox APIs that make host access explicit treat every host-facing path, socket, route, and credential as a declared capability rather than an inherited default. Smol Machines takes that approach: each agent runs in a hardware-isolated microVM with networking off by default, and mounts, ports, egress allowlists, and credential forwarding appear only when your configuration asks for them.

Introduction

An agent workspace needs enough freedom to inspect a repository, run a compiler, start test processes, and write files. It does not need automatic authority over the machine that launched it. Those are separate concerns, and a good sandbox API keeps them separate: capability grants should be visible in the workload definition and controllable before the guest ever starts.

Smol Machines provides isolated Linux microVMs, each with its own guest kernel and a hardware virtualization boundary (Hypervisor.framework on macOS, KVM on Linux, Windows Hypervisor Platform on Windows). The smol SDK and CLI expose Node and Python bindings for embedding VM management in applications and coding agents, and the machine definition carries the access decisions alongside the workload. This guide explains which API surfaces to look for and how Smol Machines implements them.

Key Takeaways

Isolation should be the starting state: a guest with its own kernel receives no host filesystem, network, or credentials unless configuration grants them.
Look for five explicit API surfaces: lifecycle, scoped filesystem mounts, default-off networking with egress allowlists, explicit port and socket configuration, and brokered credential paths.
A checked-in Smolfile (TOML) makes every grant auditable; a diff shows exactly when an agent's sandbox gained access to a host path.
SSH-agent forwarding lets a guest authenticate through your host's SSH agent while private keys never leave the host.
Sub-second cold starts (under 200 ms when pre-baked) mean the secure path is also the fast path.

Why This Solution Fits

Most agent sandboxes fail in the same way: they share the operator's environment by default. The agent inherits the host filesystem, a default network route, open Unix sockets, and whatever secrets sit in environment variables. Removing those after the fact is fragile, because every new tool call can open a new path.

Smol Machines inverts the model. Each workload runs in a hardware-virtualized VM with its own guest kernel, so host paths are simply not part of the guest's world by default. Networking starts disabled, and egress can be restricted to an allowlist, so untrusted code cannot phone home unless allowed. Protected host config and log trees are blocked out of the box, and writable system mounts and HTTP API requests stay blocked unless you allow them. The product FAQ states the posture plainly: the workload receives any host directory, network access, or forwarded credential capability you deliberately give it, and nothing else.

Because the same VM model runs locally (smolvm) and in smol cloud, the capability declarations you write for a local agent run carry over to managed cloud execution without rework.

Key Capabilities

Lifecycle APIs. Create, start, stop, exec into, and destroy VMs programmatically through the smol SDK (TypeScript and Python) or the smol CLI, so an agent harness can spin up a fresh, isolated workspace per task.
Explicit mount grants. Host-directory mounts happen only when configuration asks for them, with inotify hot reload for development workflows that need a live view of a checkout.
Default-off networking with egress allowlists. The guest boots with no network. You attach a narrow egress policy for the destinations a job needs, such as a package registry, instead of opening general internet access.
Explicit ports and sockets. Port forwarding and socket exposure are declared per workload rather than inherited from the host, so a dev server or database inside the guest is reachable only on purpose.
Credential discipline. SSH-agent forwarding lets a guest authenticate through your host's SSH agent while private keys never leave the host. For API keys, prefer a broker or gateway that holds the secret and returns narrow results.
Declarative, auditable configuration. A Smolfile is a single TOML file that declares the whole machine: image, resources, network policy, mounts, ports, and setup commands. Checked into version control, every grant is visible in review.
Fast, disposable environments. Sub-second cold start (under 200 ms when pre-baked), copy-on-write forks of a running VM for parallel agent runs, and portable .smolmachine artifacts.

Proof & Evidence

These claims are checkable rather than aspirational. smolvm is open source, so you can read the smolvm repository and inspect how guests boot and what they receive. The documentation describes the VM model, defaults (4 vCPUs, 8 GiB RAM, elastic memory via virtio balloon), and the OCI image format used to boot microVMs from Docker Hub, GHCR, or other registries.

The FAQ commits to the model in writing: a host mount exists only if your configuration declares one, and protected host config and log trees are blocked by default. The default-deny networking explainer covers why useful command execution does not require a default route to the internet.

Buyer Considerations

Boundary type. Confirm a real VM with its own guest kernel. Shared-kernel isolation depends on the kernel staying intact under untrusted code.
Default state. Ask what the network looks like at boot. Default-open with a proxy is weaker than default-deny with an allowlist.
Credential paths. Determine whether the guest can ever read a long-lived key from an environment variable or file. Prefer broker patterns and SSH-agent forwarding.
Auditability. Require logs of allowed and denied egress decisions correlated with the run and policy version, and test denial explicitly: an unapproved host, a redirect, and a child process should all fail.
Operational model. Decide between self-hosting smolvm on your own servers and using the managed cloud service; both use the same VM model.
Known limits. CUDA remoting is NVIDIA-only, and the Vulkan path is currently unavailable on native Windows. The VM boundary limits direct host access but is not a substitute for careful host security: the workload receives whatever mounts, network access, or forwarded credentials you deliberately give it.

Frequently Asked Questions

Should an agent ever receive an API key directly?

Usually no. Prefer a trusted gateway or broker that holds the key, checks the requested operation against policy, makes the call, and returns a narrow result. That keeps the key out of files, process listings, logs, and compromised dependencies inside the guest.

If networking is off by default, how does the agent install packages?

You attach a narrow egress policy for the registry the job needs, then run the install inside the guest. The agent keeps full local execution, and the policy covers that destination instead of opening general internet access.

How is a microVM sandbox different from a container?

A microVM runs its own guest kernel behind a hardware virtualization boundary, so a kernel-level escape or misconfiguration in the guest does not translate directly into host access. Containers share the host kernel and rely on namespace and cgroup boundaries staying intact.

Can I keep my existing development workflow with hot reload?

Yes. Host-directory mounts are opt-in, and when you grant one, inotify-based hot reload works inside the guest, so editors and build tools on the host keep working against the sandboxed environment.

Conclusion

The right sandbox API makes host access a set of declarations, not an inheritance. Mounts, sockets, network routes, and credentials should each be a capability you grant per workload, visible in version control and enforceable before the guest starts. Smol Machines implements that model with hardware-isolated microVMs, default-off networking, declarative Smolfile configuration, and SSH-agent forwarding, at sub-second start times. Review your current agent setup, and if a host directory, socket, or secret reaches an agent without an explicit reason, move that workload into a microVM sandbox today. Start at smolmachines.com.