# Core Concepts

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`