cvisor (cvisor v0.3.0)
View SourceSummary
Functions
Run a shell command in the sandbox, blocking until it exits. Returns the captured stdout and stderr as binaries, and the guest's exit code (shell convention: status, or 128+signo when killed).
Like run/1, but SIGKILLs the guest after TimeoutMs milliseconds (0 = no limit). A timed-out run reports exit code 137.
Start a streaming session for Cmd, draining stdout/stderr in the calling process until the command exits. Equivalent to run_streaming(Cmd, []).
Run Cmd as a non-PTY streaming session, invoking the supplied callbacks with each chunk of output as it arrives. Options
Restore a cache entry (saved under Key) into SandboxPath in the session's sandbox overlay, with the default backend (disk) and "gzip" format. Equivalent to session_cache_restore(S, SandboxPath, Key, <<>>, <<"gzip">>).
Restore a cache entry (saved under Key) into SandboxPath in the session's sandbox overlay.
Save SandboxPath from the session's sandbox overlay to the cache under Key, with the default backend (disk) and "gzip" format. Equivalent to session_cache_save(S, SandboxPath, Key, <<>>, <<"gzip">>).
Save SandboxPath (a file or directory) from the session's sandbox overlay to the cache under Key.
Copy a host file or directory tree at HostPath into the session's sandbox filesystem overlay at GuestPath. Like session_write_file/3, the copy targets the session's own sandbox (a stable uid held for the session's lifetime), so the copied content is visible to later commands run on the SAME session. Accepts either a single file or a whole directory. Returns ok, or {error, Reason} where Reason is an errno atom such as enoent or eacces.
Copy a file or directory tree at GuestPath out of the session's sandbox filesystem overlay to the host at HostPath (the guest's view, including files produced by earlier commands on this session). Returns ok, or {error, Reason} (an errno atom).
Free the session and its sandbox. Idempotent; also runs automatically when the handle is garbage-collected.
Send SIGKILL to the session's command.
Read Path from the session's sandbox filesystem overlay (the guest's view, including files written by earlier commands on this session or by session_write_file/3). Returns the file's bytes as a binary, or <<>> for an empty or missing file.
Drain and return any new stderr bytes (<<>> if none). Empty for PTY sessions, whose streams are merged into stdout.
Drain and return any new stdout bytes (<<>> if none). For a PTY session this returns the merged output stream.
Resize the session's PTY window to Rows by Cols.
Start a session for Cmd. Pty is 0 for a plain command (separate stdout/stderr) or 1 for an interactive PTY shell (merged output, stdin writable). Returns an opaque session handle.
Non-blocking check for session completion. Returns {done, ExitCode} once the command has exited, or running otherwise.
Block until the session exits and return its exit code. Runs on a dirty I/O scheduler so it does not stall the VM.
Write Data to the session's stdin (PTY sessions only). Returns the number of bytes written, or -1 on error.
Write Data to Path inside the session's sandbox filesystem overlay. Because the write targets the session's own sandbox (a stable uid held for the session's lifetime), the file is visible to later commands run on the SAME session (e.g. via session_write/2 to a PTY shell). Returns ok, or {error, Reason} where Reason is an errno atom such as eacces or enospc.
Allow or deny inbound TCP servers (binding a fixed port, listen, and accept) for sandboxes created by subsequent runs and sessions. The default is to deny.
Allow or deny outbound INET/INET6 networking for sandboxes created by subsequent runs. The default is to allow.
Set a guest environment variable, layered over the default PATH/HOME, for sandboxes created by subsequent runs and sessions. Setting a key that is already present overrides its value. Key and Value may be binaries or strings.
Set guest cgroup resource limits for sandboxes created by subsequent runs and sessions. MemoryMax is the memory ceiling in bytes, PidsMax the maximum number of processes/threads, and CpuPercent the CPU quota as a percent of one core (50 = half a core, 200 = two cores). Any argument of 0 leaves that limit unset. Limits require a writable cgroup v2 hierarchy; where one is unavailable they gracefully no-op.
Start an interactive PTY shell (/bin/sh -i). Equivalent to shell([]).
Start an interactive PTY shell session and return its handle. Write to it with session_write/2, resize with session_resize/3, and wait for exit with session_wait/1. Options
Types
-type session() :: reference().
Functions
Run a shell command in the sandbox, blocking until it exits. Returns the captured stdout and stderr as binaries, and the guest's exit code (shell convention: status, or 128+signo when killed).
-spec run(binary() | string(), non_neg_integer()) -> {ok, binary(), binary(), integer()} | {error, atom()}.
Like run/1, but SIGKILLs the guest after TimeoutMs milliseconds (0 = no limit). A timed-out run reports exit code 137.
Start a streaming session for Cmd, draining stdout/stderr in the calling process until the command exits. Equivalent to run_streaming(Cmd, []).
Run Cmd as a non-PTY streaming session, invoking the supplied callbacks with each chunk of output as it arrives. Options:
{on_stdout, fun((binary()) -> any())}— called per non-empty stdout chunk.{on_stderr, fun((binary()) -> any())}— called per non-empty stderr chunk.{poll_ms, integer()}— poll interval in ms (default 15).
Blocks the calling process until the command exits, performs a final drain, frees the session, and returns the exit code.
Restore a cache entry (saved under Key) into SandboxPath in the session's sandbox overlay, with the default backend (disk) and "gzip" format. Equivalent to session_cache_restore(S, SandboxPath, Key, <<>>, <<"gzip">>).
-spec session_cache_restore(session(), binary(), binary(), binary(), binary()) -> ok | {error, atom()}.
Restore a cache entry (saved under Key) into SandboxPath in the session's sandbox overlay.
Backend defaults to disk when the empty binary <<>> is given; Format ("gzip"/"estargz"/"none") must match the format used to save, and defaults to "gzip" in the /3 form. As with session_cache_save/5, the bundled libcvisor supports only the disk backend and the gzip/estargz/none formats, and save/restore are session-scoped. Returns ok, or {error, Reason} (an errno atom).
Save SandboxPath from the session's sandbox overlay to the cache under Key, with the default backend (disk) and "gzip" format. Equivalent to session_cache_save(S, SandboxPath, Key, <<>>, <<"gzip">>).
-spec session_cache_save(session(), binary(), binary(), binary(), binary()) -> ok | {error, atom()}.
Save SandboxPath (a file or directory) from the session's sandbox overlay to the cache under Key.
Backend selects where the cache lives; the empty binary <<>> means the default disk backend. Format selects the archive format ("gzip", "estargz", or "none"), defaulting to "gzip" in the /3 form.
Note: the bundled libcvisor is built with the disk backend and the gzip/estargz/none formats only. Other backends (e.g. s3) or formats (e.g. zstd) require a libcvisor built with those features.
Because the cache is keyed by the sandbox's uid overlay, save/restore are only meaningful within a single session (whose sandbox and uid are stable). Returns ok, or {error, Reason} (an errno atom).
Copy a host file or directory tree at HostPath into the session's sandbox filesystem overlay at GuestPath. Like session_write_file/3, the copy targets the session's own sandbox (a stable uid held for the session's lifetime), so the copied content is visible to later commands run on the SAME session. Accepts either a single file or a whole directory. Returns ok, or {error, Reason} where Reason is an errno atom such as enoent or eacces.
Copy a file or directory tree at GuestPath out of the session's sandbox filesystem overlay to the host at HostPath (the guest's view, including files produced by earlier commands on this session). Returns ok, or {error, Reason} (an errno atom).
-spec session_free(session()) -> ok.
Free the session and its sandbox. Idempotent; also runs automatically when the handle is garbage-collected.
-spec session_kill(session()) -> ok.
Send SIGKILL to the session's command.
Read Path from the session's sandbox filesystem overlay (the guest's view, including files written by earlier commands on this session or by session_write_file/3). Returns the file's bytes as a binary, or <<>> for an empty or missing file.
Drain and return any new stderr bytes (<<>> if none). Empty for PTY sessions, whose streams are merged into stdout.
Drain and return any new stdout bytes (<<>> if none). For a PTY session this returns the merged output stream.
-spec session_resize(session(), non_neg_integer(), non_neg_integer()) -> ok.
Resize the session's PTY window to Rows by Cols.
Start a session for Cmd. Pty is 0 for a plain command (separate stdout/stderr) or 1 for an interactive PTY shell (merged output, stdin writable). Returns an opaque session handle.
Non-blocking check for session completion. Returns {done, ExitCode} once the command has exited, or running otherwise.
Block until the session exits and return its exit code. Runs on a dirty I/O scheduler so it does not stall the VM.
Write Data to the session's stdin (PTY sessions only). Returns the number of bytes written, or -1 on error.
Write Data to Path inside the session's sandbox filesystem overlay. Because the write targets the session's own sandbox (a stable uid held for the session's lifetime), the file is visible to later commands run on the SAME session (e.g. via session_write/2 to a PTY shell). Returns ok, or {error, Reason} where Reason is an errno atom such as eacces or enospc.
Note: this operates on the session's sandbox, not a global one. The top-level run/1 and run_streaming/2 each create a fresh sandbox with a new uid, so files seeded here are NOT visible to those calls — only to the session that owns them.
-spec set_allow_listen(boolean()) -> ok.
Allow or deny inbound TCP servers (binding a fixed port, listen, and accept) for sandboxes created by subsequent runs and sessions. The default is to deny.
-spec set_allow_network(boolean()) -> ok.
Allow or deny outbound INET/INET6 networking for sandboxes created by subsequent runs. The default is to allow.
Set a guest environment variable, layered over the default PATH/HOME, for sandboxes created by subsequent runs and sessions. Setting a key that is already present overrides its value. Key and Value may be binaries or strings.
-spec set_limits(_Sandbox, non_neg_integer(), non_neg_integer(), non_neg_integer()) -> ok.
Set guest cgroup resource limits for sandboxes created by subsequent runs and sessions. MemoryMax is the memory ceiling in bytes, PidsMax the maximum number of processes/threads, and CpuPercent the CPU quota as a percent of one core (50 = half a core, 200 = two cores). Any argument of 0 leaves that limit unset. Limits require a writable cgroup v2 hierarchy; where one is unavailable they gracefully no-op.
Start an interactive PTY shell (/bin/sh -i). Equivalent to shell([]).
Start an interactive PTY shell session and return its handle. Write to it with session_write/2, resize with session_resize/3, and wait for exit with session_wait/1. Options:
{on_output, fun((binary()) -> any())}— if given, a poller process is spawned that drains the merged PTY output and calls the fun with each chunk until the shell exits (with a final drain).{poll_ms, integer()}— poll interval in ms (default 15).
The caller is responsible for calling session_free/1 when done.