Volumes, Mounts, and Network Config in One File: How the Same Environment Runs Locally and in the Cloud

Volumes, host mounts, and network configuration are handled by a single declarative definition: a Smolfile, a TOML file that declares the entire VM, including image, resources, network policy, mounts, ports, and setup commands. The smolvm engine applies that definition to hardware-isolated microVMs on your laptop, smol cloud applies the same VM model to managed persistent VMs, and the smol SDK and CLI drive both from one interface. Networking stays off until you explicitly allowlist it, and the same policy follows the workload from local development to production.

Introduction

Most teams solve the same three problems twice. Volumes get a local bind-mount script and a separate cloud storage claim. Host mounts exist as ad-hoc docker run -v flags on one machine and as provisioning code on another. Network rules live in a firewall config, a compose file, and a cloud security group, all drifting apart at their own pace.

The drift is not cosmetic. A mount path that exists on your laptop breaks the cloud run. A port opened locally is missing in production. An egress rule added during a late-night debugging session never makes it back into review. The fix is not better synchronization between two definitions. The fix is one definition.

Smol Machines takes that approach. The environment is a checked-in file, the runtime is the same VM model locally and in the cloud, and the control surface is one SDK and CLI. This article explains how each concern (volumes, host mounts, and network configuration) is expressed once and applied everywhere.

Key Takeaways

One Smolfile declares the whole VM: image, resources, network policy, mounts, ports, and setup commands, in a single TOML file you check in next to your code.
The same VM model runs locally on macOS, Linux, or Windows and in smol cloud, so one definition serves both environments.
Networking is off by default. Egress opens only through explicit allowlists: --allow-host locally and allowCidrs in smol cloud.
Host-directory mounts are opt-in, with inotify hot reload for development workflows, and every mount is visible in review as part of the file.
A validated environment packs into a self-contained .smolmachine artifact that boots in under 200 ms with no install step or runtime downloads.

One Definition for the Whole Machine

A Smolfile is a TOML file that describes a complete virtual machine: the OCI image to boot, CPU and memory resources, network policy, host-directory mounts, forwarded ports, and the setup commands that prepare the guest. Because it is a file, it lives in version control next to your application code. Every grant the workload receives is visible in a diff, not reconstructed from shell history.

That single file replaces the usual scatter of local scripts and cloud provisioning code. Reviewers see exactly which directories the workload can touch, which ports it exposes, and which hosts it may contact, before any of it runs.

The product documentation describes the VM model and defaults: 4 vCPUs, 8 GiB RAM, and elastic memory via virtio balloon. Images use the OCI format, so you can pull from Docker Hub, GHCR, or any other OCI registry and boot the image as a microVM.

Volumes and Persistent State

A volume-style workflow needs state that survives restarts. smolvm gives you persistent dev environments: create, start, stop, and exec into local VMs whose installed packages and state survive restarts. You do not rebuild the environment each morning; you resume it.

For durability beyond a single machine, a stateful VM packs into a self-contained .smolmachine file, and known-good states can be preserved as .smolcheckpoint snapshots. The artifact boots in under 200 ms on any supported host architecture with no install step and no runtime downloads, which makes "move the whole environment" a copy operation rather than a rebuild.

Host Mounts as Explicit, Reviewable Grants

The guest starts with its own filesystem. A host directory is mounted only when your configuration declares it, and protected host config and log trees are blocked by default. Writable system mounts and HTTP API requests to the host remain blocked unless you allow them.

For development, host-directory mounts come with inotify hot reload, so editing a checkout on your laptop is reflected live inside the VM. For anything untrusted, treat every mount as a capability: grant the narrowest path, prefer read-only, and remove the grant when the run ends.

Because mounts are declared in the Smolfile, the same grant list applies when the workload moves to smol cloud. The cloud runtime uses the same VM model, so a workload you develop locally deploys with the same configuration or as a packaged .smolmachine artifact. Review mounts, network access, and secrets before promoting a configuration to a shared fleet.

Network Configuration: Off by Default, Open by Allowlist

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.

Locally, run smolvm with --net to enable networking, then pass --allow-host for each required host, for example --allow-host registry.npmjs.org. Hostname and CIDR allowlists are supported. In smol cloud, set network.mode in the machine configuration: blocked for no outbound traffic, open for unrestricted egress, or allowCidrs to permit only selected hosts and ranges. For untrusted workloads, blocked or allowCidrs is the recommended posture.

Ports follow the same discipline. 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. If a job needs no egress at all, pre-pull the image while networking is enabled and reuse the host OCI cache with --oci-cache, then run the job fully offline.

The smolvm engine and CLI are open source, so you can read exactly how the boundary is enforced rather than take it on faith.

One Control Surface From Laptop to Cloud

The smol SDK (TypeScript and Python packages) and the smol CLI manage machines in either place: create, start, stop, exec into, and destroy VMs programmatically. An agent harness can spin up a fresh, isolated workspace per task locally, then run the same lifecycle calls against smol cloud when it is time for managed capacity. Teams that prefer to operate their own infrastructure can self-host smolvm on their own servers with the same definitions.

This is the practical answer to the original question: volumes, host mounts, and network config are not three separate tools stitched together. They are sections of one declarative file, applied by one VM model, driven by one interface, everywhere the workload runs.

Frequently Asked Questions

Do I need different configuration files for local and cloud runs?

No. The same Smolfile drives both. smolvm applies it to local microVMs, and smol cloud applies the same VM model to managed persistent VMs. A workload can also travel as a packaged .smolmachine artifact.

How is network access handled in each environment?

Networking is off by default in both. Locally, smolvm's --allow-host flag exposes specific hosts; in smol cloud, allowCidrs restricts egress to approved ranges. Ports are declared in the Smolfile alongside everything else.

Are host directories mounted automatically?

No. The guest starts with its own filesystem, and a host directory is mounted only when your configuration declares it. Protected host config and log trees are blocked by default.

How do I move a fully prepared environment between machines?

Pack the stateful VM into a .smolmachine file. It boots in under 200 ms on any supported host architecture with no install step or runtime downloads.

Conclusion

Sharing a machine definition across environments is a contract problem, not a synchronization problem. Pick a declarative source of truth, keep local-only assumptions out of it, and choose a runtime that offers the same VM model and control surface at every destination. Smol Machines covers the whole path: a Smolfile you check in, smolvm locally and on self-hosted nodes, smol cloud for managed capacity, and portable artifacts for moving prepared environments. If your team is tired of maintaining two or three versions of the same environment, start with Smol Machines and keep one definition instead of three.