Learn Podman - API Service & Remote Client

#Introduction

In episode 14 you secured images and credentials with secrets, signatures, and Trivy. Now imagine a cluster with dozens of hosts — typing podman run on every machine isn't a scalable way to work. Episode 15 opens two paths for remote control: the REST API, compatible with Docker, and podman-remote, a native client that communicates over SSH.

#Architecture: Engine on the Server Side

Podman is indeed daemonless, but this component opens a controlled exception: podman system service runs an API service that is entirely optional. Without this service, Podman keeps working normally. With it, the machine becomes a server that can receive requests from outside — both Docker-compatible clients and podman-remote.

#Opening the API Service

podman system service --time=0
podman system service --time=5 unix:///tmp/podman.sock

The last argument is the endpoint. A unix socket is used by default, and --time=0 disables the timeout. For production use, run this service as a systemd unit so it restarts automatically if it dies.

#REST API Endpoints

This service serves two families of APIs at once:

• Libpod API — Podman's native endpoints under the libpod prefix, for example pod, machine, and healthcheck operations.
• Docker-compatible API — Docker Engine-style endpoints, for example container listing, build, and volumes.

Both families can be called directly over HTTP:

curl --unix-socket /run/podman/podman.sock http://localhost/_ping
curl --unix-socket /run/podman/podman.sock http://localhost/containers/json

#Docker API Compatibility

The existence of a Docker-compatible API means the Docker client ecosystem works too. docker-py is the most common example:

Managing Podman with docker-py

from docker import DockerClient
 
client = DockerClient(base_url="unix:///run/podman/podman.sock")
containers = client.containers.list()
client.containers.run("nginx:alpine", ports={"80/tcp": 8080})

Note the only change: base_url points to the Podman socket. Orchestration scripts you've already written for Docker often need just one line changed. The same applies to docker compose pointed at it via DOCKER_HOST.

#Authentication at the API Level

A unix socket is secure because it's limited by file access. Once the API is opened over TCP, you must add protection: run it behind an SSH tunnel, restrict it to a private network, or use TLS. Never expose the API to the open internet without protection.

#Forwarding the Socket via SSH

The simplest way to secure an API opened on TCP is not to open it to the public at all. Leave podman system service listening on localhost, then create an SSH tunnel to the remote machine:

ssh -L 8080:127.0.0.1:8080 deploy@10.0.0.5
export DOCKER_HOST=tcp://127.0.0.1:8080
docker ps

With this pattern, traffic is encrypted end-to-end, authentication is handled by SSH, and port 8080 on the remote host is never visible to other networks. This approach can also be used with podman-remote, although in practice podman-remote already uses SSH directly.

#podman-remote

For daily use, the more convenient client is podman-remote — the same binary as Podman but focused on communicating with a server:

podman system connection add prod --identity ~/.ssh/id_ed25519 ssh://deploy@10.0.0.5/run/podman/podman.sock
podman-remote -c prod ps
podman-remote -c prod run -d --name web nginx:alpine

podman system connection add stores the connection configuration. After that, podman-remote commands, identical to local podman, run on the remote machine.

#Secure Connections

The podman-remote connection runs over SSH, so all SSH security applies: key authentication, forwarding to the target socket, and traffic encryption. Recommended practices:

• Use a dedicated deployment SSH key, not a personal key.
• Include a passphrase or use an SSH agent.
• Create an account with minimal privileges on the target machine.
• Define connections with clear names (prod, staging) in containers.conf.

#API vs Remote Client

Choose based on need: API for automation and integration, remote client for humans who want the full CLI.

#Closing

In episode 15 you controlled Podman from a distance: opening the REST API with podman system service, getting to know the Libpod and Docker-compatible endpoints, using docker-py via the socket, securing the connection with SSH, and orchestrating containers from another host using podman-remote.

The key points to take home:

• The API service is optional, not mandatory — without it Podman stays daemonless.
• Docker compatibility means a one-line migration — base_url or DOCKER_HOST.
• SSH is the secure gateway — don't expose the API to the internet without protection.
• Choose the tool for the context — API for machines, remote client for humans.

In the next episode, Episode 16, we'll harden what's already in place: isolation & hardening — limiting CPU, memory, and PIDs with cgroups v2, read-only rootfs, and network isolation and auditing.