Smol Machines

https://smolmachines.com/docs
Admin
Smol Machines is a CLI tool that enables running custom Linux virtual machines locally with...
Tokens:1,473
Snippets:19
Trust Score:4.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Declare VM Environments with Smolfile

Source: https://smolmachines.com

Defines reproducible VM configurations using a TOML file named 'Smolfile'. This example shows creating and starting a VM based on the configurations in the Smolfile.

```toml
# Smolfile
# image = "python:3.12-alpine"
# net = true
# [network]
# allow_hosts = ["api.stripe.com", "db.example.com"]
# [dev]
# init = ["pip install -r requirements.txt"]
# volumes = ["./src:/app"]
# [auth]
# ssh_agent = true
```

```bash
smolvm machine create myvm -s Smolfile
smolvm machine start --name myvm
```

--------------------------------

### Manage Persistent Development VMs

Source: https://smolmachines.com

Demonstrates the lifecycle of a persistent development VM, including creation, starting, executing commands, and stopping. Installed packages persist across restarts.

```bash
smolvm machine create --net myvm
smolvm machine start --name myvm
smolvm machine exec --name myvm -- apk add sl
smolvm machine exec --name myvm -it -- /bin/sh
# inside: sl, ls, uname -a — type 'exit' to leave
smolvm machine stop --name myvm
```

--------------------------------

### Install smol machines CLI

Source: https://smolmachines.com

Installs the smol machines CLI tool on macOS and Linux systems. Run this script to get started.

```bash
# install (macOS + Linux)
curl -sSL https://smolmachines.com/install.sh | bash
```

```bash
# for coding agents — install + discover all commands
curl -sSL https://smolmachines.com/install.sh | bash && smolvm --help
```

--------------------------------

### Start Interactive Shell in VM

Source: https://smolmachines.com

Launches an interactive shell session inside a temporary Linux VM. Use this for exploring or running multiple commands interactively.

```bash
# interactive shell
smolvm machine run --net -it --image alpine -- /bin/sh
# inside the VM: apk add sl && sl && exit
```

--------------------------------

### Pack Workload into Portable Executable

Source: https://smolmachines.com

Creates a self-contained, portable executable from a specified VM image. The resulting binary includes all dependencies and boots quickly.

```bash
smolvm pack create --image python:3.12-alpine -o ./python312
./python312 run -- python3 --version
# Python 3.12.x — isolated, no pyenv/venv/conda needed
```

--------------------------------

### Use Git and SSH Without Exposing Keys

Source: https://smolmachines.com

Enables forwarding of the host's SSH agent into a VM, allowing Git operations on private repositories without the private keys ever entering the guest. Requires an SSH agent running on the host.

```bash
smolvm machine run --ssh-agent --net --image alpine -- sh -c "apk add -q openssh-client && ssh-add -l"
# lists your host keys, but they can't be extracted from inside the VM
```

```bash
smolvm machine exec --name myvm -- git clone git@github.com:org/private-repo.git
```

--------------------------------

### Run Command in Ephemeral VM

Source: https://smolmachines.com

Executes a command within a temporary, isolated Linux VM. The VM is automatically cleaned up after the command finishes.

```bash
# run a command in an ephemeral VM (cleaned up after exit)
smolvm machine run --net --image alpine -- sh -c "echo 'Hello world from a microVM' && uname -a"
```

--------------------------------

### Sandbox Untrusted Code - Network Isolation

Source: https://smolmachines.com

Demonstrates network isolation by attempting to ping an external host from a VM where networking is disabled by default. This ensures untrusted code cannot access the network.

```bash
# network is off by default — untrusted code can't phone home
smolvm machine run --image alpine -- ping -c 1 1.1.1.1
# fails — no network access
```

--------------------------------

### Sandbox Untrusted Code - Allow Specific Hosts

Source: https://smolmachines.com

Configures network access for a VM to only allow connections to specified hosts. This snippet shows a successful connection to an allowed host and a failed connection to a disallowed host.

```bash
# lock down egress — only allow specific hosts
smolvm machine run --net --image alpine --allow-host registry.npmjs.org -- wget -q -O /dev/null https://registry.npmjs.org
# works — allowed host
```

```bash
smolvm machine run --net --image alpine --allow-host registry.npmjs.org -- wget -q -O /dev/null https://google.com
# fails — not in allow list
```

--------------------------------

### Uninstall smol machines CLI

Source: https://smolmachines.com

Removes the smol machines CLI tool from your system. Use this command to uninstall.

```bash
# uninstall
curl -sSL https://smolmachines.com/install.sh | bash -s -- --uninstall
```
Tokens:
Raw