bsdkrun.sandbox — io.github.tsirysndr/bsdkrun 0.1.1

The machine lifecycle. A "sandbox" here is just a plain map, e.g. {:id "abc123" :ssh-port 2222} — there is no object, no class. Create one with create!, reconnect with get, or enumerate with list.

Every function below that acts on a machine takes a ref first: a sandbox map, or a bare machine id/name string (see id) — bsdkrun itself resolves a bare id prefix or exact name (core/src/db.rs's find_machine), so (sandbox/stop! "web-1") needs no lookup first. And since every ref-taking function returns either its result or (for lifecycle ops with nothing interesting to return) ref itself, they thread with ->/doto:

(-> (sandbox/get "web-1")
    sandbox/start!
    (sandbox/exec! ["uname" "-a"])
    :stdout)

(doto (sandbox/get "web-1")   ; same vm through every step, vm back at the end
  sandbox/start!
  (sandbox/exec! ["setup.sh"])
  sandbox/stop!)

Mirrors sdk/ruby/lib/bsdkrun/sandbox.rb.

connect-network! clj

(connect-network! ref network)

Join or switch this machine to a global network. Applies on next start!.

create! clj

(create! opts)

Boot a new microVM and return {:id ... :ssh-port ...} (:ssh-port is nil unless the boot banner reported one, which only BSD guests do).

opts is a create-options map discriminated on :os — see bsdkrun.args/build-create-args.

Throws errors/command-failed if boot fails or no machine id is printed.

disconnect-network! clj

(disconnect-network! ref)

Detach this machine from its network. Applies on next start!.

exec! clj

(exec! ref command)

(exec! ref
       command
       {:keys [args env tty stdin cwd throw-on-error log-level]
        :or {args [] env {} tty false throw-on-error false log-level 0}})

Run a command in the guest through its exec agent.

command may be a vector (argv, no shell parsing) or a bare string program name; with a string, :args supplies its arguments.

opts: :args arguments when command is a bare string :env environment variables map (-e K=V) :tty allocate a pseudo-TTY in the guest (-t) :stdin data piped to the command's stdin :cwd working directory, emulated via sh -c 'cd ...' :throw-on-error throw errors/command-failed on a non-zero exit :log-level per-command bsdkrun log level

Returns {:stdout ... :stderr ... :exit-code ... :command "..."}.

get clj

(get ref)

Reconnect to an existing machine by id (a unique prefix is enough) or by exact name. ref is a sandbox map or a bare id/name string (see id).

Throws errors/sandbox-not-found if nothing matches.

id clj

(id ref)

The machine id/name to hand the CLI for ref — a sandbox map's :id, or a bare id/name string, unchanged. Every function below that acts on a machine accepts either.

list clj

(list)

(list opts)

List machines. {:all true} includes exited ones (default running only).

Returns a vector of sandbox-info maps (see bsdkrun.types/sandbox-info-from-row).

logs clj

(logs ref)

(logs ref {:keys [boot]})

Read the machine's console log. {:boot true} shows bsdkrun's own boot log instead of the console.

remove! clj

(remove! ref)

(remove! ref {:keys [force]})

Remove the machine and its state. {:force true} stops it first if running.

run-command! clj

(run-command! ref command)

(run-command! ref command args)

(run-command! ref command args opts)

Vercel-Sandbox-style alias for exec!: a program plus its args.

running? clj

(running? ref)

Whether the machine is currently running.

shell! clj

(shell! ref)

Attach an interactive shell to the machine (inherits the terminal). Returns true if the shell exited zero.

ssh-setup! clj

(ssh-setup! ref)

(ssh-setup! ref {:keys [user key]})

Install SSH keys in the guest via the agent (ssh setup). With no keys, the CLI installs your local ~/.ssh/*.pub.

opts: :user (target user, default root), :key (a literal key or .pub path, or a vector of them).

start! clj

(start! ref)

Restart a stopped machine in place (same id, disk/rootfs). Boots detached.

status clj

(status ref)

This machine's current status row, or nil if it's gone. ref may be a sandbox map or a bare id/name string.

stop! clj

(stop! ref)

Stop the machine. BSD guests are cleanly powered off; Linux is SIGTERM'd.

tailscale-up! clj

(tailscale-up! ref)

(tailscale-up! ref {:keys [authkey hostname args]})

Put the guest on your tailnet (tailscale setup).

opts: :authkey (tailnet auth key, sent as TS_AUTHKEY), :hostname (machine name on the tailnet), :args (extra args passed through to tailscale up).

update! clj

(update! ref)

(update! ref {:keys [cpus mem]})

Change the recorded vCPU / RAM. Applies on the next start!.

with-network clj

(with-network opts network)

Join a create-options map's guest to a global network (--network) — merges into :net rather than replacing it, so it composes with other :net keys (e.g. :ports, :mac) already set on opts. Composes with -> before create!:

(-> {:os :linux :image "alpine"}
    (sandbox/with-network "devnet")
    sandbox/create!)

To move an existing machine between networks, use connect-network! instead (applies on its next start!).

with-volume clj

(with-volume opts volume)

Set the persistent volume a machine's rootfs is cloned onto/reused from (-v/--volume) on a create-options map — :volume is a create-time choice, fixed for the machine's lifetime, so this composes with -> before create!, not after it:

(-> {:os :linux :image "alpine"}
    (sandbox/with-volume "web")
    sandbox/create!)