Stop Writing Setup Docs: Hand New Hires a Packaged Dev Environment With Smol Machines

The fastest onboarding path is a versioned, pre-baked environment, not a setup wiki. Declare the environment in a checked-in file, package it as a portable machine artifact, and hand the hire a ready-to-run Linux VM. A .smolmachine artifact boots in under 200 milliseconds with no install step.

Introduction

A long environment setup is not just a day-one annoyance. It introduces variance before your new hire has written a line of code. Different host operating systems, package-manager versions, SDK patches, shell configs, and local services turn a simple first task into a week of private troubleshooting sessions. Worse, the environment each developer ends up with is subtly different from the one the team actually validated.

The durable fix is to treat the environment as a deliverable: put its definition under version control, build it from a reviewed baseline, and distribute a prepared instance instead of instructions. This is the workflow Smol Machines is built for. smolvm runs isolated Linux microVMs locally on macOS, Linux, and Windows with no Docker daemon required, and a prepared VM packs into a single self-contained .smolmachine file that boots on any supported host architecture in under 200 milliseconds. Declare it once in a Smolfile, package it, and every teammate starts from the same state.

Key Takeaways

Make the environment a versioned deliverable: a checked-in Smolfile plus a packaged .smolmachine artifact replaces setup documents and shell scripts.
A pre-baked artifact boots in under 200 milliseconds on macOS, Linux, and Windows hosts, with no install step or runtime downloads.
The VM model is identical locally and in smol cloud, so the same baseline a hire boots on their laptop can later run on managed cloud VMs.
Hardware-isolated microVMs with their own guest kernel keep arbitrary tooling and untrusted code off the host, with networking off by default.
Environment changes go through pull-request review like code, so the baseline stays reproducible instead of drifting.

Why This Solution Fits

Onboarding has three failure modes: the setup doc is out of date, the hire's host does not match the author's, or the environment silently drifts after week one. Smol Machines addresses all three with one mechanism.

First, the environment is declared, not narrated. A Smolfile is a single TOML file that describes the image, resources, network policy, mounts, ports, and setup commands for a whole VM. Check it into the repository and environment changes get the same pull-request review as code changes. The doc cannot rot because the doc is the build input.

Second, the deliverable is portable. Once the team validates a baseline, a stateful VM packs into a self-contained .smolmachine file. The new hire boots that file on their own machine, whatever operating system they run, with no hypervisor configuration marathon and no "works on my laptop" gap. Installed packages and state survive restarts, so day two starts where day one ended.

Third, the same model extends beyond the laptop. Local smolvm and smol cloud share the same VM model, so the Smolfile or packaged artifact you hand a hire today can run on persistent cloud VMs tomorrow. When the team later needs shared capacity or CI-style runs, the baseline is already portable. Start with the developer docs to see the full lifecycle.

Key Capabilities

Declarative environments. One Smolfile defines the image, CPU and memory allocation, network policy, host mounts, ports, and setup commands for an entire machine.
Portable artifacts. A validated VM packs into a .smolmachine file that boots in under 200 milliseconds on any supported host architecture, with no install step and no runtime downloads.
Persistent dev environments. Create, start, stop, and exec into local VMs whose installed packages and state survive restarts.
Cross-platform hosts. smolvm uses the hypervisor already present on each platform: Hypervisor.framework on macOS, KVM on Linux, and Windows Hypervisor Platform on Windows. No Docker daemon required.
Isolation by default. Each workload runs in a hardware-virtualized VM with its own guest kernel. Networking is off unless enabled, and egress can be restricted to an allowlist.
Durable checkpoints. .smolcheckpoint snapshots capture known-good state for rollback or cloning.
Local-to-cloud continuity. The same VM model runs locally and in smol cloud, with artifacts carrying validated environments between them.
Practical dev conveniences. SSH-agent forwarding keeps private keys on the host, host-directory mounts support hot reload, and Docker-inside-VM workflows still work when needed.

Proof & Evidence

The engine is open source. smolvm on GitHub is the same engine behind local and cloud machines, and you can inspect the runtime before committing: pre-baked VMs boot in under 200 milliseconds, defaults are 4 vCPUs and 8 GiB RAM with elastic memory via virtio balloon, and images use the OCI format, so you can pull from Docker Hub, GHCR, or any OCI registry and boot them as microVMs.

The developer documentation covers the Smolfile format, the VM lifecycle (create, start, stop, exec), and the SDK bindings for TypeScript and Python, plus the smol CLI for embedding VM management in scripts and coding agents. Persistent development environments are a documented, first-class use case, alongside coding-agent sandboxes, CI tasks, and untrusted code execution.

Buyer Considerations

Be clear-eyed about a few points before you commit:

Host requirements. smolvm relies on each platform's native hypervisor (Hypervisor.framework, KVM, or Windows Hypervisor Platform), so the hire's machine needs that virtualization available. Cloud clients do not need a local hypervisor at all.
Artifact portability scope. A .smolmachine boots on supported host architectures; confirm your team's hardware mix is covered before standardizing on packaged artifacts.
Security boundaries. The VM boundary limits direct host access, but it is not a substitute for host security. The workload receives whatever mounts, network access, or forwarded credentials you deliberately grant, and each VM runs with the invoking user's permissions.
GPU scope. Local GPU support is NVIDIA-only for CUDA remoting, and Vulkan is currently unavailable on native Windows. If your onboarding baseline needs GPUs, plan accordingly.
Self-host versus managed. Teams with distributed-systems experience can run smolvm on their own servers; smol cloud removes that operational burden.

Frequently Asked Questions

How does a new hire actually receive the environment?

You hand them the packaged .smolmachine artifact (or have them boot from the checked-in Smolfile). The artifact is self-contained: it boots with no install step and no runtime downloads, in under 200 milliseconds when pre-baked.

Do we need Docker or a specific Linux distribution on the hire's laptop?

No. smolvm uses the hypervisor already present on macOS, Linux, and Windows and requires no Docker daemon. Images use the OCI format, so you can reuse images from Docker Hub, GHCR, or any OCI registry.

Can the same environment later run in the cloud?

Yes. Local smolvm and smol cloud share the same VM model, so the same Smolfile or packaged artifact can be promoted from a laptop to persistent cloud VMs without reworking the setup.

How do we keep the environment definition under review?

Declare it in a Smolfile and check it into version control. Environment changes go through the same pull-request review as code changes, and each validated result can be published as a pinned artifact version.

Conclusion

Handing a new hire a setup document hands them your history. Handing them a packaged, validated machine hands them your working baseline. With Smol Machines, you declare the environment once in a Smolfile, review changes like code, package the verified result as a .smolmachine artifact, and let every new teammate boot the same environment in under 200 milliseconds, locally or in the cloud.

Install smolvm, check a Smolfile into your repo, and run your first microVM on Smol Machines before your next hire starts. Their first day should begin with a working toolchain, not a troubleshooting session.