Docs · Headless & CI

Agents that run themselves.

poddle task hands a coding agent a prompt in a fresh, secretless pod, runs it to completion, and tears the pod down - no shell, no key, no babysitting. Perfect for nightly jobs and CI.

Run a task

Give it a prompt and an identity. The pod spins up, the agent works, and everything is gone when it finishes:

>_zsh
poddle task "add tests for parseConfig" --identity work
→ pod poddle-task-9f2a up (weak) · broker attached
→ claude-code · 6 turns · editing parser_test.go
✓ done · pod torn down · no key ever entered the pod
  • --max-turns bounds the run (default 24) so a stuck agent can’t loop forever.
  • --template reuses a blueprint - image, repo, connectors, and safety rules in one flag.
  • --keep leaves the pod up to inspect afterward; --detach runs it in the background and returns immediately.

Watch a detached run

A backgrounded task keeps working after the command returns. Follow it with logs, and tear it down when you’re done:

>_zsh
poddle task "port the module to v2" --identity work --detach --keep
poddle logs poddle-task-9f2a --follow
poddle stats                       # live CPU / memory for running pods
poddle down poddle-task-9f2a

Burst for the job, shrink after

Autonomous jobs often need horsepower for a run and nothing while idle. A template can resize around each task with before_task and after_task - burst to a strong pod for the run, drop back to weak when it’s kept:

>_.poddle/nightly.toml
# extends api - inherits repo, connectors, and safety rules
extends = "api"
before_task = "strong"
after_task = "weak"

Reactive autoscaling

For runs whose peak memory you can’t predict, --autoscale lets the poddleddaemon react to real memory pressure. Its behavior depends on the mode:

  • Headless (poddle task --autoscale) - the daemon auto-grows the pod to a bigger shell when it nears its memory limit.
  • Interactive (poddle up --autoscale) - the daemon only warns; you stay in control of the resize.

How it samples

The autoscaler checks memory every 15s by default; set PODDLE_AUTOSCALE_INTERVAL (a Go duration like 5s) to change the cadence. It grows one size step at a time - it never shrinks a live pod out from under a running agent.

In a pipeline

Because credentials stay in the broker, CI never holds a vendor key. A step authenticates a brokered identity, runs the task against a checked-in template, and the pod carries only a revocable handle:

>_.woodpecker.yml
# nightly agent run - no secrets in the CI environment
steps:
  agent:
    image: poddle/ci
    commands:
      - poddle task "triage flaky tests and open fixes" \
          --template nightly --identity ci --autoscale

Pair it with brokered connectors

Add connectors = ["github"] to the template and the agent can push a branch or open a PR - the forge token is injected on the wire, never written into the pod. See Connectors.

task reference →Templates →Connectors →