SmolBox

Run Python, JavaScript and other programs in disposable or retained Linux VMs from Elixir.

SmolBox is a client and supervised execution runtime for smolvm. smolvm runs the machines on your hosts; SmolBox tracks command identity, results and cleanup under your application's supervision tree. You install the workers and prepare the images containing the languages and dependencies your programs need.

Start here

You need Elixir 1.18 or later and smolvm 1.22.0 on Linux x86_64 with KVM or macOS Apple Silicon. Worker installation is included in the walkthrough; the Elixir dependency does not install smolvm.

Choose one path to your first execution:

Livebook: download the notebook, import it into a local Livebook and follow its setup instructions. No Mix project or database is needed. New to Livebook? See installation and import instructions.
Mix application: follow Getting started to install the dependencies, prepare an image, start a separate worker, run Python and confirm output collection and VM cleanup.

See Supported platforms for host prerequisites. For an existing application, use Upgrading SmolBox.

Why use SmolBox?

Executing a command is only part of integrating a worker. Your application also needs to handle duplicate requests, lost responses, restarts and leftover VMs.

Reuse a request's identity. Submitting the same scoped ID and specification returns its existing handle. A different specification under that ID is rejected.
Recover after a restart. A durable store preserves execution records for observation and cleanup. A command that may have run remains unknown when its result is lost; SmolBox does not automatically run it again.
Track results and cleanup separately. Input staging, output collection, cancellation and VM deletion have their own states. Command success does not imply that its machine has already been deleted.

What execution looks like

This fragment illustrates submitting a command to an already configured runtime. It assumes SmolBoxDemo.Runtime is running and artifact and profile are available in the same code context. For a complete runnable example, use Getting started or the notebook. Those walkthroughs stop their demo supervisor after cleanup, so this fragment is not a next step to paste into IEx after finishing them.

alias SmolBox.{Command, ExecutionSpec}

argv = ["python", "-c", "print(6 * 7)"]
{:ok, command} = Command.new(argv, timeout_secs: 10)

{:ok, spec} =
  ExecutionSpec.new(
    scope: "demo",
    id: "answer-001",
    artifact: Map.drop(artifact, ["path"]),
    profile: profile,
    command: command
  )

{:ok, handle} = SmolBox.submit(SmolBoxDemo.Runtime, spec)
{:ok, ^handle} = SmolBox.submit(SmolBoxDemo.Runtime, spec)

{:ok, execution} =
  SmolBox.await(SmolBoxDemo.Runtime, handle, 90_000)

%{state: :completed, result: result} = execution
%{exit_code: 0, stdout: stdout} = result

IO.write(stdout)
# Prints: 42

The second submission reuses the execution. The specification uses the image identity from artifact and the registered profile created during setup. Handle errors, nonzero exits and unknown outcomes in application code. An await/3 timeout does not cancel the command. Inspect cleanup with SmolBox.fetch/3; see Troubleshooting.

Choose your next step

What you want to do	Guide
Add supervision, profiles and durable storage	Host integration
Keep a machine and its files across commands	Persistent machines
Manage the lifecycle yourself	Low-level client
Use registry images or prepared artifacts	Images and registry artifacts
Run longer commands, background processes or a terminal	Long commands · Terminals
Transfer files or retain data after machine deletion	Guest files · Local volumes
Reuse prepared disk or memory state	Exports · Checkpoints · Branches
Configure networking or expose a guest service	Network access · Port mappings
Recover from failures or prepare maintenance	Recovery · Draining
Upgrade an existing deployment	Upgrading SmolBox

The community workspace app provides a Phoenix walkthrough using its pinned SmolBox 0.3.0 dependency. It includes persistent machines, commands, a terminal and PostgreSQL recovery. The engineering blog has longer worked examples.

Deployment and support

SmolBox relies on smolvm for VM isolation. Your deployment controls worker access, image approval, host resource limits, networking, credentials and storage. Admission reservations do not enforce host quotas. Offline networking is the default, and retained machines remain until explicitly deleted. Read Deployment boundaries before operating workers.

Supported use remains :development. Supported platforms describes usable combinations and feature limits. Testing reports collects recorded worker checks, performance measurements and historical results, with their original versions and limits.

Contributing

Source: hfiguera/smolbox. Toolchain pins are in .tool-versions. Run mix ci for deterministic checks without a real worker. Build the documentation with MIX_ENV=dev mix docs --warnings-as-errors, then run MIX_ENV=dev mix smolbox.ci.docs to check local links and fragments. Live worker checks are a separate operation described in the repository's CI guide.