Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 37 ยท Systemd and Operations

Podman Machine and Remote Podman

Run Podman on Windows and macOS with podman machine, resize its VM, mount folders, connect to remote hosts with system connections and SSH, and use the Podman API socket.

Containers need a Linux kernel. On Linux, Podman talks to the kernel directly. On macOS and Windows there is no Linux kernel to share, so Podman starts a small Linux virtual machine and runs containers inside it. The podman command you type on your Mac or Windows machine is a remote client that forwards your requests to the Podman service inside that VM.

The same client/server design lets you manage containers on any other Linux host over SSH. This lesson covers podman machine, resizing and mounting, connections to remote hosts, and the API socket. These features need real hosts, so the commands are read-only; the stand-ins check VM sizing and build connection URIs.

podman machine

Terminal
podman machine init                 # create the VM (downloads a Fedora CoreOS-based image)
podman machine start
podman machine list
podman run --rm docker.io/library/alpine:3 uname -a    # runs inside the VM
podman machine ssh                  # shell inside the VM
podman machine stop
podman machine rm

The VM provider depends on the platform:

Platform Provider
Windows WSL 2 (default) or Hyper-V
macOS (Apple silicon) Apple Virtualization (applehv) or libkrun
macOS (Intel) applehv or QEMU, depending on version

Podman Desktop is a graphical application that manages machines and containers for you using these same commands underneath.

Choosing resources

The VM has a fixed CPU, memory and disk allocation. Everything you run shares it, so a container that needs more than the VM has simply fails or is killed.

Terminal
podman machine init --cpus 4 --memory 8192 --disk-size 100 dev
podman machine set --cpus 6 --memory 12288      # machine must be stopped first

Memory is in MiB, disk in GB. Keep the VM smaller than the host's resources: leave memory for your own applications.

Python Machine sizing check (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Sharing folders

On macOS, the home folder is shared with the VM automatically, so -v ~/project:/app works. Bind mounts from folders outside the shared set fail. On Windows with WSL, your Windows drives appear under /mnt/c/... inside the VM. File sharing across the VM boundary is slower than native Linux disks; for heavy I/O (databases) prefer a named volume, which lives inside the VM.

Rootless and rootful machines

By default containers in the VM run rootless. Some tasks (binding low ports, certain networking) need a rootful machine:

Terminal
podman machine set --rootful

Remote connections

The Podman client can control Podman on another machine. Add a connection:

Terminal
podman system connection add buildhost ssh://[email protected]/run/user/1000/podman/podman.sock
podman system connection list
podman system connection default buildhost
podman ps                           # now lists containers on buildhost
podman --connection other ps        # one-off use of another connection
podman --remote ps                  # force the remote client

For the server side, the target user needs the Podman socket running and SSH access with keys:

Terminal
systemctl --user enable --now podman.socket
ls $XDG_RUNTIME_DIR/podman/podman.sock

For a rootful system socket use /run/podman/podman.sock and an account that may use it. You can also set CONTAINER_HOST and CONTAINER_SSHKEY environment variables instead of saving a connection.

Python Build a connection URI (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

A connection with root rights controls the whole remote machine. Use SSH keys, a dedicated account and the rootless socket when you can.

The API socket

podman system service and the podman.socket unit expose a REST API, in two flavors: Podman's own libpod API and a Docker-compatible one. This is what lets Docker clients, Compose and many IDE plugins work with Podman:

Terminal
systemctl --user enable --now podman.socket
export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/podman/podman.sock
curl --unix-socket $XDG_RUNTIME_DIR/podman/podman.sock http://d/v5.0.0/libpod/info

The socket is "socket-activated": systemd starts the service when something connects and it exits when idle, so it costs nothing when unused.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does Podman on macOS and Windows use a virtual machine?

    Containers share the Linux kernel, so a small Linux VM provides it.
  2. 2. How do you give the machine more memory?

    podman machine set changes the VM's resources; stop the machine first.
  3. 3. What does podman system connection add do?

    It stores a name and URI (for example ssh://...) so podman commands can target another host.
  4. 4. Which environment variable points Docker-compatible tools at Podman's socket?

    DOCKER_HOST=unix://.../podman.sock lets Docker clients talk to Podman's compatible API.

Summary

  • On macOS and Windows, podman machine runs a Linux VM and the local podman command is a client for it.
  • Size the VM with --cpus, --memory and --disk-size; share folders carefully and prefer volumes for heavy I/O.
  • podman system connection and --connection manage remote hosts over SSH.
  • The API socket (podman.socket) serves Podman and Docker-compatible APIs for tools such as Compose.
  • Treat remote root access as full control of that host.

Next: Podman and Kubernetes YAML