armless
pages / Native API

Native API

use armless::{native::{Egress, HostOptions, NativeHost}, runner::{self, Runner}, vm::Config};

let (mut vm, clock) = runner::new_vm(Config { memory_size: 512 << 20, cpus: 2, ..Default::default() })?;
vm.board.load_filesystem(&std::fs::read("filesystem.json")?)?;
vm.board.set_tls(&std::fs::read("tls.json")?)?;  // the guest's HTTPS ends in the machine
let host = NativeHost::spawn(vm.board.clone(),
    HostOptions { blobs: Some("filesystem".into()), network: true, egress: Egress::from_env(), tunnels: vec![] },
    Box::new(|event| { /* console output, files read, ... */ }));
let mut runner = Runner::new(vm, clock, false);
runner.load_state(&std::fs::read("state.bin.zst")?)?;
runner.start();
  • Egress::from_env() goes out through the proxy the environment names (HTTPS_PROXY, HTTP_PROXY, ALL_PROXY, NO_PROXY), with TLS checked against the system's roots (SSL_CERT_FILE included). That covers sandboxes whose only way out is a TLS-intercepting proxy. Private and loopback addresses are off limits unless allow_private is set (through a proxy, which resolves names itself, private IP literals and localhost names are refused before it sees them). examples/fetch.rs makes a request this way. ports limits the TCP ports the guest reaches (vec![443]: HTTPS and wss:// only; its DNS is answered inside the machine and isn't affected); deny_all lets nothing out.
  • Board::set_fs_cache is the native counterpart of fs_cache_mb.
  • Board::set_fs_write_limit caps the host memory the guest's file writes hold (its filesystem lives there): past the budget its writes fail with ENOSPC and statfs (df) shows what is left. Counted from when it is set (a fork of a restored machine gets its own count); Board::fs_write_budget says what is used and whether a write was refused. Off by default.
  • runner::new_vm and every Runner restore seed the machine from the host (Board::seed), so a restored guest gets a new VM generation id and Linux reseeds its random generator at once.
  • HostOptions::blob_source serves blobs from anywhere (an archive in memory, say) instead of a directory.

this page's source