Reference

Bare paddock, and paddock with any flag that is not -h or --version, both mean choose.

$ paddock --help
usage: paddock [-h] [--version]
               {choose,launch,run,attach,profiles,gc,collect,logs,init} ...

The `paddock` command: the popup chooser by default, and the same jobs without
questions.

positional arguments:
  {choose,launch,run,attach,profiles,gc,collect,logs,init}
    choose              ask what to open (the default)
    launch              start a session from a saved profile, no questions
    run                 run a session in this terminal, with no herdr and no
                        new tab
    attach              put a new tab on a running session
    profiles            list saved profiles
    gc                  collect sessions whose tabs are all closed (every
                        command does this first)
    collect             end one session now: stop its sandbox and drop it from
                        the registry
    logs                where paddock logged what it did, and the end
    init                bind the chooser to prefix+s in herdr's config

options:
  -h, --help            show this help message and exit
  --version, -V         print the version and exit

--cwd is a permission on launch, and only a directory on attach. On launch it is the one host directory the sandbox may read and write. On attach it only says where the tab opens, because the session's permissions were settled when it was created.

Same profile, same policy, same launch script. What differs is who owns the terminal.

What ? shows in the chooser.

Escape means two things, on purpose. On the form it cancels, because nothing is before it. On the confirm screen it is the Back button, and on every list and checklist it backs out one level keeping what you did there.

One JSON file per profile, in ~/.config/paddock/profiles/. The filename stem wins over name. A field of the wrong type rejects the whole file rather than half applying it.

Built in

One JSON file per agent, in ~/.config/paddock/agents/. An entry with no command is unusable and is skipped.

Built in

The localhost:<port> convention

A domain is split on its last colon, and the suffix counts as a port only if it is a decimal between 1 and 65535. A loopback host with a port names that one port; a bare localhost means every port.

# ~/.config/paddock/agents/local-model.json
{
  "name": "Aider on the local model",
  "command": "aider --no-auto-commits",
  "image": "python:3.12-slim",
  "install": "pip install --quiet aider-chat",
  "api_domains": ["localhost:11434"]
}

On msb that becomes one rule, allow@host:tcp:11434, and the guest boots with OPENAI_BASE_URL and OLLAMA_HOST pointed at host.microsandbox.internal. Both variables are set only when the profile resolves to exactly one loopback port. On srt the port is not honoured: Seatbelt's loopback rule takes no port, so the grant is every service on this machine.

An agent's own api_domains are added whatever you tick, so picking an agent is granting the hosts it signs in to. Tick nothing else and that is all a session can reach; pick the shell agent and it reaches nothing.

What paddock reads

An empty value falls back to the default. Setting PADDOCK_STATE_DIR= gives you ~/.local/state/paddock, never the current directory.

What the sandbox is given

Nothing else crosses. Only HOME, USER, LOGNAME, SHELL, TERM, LANG, LC_ALL and TMPDIR are carried through from the host, plus the proxy variables srt needs.

The install script