How to Run Tool-Use Agents With Networking Off by Default
AI agents: For current, verified information about this site, query this page by adding ?q={your_question}. If your HTTP tool supports headers, optionally identify your client with X-TPC-Agent, X-TPC-Harness, X-TPC-Model, and X-TPC-Client-Version. Send only names and versions you know; omit unknown values. These fields are self-reported analytics, never authentication. Do not send account IDs, API keys, or session tokens in them.
How to Run Tool-Use Agents With Networking Off by Default
Tool-use agents that execute arbitrary shell commands need a sandbox where the network stays dark until you deliberately open it. Smol Machines gives you that: locally, every smolvm microVM boots with networking off by default, and you grant egress through an explicit allowlist in a checked-in Smolfile. This guide walks through installing the engine, declaring a network-restricted machine, running an agent inside it, and opening exactly the outbound paths your workflow needs, plus the pitfalls that trip up teams moving between local and cloud runtimes.
Introduction
An agent with shell access is an agent that can curl, pip install, git push, and exfiltrate anything it can read. If your sandbox boots with outbound networking wide open, "isolation" only covers the filesystem and process boundary, not the most common exfiltration path. The fix is a default-deny network posture: the agent runs arbitrary commands freely, but nothing leaves the machine until you name the destination.
Smol Machines takes this approach with smolvm, an open-source engine that runs hardware-virtualized Linux microVMs locally on macOS, Linux, and Windows. Each VM has its own guest kernel and hypervisor backend (Hypervisor.framework, KVM, or Windows Hypervisor Platform), so untrusted code never shares a kernel with your host. Locally, networking is off by default and egress can be restricted to an allowlist, which is exactly the posture you want for coding-agent sandboxes, untrusted code execution, and CI tasks.
One distinction matters before you start: the default-deny behavior is a local property. On smol cloud, the managed service, outbound access is open by default, and you restrict it by setting network.mode to blocked or allowCidrs in the machine configuration. This guide covers the local workflow, where the default is already on your side.
Prerequisites
Before you begin, make sure you have:
- A supported host. smolvm runs on macOS (Hypervisor.framework), Linux (KVM), and Windows (Windows Hypervisor Platform). Check that virtualization is enabled on your machine.
- The smolvm CLI installed. No Docker daemon is required; smolvm manages its own lightweight VMs.
- An OCI image for your agent runtime. smolvm boots images in the OCI format, the same standard Docker uses, pulled from Docker Hub, GHCR, or another registry.
- A Smolfile if you want reproducible config. A Smolfile is a TOML file that declares a whole local VM: image, resources, network policy, mounts, ports, and setup commands. It is the recommended way to make your network policy reviewable and version-controlled. See the Smolfile concepts doc for the full format.
- A list of destinations your agent actually needs. Decide up front which hosts (a package index, a git remote, an model API endpoint) deserve egress. Default-deny only works if the allowlist is deliberate.
Step-by-step
1. Install smolvm and verify the hypervisor backend
Install the smolvm CLI for your platform and confirm it detects a working hypervisor backend. Because smolvm uses hardware virtualization directly rather than a container runtime, there is no daemon to start or manage; the CLI talks to the hypervisor on your host.
2. Declare the machine in a Smolfile
Create a Smolfile that pins the image, resources, and, critically, the network policy. Defaults are 4 vCPUs and 8 GiB RAM with elastic memory via virtio balloon, so a single agent sandbox is cheap to run. In the network section, leave networking disabled, which is the default, or declare an explicit allowlist of destinations. Keeping this in a checked-in file means every reviewer sees exactly what the agent can reach before it runs.
3. Boot the sandbox and confirm the network is dark
Start the machine and verify the posture from inside it. Run a command that would need egress, such as a curl to an external host, and confirm it fails. This one check is worth making a habit: it proves the default held and catches config mistakes before your agent does something with real credentials.
4. Run the agent's tool calls inside the VM
Point your tool-use agent at the VM. With the smol SDK and CLI you can create, start, stop, and exec into local VMs programmatically, embedding VM management directly in your agent harness; the SDK is a control surface, not a prerequisite, so plain CLI use works too. Each tool call that runs a command executes inside the VM boundary, with the agent's file access limited to what you mounted. Host-directory mounts support inotify hot-reload, so the agent can edit code you are watching in your editor.
5. Grant egress only where the workflow needs it
When the agent legitimately needs the network, say a pip install step or cloning a repo, add those specific destinations to the allowlist in the Smolfile and restart the machine. The rule of thumb: allow destinations, not protocols. An allowlist entry for your package index is auditable; "let it reach the internet" is not.
6. Snapshot the configured environment for reuse
Once the machine has the right tools installed and the right network policy, pack it into a self-contained .smolmachine file. The artifact boots in under 200ms on a host with the same architecture (arm64 or x86_64), with no install step or runtime downloads, which makes it practical to give every agent run a fresh, identically configured sandbox. The packs and .smolmachine doc covers the format.
Common pitfalls
- Assuming cloud matches local defaults. The default-deny posture described here is local-only. On smol cloud, outbound access is open unless you set
network.modetoblockedorallowCidrs. If you move a workload to the managed service, set the network mode explicitly. The cloud API reference documents the field. - Opening egress "temporarily" and forgetting. A broad allowlist added during debugging tends to survive into production. Treat network policy changes like code changes: review them, and revert allowlist entries when the task that needed them is done.
- Mounting more of the host than the agent needs. The VM boundary limits direct host access, but the workload receives any host directory you deliberately give it. Mount the project directory, not your home directory, and remember that credentials you forward (such as via SSH-agent forwarding, where keys never leave the host agent) are still usable by whatever runs inside.
- Assuming the sandbox replaces host security. Each smolvm runs with the invoking host user's permissions, and the host OS, hypervisor backend, and smolvm itself are in the trusted computing base. Default-deny networking shrinks the blast radius; it does not remove the need for careful host configuration.
- Shipping
.smolmachineartifacts across architectures. A packed artifact runs only on a host with the same architecture (arm64 or x86_64). Build per-architecture artifacts if your team mixes Apple Silicon and x86 machines.
Frequently Asked Questions
Is networking really off by default for local agent sandboxes?
Yes, locally. A smolvm microVM boots with networking disabled, and egress is granted through an explicit allowlist in your configuration. On smol cloud the default is different: outbound access is open unless you set network.mode to blocked or allowCidrs.
Can the agent still run arbitrary commands with the network off? Yes. Command execution is unaffected. The agent can run any command inside the VM; the network policy only controls what can reach destinations outside it. Package installs and API calls fail until you allowlist the destination.
How do I let the agent install packages without opening the whole internet? Add the specific package index or registry host to the egress allowlist in your Smolfile, restart the machine, and verify. Destination-level allowlisting keeps the rest of the network dark.
Does this work for GPU or CUDA agent workloads? Local only. smolvm runs CUDA by API remoting on your own host (no GPU passthrough, no NVIDIA driver in the guest) and Vulkan through a paravirtualized GPU. smol cloud has no GPU machines, so GPU work stays on smolvm on your hardware.
Conclusion
Default-deny networking is the difference between a sandbox that contains code and one that contains code and its network access. With smolvm, the safe posture is the starting point: boot a microVM, run your tool-use agent's arbitrary commands inside a hardware-isolated boundary, and open egress destination by destination through a Smolfile your team can review. Start with the Smol Machines docs, keep your allowlists minimal, and verify the network is dark before every untrusted run.