Questions & gotchas.

Install & setup

Do I need Podman installed?

Yes - poddle drives Podman to create and attach pods, so install it first. Rootless Podman works; see the stats note below for one caveat.

How do I install poddle?

Quickest is curl -sSf https://get.poddle.dev | sh. Also on Homebrew (brew tap datadir-lab/tap && brew trust datadir-lab/tap && brew install poddle; the trust step is a one-time Homebrew 6.0+ requirement for third-party taps), Scoop for Windows, and as .deb/.rpm/.apk on each release. Or build from source with Go 1.25+: go build -o poddle ./src/cli.

Can I run against a remote host?

Set PODDLE_HOST=ssh://user@host and run the same commands; leave it empty for local Podman. The broker runs where you invoke poddle, so your keys never travel to the remote host.

Templates & identities

“unknown template” - what went wrong?

poddle looks up --template <name> by filename in .poddle/<name>.toml (project) and ~/.config/poddle/templates/<name>.toml (user). Check the name and location - see Configuration.

“unknown parent template” or “template cycle via …”

An extends names a template that doesn’t exist, or two templates extend each other. Fix the chain so it terminates at a real base.

“unknown provider” / “unknown harness”

Today poddle ships the anthropic provider and the claude-code harness; more are planned. Check the flag value.

My identity stopped working.

Run poddle identity status <name>. If it reports NOT authenticated, re-run poddle identity add <name>. poddle also re-authenticates a stale login before wiring it into a pod, so a dead credential never reaches the sandbox.

Secrets & safety

Where are my credentials stored?

Under ~/.config/poddle/identities/<name>/ (mode 0600) on your machine - never only in poddle. The broker seals a copy into its vault at spin-up; the pod only ever holds a revocable handle.

How do I revoke a pod’s access?

poddle down <name> revokes the pod’s handles as it tears the pod down. Revocation is immediate - no key rotation, no image scrubbing.

“no token - pass --token or pipe it on stdin”

poddle connect add needs the service token. Pipe it on stdin (keeps it out of your shell history) or pass --token. See Connectors.

A pod refuses to start on a credential file.

With secret_scan = "block", a mount carrying a credential file stops the pod, and block_paths refuses the mount entirely. Loosen to warn or drop the path - see Security.

Headless & CI

“poddle stats” shows nothing under rootless Podman.

Live CPU/memory needs cgroup accounting; some rootless setups without cgroup-v2 delegation don’t expose it. Run on a cgroup-v2 host, or via the system Podman service.

Does autoscale ever shrink my pod?

No. It grows one size step under memory pressure and never shrinks a live pod out from under a running agent. Headless (task) auto-grows; interactive (up) only warns.

How do I watch a background task?

Run it with poddle task … --detach, then follow its output with poddle logs <name> --follow. See Headless & CI.