BCVK-EPHEMERAL-RUN-SSH(8)

💖 bcvk-ephemeral-run-ssh(8) 💖

okay bestie, welcome to the section 8 manual page for bcvk-ephemeral-run-ssh — the little command that boots a whole ephemeral VM and drops you straight into an SSH session like it's nothing 🦋

---

✨ SYNOPSIS ✨

bcvk ephemeral run-ssh [OPTIONS] IMAGE [SSH_ARGS]

---

🌸 DESCRIPTION 🌸

So here's the vibe: you take a bootc container, you run it as an ephemeral VM, and the moment it's up you're SSH'd into it. No cap. And the second your SSH session ends? The VM gets stopped and cleaned up automatically. It's giving responsible. It's giving self-cleaning. We love her 💅

This is the recommended command for quick testing and iteration, fr fr. It's basically bcvk ephemeral run and bcvk ephemeral ssh fused into one single command with automatic lifecycle management, and honestly? iconic.

🎀 Lifecycle Behavior 🎀

Okay so listen — this is NOT the same as bcvk ephemeral run -d. That one starts a background VM that just... persists. Forever. Until you explicitly stop it. Meanwhile run-ssh ties the VM's whole lifecycle to your SSH session, like a bestie who leaves the party when you leave the party 🫶

Here's the order of operations:

1. VM boots and waits for SSH to become available
2. SSH session is established
3. When you exit the SSH session (or the connection drops), the VM is stopped
4. The container is automatically removed

So run-ssh is ideal for:

• Quick one-off testing of container images
• Rapid build-test iteration cycles
• Running a single command in a VM environment
• Demos and exploration

But if you need a longer-running VM where you reconnect multiple times? Different beast, bestie. Use bcvk ephemeral run -d --rm -K instead.

---

💅 OPTIONS 💅

• IMAGE — the container image you're running as an ephemeral VM. This argument is required, no skipping it 🙈
• SSH_ARGS — the SSH command to execute. Optional! Defaults to an interactive shell if you don't say anything.
• --itype=ITYPE — instance type, like u1.nano, u1.small, u1.medium. Heads up: this overrides vcpus/memory if you specify it.
• --memory=MEMORY — memory size, e.g. 4G, 2048M, or just a plain number for MB. Default: 4G
• --vcpus=VCPUS — number of vCPUs. (Gets overridden by --itype if you specified that.)
• --console — connect the QEMU console to the container's stdio (you can see it via podman logs/attach)
• --debug — enable debug mode, which drops you to a shell instead of running QEMU
• --virtio-serial-out=NAME:FILE — add a virtio-serial device with output to a file (format: name:/path/to/file)
• --execute=EXECUTE — execute a command inside the VM via systemd and capture the output
• -K, --ssh-keygen — generate an SSH keypair and inject it via systemd credentials ✨
• --virtiofsd=VIRTIOFSD_BINARY — path to the virtiofsd binary (this overrides auto-detection)
• --output=OUTPUT — select how VM output is presented

Possible values:

• console
• journal

Default: console

• --log-dir=STREAMS=DIR — write VM log streams to files in DIR
• -t, --tty — allocate a pseudo-TTY for the container
• -i, --interactive — keep STDIN open for the container
• -d, --detach — run the container in the background
• --rm — automatically remove the container when it exits
• --name=NAME — assign a name to the container
• --network=NETWORK — configure the network for the container
• --label=LABEL — add metadata to the container in key=value form
• -e, --env=ENV — set environment variables in the container (key=value)
• --debug-entrypoint=DEBUG_ENTRYPOINT — do not run the default entrypoint directly, but instead invoke the provided command (e.g. bash)
• --bind=HOST_PATH[:NAME] — bind mount a host directory (RW) at /run/virtiofs-mnt-<name>
• --ro-bind=HOST_PATH[:NAME] — bind mount a host directory (RO) at /run/virtiofs-mnt-<name>
• --systemd-units=SYSTEMD_UNITS_DIR — directory with systemd units to inject (it expects a system/ subdirectory)
• --bind-storage-ro — mount host container storage (RO) at /run/virtiofs-mnt-hoststorage
• --add-swap=ADD_SWAP — allocate a swap device of the provided size
• --mount-disk-file=FILE[:NAME] — mount a disk file as a virtio-blk device at /dev/disk/by-id/virtio-<name>
• --karg=KERNEL_ARGS — additional kernel command line arguments
• --ignition=IGNITION_CONFIG — path to an Ignition config file (JSON format) to inject via fw_cfg

---

🌈 EXAMPLES 🌈

🍓 Basic Usage

Test a public bootc image:

bcvk ephemeral run-ssh quay.io/fedora/fedora-bootc:42

Test a CentOS bootc image:

bcvk ephemeral run-ssh quay.io/centos-bootc/centos-bootc:stream10

🧚 Build and Test Workflow

The most common development pattern is building and then immediately testing, obviously:

# Build your container
podman build -t localhost/mybootc .

# Boot it and SSH in (auto-cleanup on exit)
bcvk ephemeral run-ssh localhost/mybootc

And for rapid iteration, just combine it all in one command, chef's kiss:

podman build -t localhost/mybootc . && bcvk ephemeral run-ssh localhost/mybootc

⭐ Running Commands

Execute a specific command and exit:

bcvk ephemeral run-ssh localhost/mybootc 'systemctl status'

Check what services are running:

bcvk ephemeral run-ssh localhost/mybootc 'systemctl list-units --type=service --state=running'

Verify your custom configuration:

bcvk ephemeral run-ssh localhost/mybootc 'cat /etc/myapp/config.yaml'

🔥 Resource Allocation

For memory-intensive testing:

bcvk ephemeral run-ssh --memory 8G --vcpus 4 localhost/mybootc

Using instance types:

bcvk ephemeral run-ssh --itype u1.medium localhost/mybootc

🦋 With Bind Mounts

Mount source code for testing:

bcvk ephemeral run-ssh --bind /home/user/project:src localhost/mybootc
# Inside VM: ls /run/virtiofs-mnt-src

💜 Debugging

Enable console output to see boot messages:

bcvk ephemeral run-ssh --console localhost/mybootc

---

👑 TIPS 👑

• Fast iteration: keep your container builds small and layered so rebuilds are faster. The VM boots in seconds, so the container build is usually the bottleneck, ngl.
• SSH arguments: any arguments after the image name get passed to SSH. Use this for commands, port forwarding, or SSH options.
• Exit cleanly: use exit or Ctrl+D to cleanly end the SSH session and trigger VM cleanup.

⚠️ Careful bestie: Ctrl+C may not clean up properly. Exit the nice way, okay? 😭

---

🌟 SEE ALSO 🌟

bcvk(8), bcvk-ephemeral(8), bcvk-ephemeral-run(8), bcvk-ephemeral-ssh(8)

---

🎀 VERSION 🎀

v0.21.0

---

and that's the whole page, bestie 💖 this is bcvk-ephemeral-run-ssh(8) from v0.21.0 — go forth, boot ephemeral VMs, and clean up after yourself like the main character you are. periodt 👑✨