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).