Core Concepts

Last updated 2026-10-06

This page explains how PodRun identifies a deployment: the rules for the UID, the remote folder, and the local project folder.

Local Project Folder

Resolved in this order, then converted to an absolute path:

Priority	Source
1	`--folder=<path>` or `--folder <path>`
2	Directory of `-f <file>` (when `dir != "."`)
3	A positional directory that starts with `./` or `/` and exists
4	Current working directory

The folder must exist and contain docker-compose.yml or docker-compose.yaml; otherwise command.New() returns an error.

Deployment UID

uid = md5("<MAC>@<local-absolute-path>")

The MAC comes from the first non-loopback interface with a hardware address; the hostname is used when none is found
The same machine and project path always yield the same UID
-u <uid> overrides it; the override affects only the recorded UID, not the remote folder

Remote Folder

/home/podrun/<local-folder-name>_<first-8-hash-chars>

The hash shares its source with the UID, so same-named projects from different machines or paths never overwrite each other. The /home/podrun root is fixed and independent of PODRUN_USERNAME.

Command Dispatch

Command	Path	Behavior
`up`	`up()`	Sync, rewrite compose, recreate containers, report to the API
`clear`	`clear()`	Remove containers, volumes, images, and the remote folder
`down` / `ps` / `logs` / `restart` / `exec` / `build`	`runCMD()`	Run `podman compose <args>` in the remote folder
`domain` / `deploy`	`main`	No action (unfinished)
Anything else	—	`unsupported command`

The first element of RemoteArgs is the command name; -d, -f <file-name>, and other arguments are forwarded to podman compose as-is.

Foreground and Background

-d: containers start in the background, then port mappings and Pod info are printed
Without -d: up streams compose output in the foreground; the remote command is wrapped in trap cleanup INT TERM, so Ctrl+C runs podman compose down