Use Slicer

Use Slicer — Launch Linux MicroVMs

Slicer gives you instant Linux microVMs powered by Firecracker. Use it when you need:

• A real Linux environment with systemd, Internet access and SSH preinstalled(especially from macOS)
• Sandboxed builds, CI, or E2E tests
• Docker/container workflows with port forwarding
• Isolated environments for untrusted or destructive operations
• Kubernetes (k3s) clusters for testing
• GPU/PCI passthrough workloads (via cloud-hypervisor backend)
• Automated code review pipelines in ephemeral microVMs
• Running coding agents in isolated microVMs (Amp, Claude Code, Codex, OpenCode, GitHub Copilot CLI) then copying out the outcome - code, files, reports, binaries, images, etc.

VMs boot in 1–3 seconds, have full systemd, internet access, and SSH pre-installed.

Docs: https://docs.slicervm.com Go SDK: https://github.com/slicervm/sdk (github.com/slicervm/sdk)

On macOS, the CLI drives Slicer for Mac — a persistent Linux VM plus an sbox host group for sandboxes. See [references/macos.md](references/macos.md).

Reference files

Deeper material is split into reference files — read the relevant one when a task calls for it:

• [references/macos.md](references/macos.md) — Slicer for Mac (slicer-mac)
• [references/daemon-setup.md](references/daemon-setup.md) — generate a config and run your own daemon
• [references/workflows.md](references/workflows.md) — worked recipes (E2E, Docker, builds, k3s, DB, SSH)
• [references/custom-images.md](references/custom-images.md) — custom rootfs images and userdata
• [references/bg-exec.md](references/bg-exec.md) — background exec detail
• [references/interactive-tui.md](references/interactive-tui.md) — driving interactive TUIs and coding agents (guest tmux via exec, or host tmux + vm shell)
• [references/networking.md](references/networking.md) — bridge, isolated, and macvtap (LAN-direct) networking
• [references/agent-sandboxes.md](references/agent-sandboxes.md) — coding-agent sandbox detail

Companion skills: use-slicer-worktrees (git worktrees in a VM), use-slicer-proxy (filtered egress + secret injection).

Prerequisites — You Need a Running Daemon

Slicer is not a SaaS — it requires a running daemon that manages VMs.

Deterministic Workflow (Default)

For agent tasks that can create infrastructure, use this default pattern:

1. Reuse the session VM when already known (for example, because the same workflow tagged VM was created earlier in this run). Otherwise create a new VM and tag it.
2. Track and pass the session VM name forward (instead of switching to an arbitrary existing VM) so subsequent commands in the same session stay on the same instance.
3. Tag VMs so they are identifiable later, for example workflow=.
4. Run in-VM commands with native slicer vm operations (exec, bg exec, cp, shell).

• Use slicer vm exec for short, atomic commands.
• Use slicer vm bg exec for long-running processes (dev servers, builds) that should survive client disconnect — check back with bg logs, bg wait, and clean up with bg kill + bg remove.
• Use slicer vm shell for long sessions or multiple related commands (interactive PTY).

1. Prefer native Slicer commands over SSH even when SSH is available.

Example:

WORKFLOW=ci-$(date +%Y%m%d-%H%M%S)
# Reuse SESSION_VM if already set for this run, else create once and record it.
if [ -n "${SLICER_SESSION_VM:-}" ]; then
  VM_NAME="$SLICER_SESSION_VM"
else
  VM_NAME=$(slicer vm add sbox --tag "workflow=$WORKFLOW" | awk '/Hostname:/ {print $2; exit}')
  slicer vm ready "$VM_NAME"
  export SLICER_SESSION_VM="$VM_NAME"
fi

# then use returned hostname in subsequent commands:
slicer vm exec "$VM_NAME" --uid 1000 -- "uname -a"
slicer vm cp ./local.txt "$VM_NAME":/tmp/local.txt --uid 1000
# for longer interactive work, open a shell session instead of repeating many one-off execs:
slicer vm shell "$VM_NAME" --uid 1000

# use exec for deterministic one-liners; use shell for ongoing interactive workflows

Connecting to a daemon

macOS — slicer-mac. If slicer-mac is installed the daemon is already running and the socket auto-detects — no flags needed. Launch sandboxes into the sbox host group. See [references/macos.md](references/macos.md).

Slicer Box — hosted. A managed instance included with Slicer Home Edition — one persistent VM (2 vCPU, 4GB RAM, 10GB disk) over HTTPS:

export SLICER_URL=https://box.slicervm.com
export SLICER_TOKEN_FILE=~/.slicer/gh-access-token   # a GitHub personal access token

You get one VM to recycle; its disk persists between sessions (installed packages, files, services). Factory-reset by slicer vm delete VM_NAME then slicer vm launch + slicer vm ready.

Existing Linux daemon. Connect to a daemon already running locally or on the LAN. Ask the user for the URL and token path — don't guess.

# Local unix socket (no auth; may need sudo to read the socket)
export SLICER_URL=/path/to/slicer.sock

# Local or remote TCP
export SLICER_URL=http://127.0.0.1:8080
export SLICER_TOKEN_FILE=/var/lib/slicer/auth/token   # may need sudo to read
# or pass the value directly:
export SLICER_TOKEN=$(sudo cat /var/lib/slicer/auth/token)

Check for a running daemon with ps aux | grep -E "slicer|firecracker" | grep -v grep. If the user supplies SLICER_TOKEN / SLICER_TOKEN_FILE or a specific endpoint, use those exactly and do not infer defaults.

No daemon running? To generate a config and start your own — locally or over SSH — see [references/daemon-setup.md](references/daemon-setup.md).

Verify connectivity

slicer info --url "$SLICER_URL" --token-file "$SLICER_TOKEN_FILE"

Every slicer vm subcommand accepts --url and --token-file (or --token).

---

CLI shortcuts you should surface

Slicer exposes a few top-level shortcuts for common VM operations (not for every slicer vm ... subcommand). Prefer showing these when they match what the user asked for:

• slicer ls is a shortcut for slicer vm list (and slicer vm list itself has aliases ls/l)
• slicer shell is a shortcut for slicer vm shell
• slicer cp is a shortcut for slicer vm cp
• slicer bg is a shortcut for slicer vm bg (so slicer bg exec, slicer bg logs, etc. all work)

The slicer vm command group itself also has aliases: slicer vm == slicer v.

---

Working with VMs

List VMs and host groups

slicer vm list --url "$SLICER_URL" --token-file "$SLICER_TOKEN_FILE"
slicer vm group --url "$SLICER_URL" --token-file "$SLICER_TOKEN_FILE"

Use --json for machine-readable output.

Create a VM

slicer vm add HOSTGROUP --url "$SLICER_URL" --token-file "$SLICER_TOKEN_FILE"

The hostgroup argument is optional when only one host group is configured — the SDK resolves it automatically. When there are multiple host groups you must specify one explicitly.

If SSH access is needed, configure key material at launch time:

• for local keys: pass a real public key string via --ssh-key
• for GitHub key import: pass via --import-user USERNAME

Use slicer vm add --help first to verify current flag names and supported auth options before constructing the launch command.

slicer vm add --help

The hostname is printed on creation (e.g. demo-3). Key flags:

| Flag | Purpose | |------|---------| | --cpus N | Override vCPU count | | --ram-gb N | Override RAM (also --ram-mb, --ram-bytes) | | --userdata '#!/bin/bash\n...' | Bootstrap script | | --userdata-file ./setup.sh | Bootstrap from file | | --ssh-key "ssh-ed25519 ..." | Inject SSH public key | | --import-user USERNAME | Import SSH keys from GitHub user | | --shell | Open shell immediately after boot | | --tag env=ci | Metadata tags | | --secrets secret1,secret2 | Allow access to named secrets | | --persistent | Keep VM state across daemon restarts/shutdowns (default true); pass --persistent=false for ephemeral |

Important: do not use readiness flags on slicer vm add. If startup blocking or readiness is required, run slicer vm ready as a separate step.

When creating VMs for mutable tasks, do not target or reuse slicer-1 on slicer-mac unless the user explicitly requests it. Reuse the session's tagged VM when known; otherwise create a new VM with explicit --tag.

Persistent temporary VMs

VMs created with slicer vm add are persistent by default, they survive daemon restarts and shutdowns. Pair every launch with descriptive --tags so the sandbox can be rediscovered later. Pass --persistent=false only when you want a one-shot ephemeral VM that disappears with the daemon.

On slicer-mac: launch into the sbox host group explicitly — the slicer group is reserved for the persistent Linux twin.

VM_NAME=$(slicer vm add sbox \
  --tag "workflow=rustfs" --tag "purpose=s3-demo" \
  | awk '/Hostname:/ {print $2; exit}')
slicer vm ready "$VM_NAME"

# Rediscover later by tag:
slicer vm list --json | jq -r '.[] | select(.tags.workflow=="rustfs") | .hostname'

On Slicer for Linux: host group names vary per deployment. Either:

1. List groups first and pick an appropriate one:

``bash slicer vm group --url "$SLICER_URL" --token-file "$SLICER_TOKEN_FILE" slicer vm add --tag "workflow=..." ... ``

1. Or skip the check and launch into the default group by omitting the positional arg:

``bash slicer vm add --tag "workflow=..." ... ``

Wait for readiness

# Block until the slicer-agent is responsive (default)
slicer vm ready VM_NAME --agent --timeout 5m

# Block until userdata script has finished
slicer vm ready VM_NAME --userdata --timeout 5m

--agent waits for the in-VM slicer-agent (vsock RPC). --userdata waits for the bootstrap script to complete (guarded by /etc/slicer/userdata-ran in the guest). Polling interval: --interval 100ms (default).

Prefer slicer vm shell for interactive workflows that need command history, incremental state, and a stable PTY.

Non-blocking health check

slicer vm health VM_NAME --json    # Agent version, uptime, stats — does not block

---

Running Commands

Execute a command (foreground)

slicer vm exec VM_NAME -- "whoami"

slicer vm exec blocks until the command exits and streams stdout/stderr inline. For long-running processes that should survive client disconnect (dev servers, multi-minute builds, agent-driven workflows), use slicer vm bg exec instead — see [Background Exec](#background-exec-long-running-processes) below.

By default, slicer vm exec executes the command through a shell, so use direct command strings. For plain exec with no shell interpretation, use --shell "". Avoid wrapping with /bin/bash -lc or explicit shell launches unless you intentionally need shell-specific parsing. Anti-pattern: slicer vm exec ... -- /bin/bash -lc "..." (unless required for nested shell logic).

The default user is auto-detected (typically ubuntu, uid 1000). Override with --uid:

slicer vm exec VM_NAME --uid 1000 -- "sudo apt update && sudo apt install -y nginx"

Key flags:

| Flag | Purpose | |------|---------| | --uid | Run as target user UID (non-root default is auto-detected, typically 1000) | | --cwd string | Set working directory (~ and ~/path supported, ../ traversal is blocked) | | --env stringArray | Pass environment variables as KEY=VALUE pairs (repeatable) | | --shell "" | Skip shell interpreter, exec directly |

--cwd and --env are direct slicer vm exec flags (confirmed from slicer vm exec --help).

Example:

slicer vm exec VM_NAME --uid 1000 --cwd ~/project --env FOO=bar --env DEBUG=1 -- "env | sort | head -n 5"

Pipes and stdin work:

# Pipe local file into VM
cat script.sh | slicer vm exec VM_NAME -- "bash"

# Pipes inside VM
slicer vm exec VM_NAME -- "ps aux | grep nginx"

Interactive shell

slicer vm shell VM_NAME

Flags (from slicer vm shell --help): --uid, --cwd, --shell, --bootstrap "command" (run on connect).

• --env is not a slicer vm shell flag; pass env vars inside the shell once connected or use slicer vm exec --env.
• --shell in slicer vm shell is shell-choice only; do not assume zsh is installed.

Use slicer vm shell for longer interactive work; keep slicer vm exec for bounded command calls. It opens an interactive PTY, so it is not suited to non-interactive stdin pipelines.

Background Exec (long-running processes)

Use slicer vm bg exec when the command should survive client disconnect — dev servers, builds, test runs. Do not use slicer vm exec ... & — that ties the child to the local shell and you can't reconnect.

Critical difference from vm exec: bg exec defaults to direct exec (no shell). vm exec defaults to /bin/bash. This means:

• Positional: pass binary + args as separate tokens. -- npm run dev ✓. -- "npm run dev" ✗ (error).
• Shell features needed? Use --shell=/bin/bash. For daemons, prefix with exec: --shell=/bin/bash -- "cd /app && exec ./server".
• Explicit form (-c/-a): always direct-exec, no quoting issues, mutex with --shell and positional.

Three command forms:

# 1. Positional — separate tokens after --
slicer vm bg exec VM_NAME --uid 1000 -- npm run dev

# 2. Explicit — preferred for agents
slicer vm bg exec VM_NAME --uid 1000 -c npm -a run -a dev

# 3. Shell — opt-in for $VAR, pipes, &&
slicer vm bg exec VM_NAME --uid 1000 --shell=/bin/bash -- "cd /app && exec npm run dev"

Capture exec_id for later management:

EX=$(slicer vm bg exec VM_NAME --uid 1000 --cwd /home/ubuntu/app \
     -- npm run dev \
     | awk -F'[= ]' '/exec_id=/ {for (i=1;i/dev/null 2>&1; then
  if lsof -i TCP:"$PORT" -sTCP:LISTEN >/dev/null 2>&1; then
    echo "Local port $PORT is already in use. Pick a different host port (for example 18080)."
    exit 1
  fi
else
  echo "Cannot validate local port availability (lsof not installed); proceed with caution."
fi

# TCP port forward
slicer vm forward VM_NAME -L 8080:127.0.0.1:8080

# Remap host port
slicer vm forward VM_NAME -L 3000:127.0.0.1:8080

# Supported mapping forms:
# - TCP -> TCP: LOCAL_HOST:LOCAL_PORT:REMOTE_HOST:REMOTE_PORT
# - Unix socket -> TCP: LOCAL_HOST:LOCAL_PORT:REMOTE_SOCKET
# - Unix socket -> Unix socket: LOCAL_SOCKET:REMOTE_SOCKET
# Unix socket → local TCP (e.g. Docker)
slicer vm forward VM_NAME -L 127.0.0.1:2375:/var/run/docker.sock

# Unix socket → local Unix socket
slicer vm forward VM_NAME -L /tmp/docker.sock:/var/run/docker.sock

# SSH access
slicer vm forward VM_NAME -L 2222:127.0.0.1:22

# Privileged VM services (e.g. nginx on 80/443) should use high host ports unless requested otherwise.
slicer vm forward VM_NAME -L 8080:127.0.0.1:80
slicer vm forward VM_NAME -L 8443:127.0.0.1:443

# Multiple forwards at once
slicer vm forward VM_NAME -L 8080:127.0.0.1:8080 -L 5432:127.0.0.1:5432

Port forwards run in the foreground — use & to background them.

See [references/networking.md](references/networking.md) for bridge, isolated, and macvtap (LAN-direct) networking.

---

VM Lifecycle

slicer vm pause VM_NAME       # Freeze (saves CPU, instant resume)
slicer vm resume VM_NAME      # Unfreeze
slicer vm shutdown VM_NAME    # Graceful shutdown
slicer vm delete VM_NAME      # Remove VM
slicer vm suspend VM_NAME     # Save state to disk (snapshot)
slicer vm restore VM_NAME     # Restore from snapshot

Monitoring

slicer vm health VM_NAME      # Agent status, version, stats (--json)
slicer vm top                 # Live metrics for all VMs
slicer vm top VM_NAME         # Live metrics for one VM
slicer vm logs VM_NAME        # Boot/console log (--lines N)

---

Agent Sandboxes (Coding Agents in VMs)

Slicer can provision a fresh microVM, install a coding agent into it, and — depending on the argument — sync

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: slicervm
• Source: slicervm/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.