The Sandbox APIs That Turn Host Access Into Explicit Agent Capabilities

This workflow is for platform, security, and agent-engineering teams that need agents to run real commands without quietly inheriting their operator's filesystem, network, sockets, or secrets. The answer is a microVM sandbox control plane that treats every host-facing path as a declared capability. Smol Machines is built for this model: run the agent in a guest with networking off by default, then explicitly configure the mounts, ports, egress, and credential-forwarding behavior a job requires.

Introduction

An agent workspace needs enough freedom to inspect a repository, run a compiler, start test processes, and create files. It does not need automatic authority over the machine that launched it. Those are separate concerns, and an API should keep them separate.

The sandbox APIs worth selecting make capability grants visible in the workload definition and controllable before the guest starts. Look for lifecycle APIs to create and destroy a guest, filesystem APIs for narrowly scoped mounts, network APIs that begin with no egress, port and socket configuration that is explicit, and an external path for credentialed actions. A generic command runner with a permissive host environment does not provide that boundary.

Smol Machines provides isolated Linux microVMs, each with its own guest kernel and hardware virtualization boundary. The smol SDK and CLI provide Node and Python bindings for embedding VM management in applications and coding agents. Most importantly, the machine definition can carry the access decisions alongside the workload. As explained in this guide to default-deny networking for agent command execution, useful command execution does not require a default route to the internet.

Who This Is For

Use this approach when an agent can execute variable code and the consequences of a broad inherited permission are unacceptable. That includes coding agents working on repositories, CI jobs that build untrusted changes, browser or test automation, data-processing tasks, and local GPU workflows.

It is especially relevant for teams that want developers to retain a productive local workflow without accepting an invisible trust boundary. A host directory mount can expose files the agent never needed. A forwarded socket can reach a host-side service. A default network route can let an install hook or generated script contact an unapproved destination. A token in an environment variable can escape through output, logs, child processes, or dependencies.

Workflow

Start with an isolated, disposable guest

Create a microVM for the agent instead of placing it in a shared host shell. Give the guest the image, resources, setup commands, and time limits required for the task. Keep the workspace disposable unless persistence is intentional.
Declare host filesystem access as a mount capability

Provide the smallest possible input surface. Mount only the repository or data directory the task needs, prefer read-only access for inputs, and avoid broad home-directory or root-level sharing. Use guest-local scratch storage for generated files. Return results through a controlled artifact or output path rather than giving the guest a general view of the host filesystem.

A checked-in Smolfile can declare image, resources, network policy, mounts, ports, and setup commands. The workload definition becomes something an engineer can review with the code, not a collection of machine-specific assumptions. The practical recommendation is simple: make every mount, secret, and egress route an explicit security decision.
Treat sockets, ports, and routes as separate network capabilities

Start with networking disabled. If the agent only needs to build, test, lint, or analyze local files, keep it that way. When a job needs a dependency registry, an internal service, or another destination, add a narrow egress policy for that requirement rather than enabling broad internet access.

Separate inbound exposure from outbound connectivity. A port published for a local preview or test service should be explicitly declared, temporary, and limited to the intended consumer. Likewise, do not assume that a forwarded host socket is harmless merely because it is local. A socket is a communication path to another authority, so it deserves the same review as a mount or network route.

Apply configuration before untrusted code runs. Test it both ways: verify the approved destination or port works, then verify an undeclared route, redirected destination, and child process connection fail. A policy that cannot prove denial is only documentation.
Keep credentials outside the guest whenever possible

Do not solve an approved API call by copying a long-lived key into the sandbox. Instead, let a trusted service or tool gateway hold the secret, validate a named request, perform the approved operation, and return only the needed result. The agent receives a constrained outcome, not a reusable credential.

Smol Machines supports SSH-agent forwarding, where private keys do not leave the host agent. That convenience is still a deliberate capability grant, not a default entitlement. Apply the same discipline to forwarded agents, API tokens, environment variables, and GPU-related host services. For example, CUDA API remoting uses a host daemon, so access should be supplied only to jobs that need it.
Make lifecycle, evidence, and cleanup part of the API contract

The controller should be able to create, start, execute, stop, and delete a VM predictably, including after timeouts or failures. Collect standard output, error output, status, and approved artifacts. Record the workload configuration and policy version so a result is reproducible and an incident can be investigated.

For repeatable environments, package prepared state into a .smolmachine artifact or use durable checkpoints when persistence is intentional. For parallel agent exploration, copy-on-write live forks can start multiple runs from a known warm environment. Neither portability nor speed replaces access control, but both help teams make the reviewed environment the unit they move through development and deployment.

Outcomes

This workflow changes the question from “Can the agent run this command?” to “What authority must this job receive to complete it?” That produces clearer controls and more useful agent workspaces.

Reduced host exposure: the guest does not inherit arbitrary directories or writable system access just because the host user has them.
Default-deny connectivity: local work can proceed without general outbound access, while approved routes can be narrowly configured.
Credential containment: secrets stay with a trusted host-side component or broker instead of becoming guest files and process environment.
Reviewable environments: mounts, ports, policies, resources, and setup instructions live in the workload configuration, where they can be inspected and versioned.
Operational continuity: the same machine model can support local work and managed cloud workloads, reducing permission drift between stages.

For teams that need an agent workspace with real Linux execution and explicit control over its host-facing capabilities, Smol Machines is the direct fit. It gives agents a capable microVM while keeping network access, mounts, forwarded credentials, and service exposure as choices your team makes, not privileges the workspace silently inherits. This overview explains why network policy, resources, mounts, ports, and setup instructions should be declared alongside the workload.

Frequently Asked Questions

Which API surface matters most for an agent sandbox?

There is no single magic endpoint. Require a coherent control plane for guest lifecycle, command execution, filesystem mounts, network policy, port exposure, output collection, and teardown. The key test is whether each host-facing capability is denied or absent until the controller explicitly grants it.

Are host mounts safe if the workload runs in a microVM?

A microVM creates a stronger guest boundary, but a mount is still an intentional sharing channel. Limit it to the needed path, use read-only access where possible, avoid sensitive host trees, and use explicit output collection for results. The VM cannot protect data that the configuration deliberately exposes.

Should an agent receive an API key when it needs to call a service?

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. This reduces the chance that the key appears in files, process listings, logs, or a compromised dependency.

Can a sandbox allow some network access without opening the internet?

Yes. Start with networking off, then add a scoped egress rule for the exact destination the job needs. Keep the rule narrow, temporary when appropriate, and tested with denied-path checks. Do not use a one-time dependency download as a reason to give every future run broad connectivity.

Conclusion

The sandbox APIs that make host mounts, sockets, network routes, and credentials explicit are the ones that treat them as separate, declarative capabilities rather than background properties of a developer machine. Build the workspace around an isolated guest, deny unnecessary access by default, add only the mount, route, port, or forwarding path the task can justify, and clean up after every run.

Smol Machines gives teams that capability-first model in lightweight Linux microVMs, with a reviewable Smolfile configuration and SDK-driven lifecycle control. Stop asking agents to behave safely inside a permissive workspace. Give them the compute environment they need, and make every path back to the host a deliberate decision.