armless
pages / Getting started

Getting started

on this page

Quick start#

Native#

cargo build --release
cargo run --release --bin armless-run -- --kernel Image --initrd initrd.cpio --smp 2
cargo run --release --bin armless-run -- --help

armless-run runs Linux kernels (Image, Image.gz, zstd or EFI zboot) and bare-metal binaries (--raw FILE[@ADDR]). Besides --kernel, --initrd, --append, -m MB and --smp N, it takes --fs DIR (a 9p root; --boot-fs boots the kernel under /boot in it), --net with --tunnel [H:]P=URL and --allow-private, --free-page-reporting, --timeout, --save FILE (a snapshot when the timeout ends the run, or with --save-after TEXT once the guest printed TEXT) and --restore FILE, input flags for scripted runs, and --stats / --fallbacks for JIT numbers.

Rust 1.97 or newer is needed (Cranelift, behind the default native-jit feature).

armless-exec runs a Linux program in user mode, with no kernel: a static executable of this host's, or (--fs DIR, a snowglobe site's system/ say) one found in a machine's filesystem:

cargo run --release --bin armless-exec -- ./my-static-binary arg1 arg2
cargo run --release --bin armless-exec -- --fs site/system --keys 'print(6*7)\n' python3
cargo run --release --bin armless-exec -- --cpus 4 --fs site/system duckdb -c 'select 42'
cargo run --release --bin armless-exec -- --stop-after "ready" --save snap ./server
cargo run --release --bin armless-exec -- --restore snap --input "a line for its terminal"

Browser#

Build armless.wasm (see Building) or take the files from a release, then:

<script src="armless.js"></script>
<script>
  const vm = new Armless({
    wasm: "armless.wasm",            // armless-smp.wasm next to it is used for cpus > 1
    memory_mb: 512,
    cpus: 1,
    filesystem: { json: "filesystem.json", baseurl: "filesystem/" },
    initial_state: "state.bin.zst",  // or boot: { kernel, initrd, cmdline }
    network: { tls: "tls.json" },    // the guest's HTTP(S) and WebSockets go out via fetch()
  });
  vm.on("console", (bytes) => term.write(bytes));
  term.onData((text) => vm.console_input(text));
  vm.on("ready", () => vm.console_resize(term.cols, term.rows));
</script>

More than one CPU needs SharedArrayBuffer, so the page must be cross-origin isolated (COOP same-origin with COEP require-corp or credentialless).

In user mode the page runs a program from the filesystem with no kernel, the console being its terminal:

const vm = new Armless({
  wasm: "armless.wasm",
  memory_mb: 512,
  filesystem: { json: "filesystem.json", baseurl: "filesystem/" },
  user: { argv: ["python3"], env: ["PATH=/usr/bin:/bin", "TERM=xterm-256color"], cwd: "/", cols: 80, rows: 24 },
  // or, a snapshot of one: initial_state: "state.bin.zst", user_state: "user.bin"
});
vm.on("stop", ({ reason, code }) => console.log(reason, code)); // "exit", 0

Building#

cargo build --release           # the crate and armless-run
sh build-wasm.sh                # build/armless.wasm (with user mode)
SMP=1 sh build-wasm.sh          # build/armless-smp.wasm

The wasm builds need the wasm32-unknown-unknown target, plus clang and lld for the C zstd decoder in lib/zstd. SMP=1 builds std from source with atomics, so it also needs the rust-src component (rustup component add rust-src). js/armless.js is used as it is. armless.wasm is the cdylib of the armless-user crate, so it has user mode's exports next to the machine's; armless-smp.wasm is armless's alone (user mode runs on one CPU).

Cargo features: native-jit (default; Cranelift), hypervisor (see docs/hypervisor.md) and wasm-api (compiles the wasm export layer natively, to type-check it; armless-user has wasm-api and native-jit of the same names, the latter default-on: default-features = false on armless-user (and on armless, if you depend on it too) links no Cranelift).

this page's source