Docs · Configuration
Where everything lives.
poddle keeps state in plain files under your OS config directory, resolves templates from three predictable places, and reads a short list of environment variables. No hidden global state.
On-disk layout
Everything is a file you can read, back up, or check in. Secrets are stored mode 0600 and never leave your machine - the broker seals them into its vault at spin-up.
| What | Path | Notes |
|---|---|---|
| Identities | ~/.config/poddle/identities/<name>/ | One directory per login - meta.toml plus the sealed token, mode 0600. |
| User templates | ~/.config/poddle/templates/<name>.toml | Your personal blueprints, available in any project. |
| Connectors | ~/.config/poddle/connectors/ | Brokered service definitions added with poddle connect. |
| Project templates | .poddle/<name>.toml | Checked into the repo and shared with the team. |
| Project default | .poddle.toml | Auto-applied when you run poddle up with no --template. |
OS-correct paths
~/.config/poddle is the Linux/macOS location; on Windows it resolves to %AppData%\poddle. poddle uses the platform config dir, so you don’t hard-code paths.
How a template is chosen
When you pass --template <name>, poddle looks it up by filename across two locations. A project file shadows a user file of the same name, so a repo can pin its own version of a shared blueprint:
- Project -
.poddle/<name>.toml(wins on a name clash). - User -
~/.config/poddle/templates/<name>.toml.
With no --template, poddle applies the project default - the repo’s root .poddle.toml - if one exists. Missing files are never an error; you only need what you use.
How extends merges
A template can extends one parent or a list of them; chains flatten and a cycle is a hard error. When a child layers over a parent, values combine by type:
| Field kind | Rule | Examples |
|---|---|---|
| Scalars | Child overrides - a non-empty child value wins. | image, size, harness, identity, repo, secret_scan, egress |
| Lists | Append - parent items first, then child. | setup, scripts, connectors, block_paths, mounts |
| Maps | Merge - child keys override same-named parent keys. | env |
| Flags | Sticky - once a parent turns it on it stays on. | autoscale |
One base, many specializations
Because lists append and scalars override, a shared base that sets safe defaults (image, secret_scan, egress) is inherited by every template that extends it - a project template only states what differs. See the Templates examples for the pattern.
Environment variables
A handful of variables tune the CLI and daemon. All are optional - the defaults are the common case.
| Variable | Default | Effect |
|---|---|---|
PODDLE_HOST | local podman | Target a remote host as ssh://user@host - the same commands run against it. Empty means local Podman. |
PODDLE_BROKER_ADDR | host.containers.internal | The routable address a remote pod dials to reach the broker (e.g. this machine’s LAN IP). Local pods use the default. |
PODDLE_ANTHROPIC_BASE_URL | https://api.anthropic.com | Point the Anthropic provider at a compatible proxy or gateway instead of the public API. |
PODDLE_AUTOSCALE_INTERVAL | 15s | How often the daemon’s autoscaler samples memory pressure (a Go duration like 5s or 1m). |
# run the same commands against a remote host
export PODDLE_HOST=ssh://you@build-box
poddle up my-sandbox --identity work