Deployment and extension¶

Moving flower elsewhere means dealing with three things: containers (fencing in unrestricted Bash, and incidentally testing the claim of "no CLI needed"), plugin (domain capabilities travel with the repo, regardless of what the host machine has installed), and the docs site (push to main and it publishes itself; install.sh is served from the Pages domain). The three sections are independent; read what you need.

1. Containers¶

Why a container¶

First, to fence things in. The worker doing the work has unrestricted Bash — flower's Bash allowlist (delegate_guard) only covers the main thread, and anyone sent out has to be able to run tests, so this is deliberate. Inside the container only your project directory is mounted; the framework source sits at /opt/flower inside the image, and nothing else on the host is visible.

Second, the container is itself the test of the portable constraint. There is no Claude Code CLI in the image and no Node, only Python and claude-agent-sdk — requests go out through the native binary bundled with the wheel. If it runs here, "no CLI needed" is not a claim on paper.

Verified (2026-09-06, macOS 15 / arm64 / colima + docker 28.4.0):

What is in the image¶

Base image python:3.13-slim, plus three apt packages on top. Each one has a reason:

The framework source enters the image via COPY, not a bind mount — which is why the agent inside the container cannot reach the framework source on the host:

The entrypoint is ENTRYPOINT ["flower"] and CMD is empty — running the container with no arguments drops into interactive input (it asks what you want done) instead of printing --help. That way you don't have to quote a Chinese request in the shell.

Why you can't mount the host's .venv¶

The SDK ships per-platform wheels, and the bundled binary is platform-specific:

host       claude_agent_sdk-0.2.152-py3-none-macosx_11_0_arm64.whl
           → _bundled/claude is Mach-O 64-bit arm64, 191M
container  claude_agent_sdk-0.2.152-py3-none-manylinux_2_17_aarch64.whl

Mounting it in doesn't run, so the image has to pip install for itself. Turned around, that is also the evidence for portability: the same pyproject.toml, a different native binary per platform, and not one line of framework code changes.

Two scripts¶

The switches for docker/build are all environment variables:

The last three only take effect when FLOWER_MIRRORS=1 — the FLOWER_MIRRORS=0 branch sets no build-args at all.

docker/flowerbox reads two:

FLOWER_HOME is derived from the script's own location rather than hard-coded, so the repo works wherever you clone it.

Build the image and start a container¶

docker/build                       # once is enough
cd ~/any-project-dir               # must be under $HOME, see the mount boundary below
/path/to/flower/docker/flowerbox   # no arguments → it asks what you want, no quoting needed

If your network reaches pypi.org / Docker Hub fine, build like this:

FLOWER_MIRRORS=0 docker/build

flowerbox takes exactly the same arguments as flower — it appends "$@" to the ENTRYPOINT verbatim. --clarify-only, --asks N, --timeout SECONDS, --isolate, -v all work; full table in command line:

cd ~/proj
/path/to/flower/docker/flowerbox --clarify-only -v
/path/to/flower/docker/flowerbox "build me an X"

What actually runs is this line (-t is added only when there is a TTY, see below):

docker run -i $TTY --rm \
    --env-file "$FLOWER_HOME/.env" \
    -v "$PWD:/work" \
    -w /work \
    "$IMAGE" "$@"

Mount boundary and persistence¶

host $PWD  ──mount──>  /work       ← the agent works here, output stays on the host
in image               /opt/flower ← framework source, **not mounted**, can't be modified on the host

So running inside a repo subdirectory like flower/human-test/HT001 is also safe: only HT001 is mounted in, and the framework source is outside the mount.

How credentials get into the container¶

Through docker run --env-file, never into an image layer. flowerbox reads $FLOWER_HOME/.env, which defaults to the .env at the repo root:

cp .env.example .env       # fill in the token; .env is already gitignored

Note that flower setup writes ~/.config/flower/.env, and flowerbox does not look at that path. If you already configured it with setup and don't want a second copy, point FLOWER_HOME at it:

FLOWER_HOME=~/.config/flower /path/to/flower/docker/flowerbox

Key names, precedence, and how to fill in the gateway: see configuration.

git submodule¶

.gitmodules has exactly one entry:

A plain git clone doesn't fetch it, and human-test/HT001 is just an empty directory (a leading - in git submodule status means exactly that). Whether you need to care:

Networks in mainland China: why all those mirror swaps¶

Installing this behind the firewall, the bottleneck isn't bandwidth, it's the international routes. The default docker/build already swaps everything that needs swapping, and FLOWER_MIRRORS=0 turns all of it off in one go. Below are the measurements and the reasoning behind the four swaps — skip it if your network doesn't have this problem.

A=https://github.com/abiosoft/colima-core/releases/download/v0.9.0-2/ubuntu-24.04-minimal-cloudimg-arm64-docker.qcow2
mkdir -p ~/.colima/images
curl -sSL -C - -o ~/.colima/images/colima-arm64-docker.qcow2 "https://ghfast.top/$A"
# verify: get the digest from the GitHub API. Don't skip this — you're going to run it as a VM
curl -sSL https://api.github.com/repos/abiosoft/colima-core/releases/tags/v0.9.0-2 \
  | python3 -c "import json,sys;[print(a['digest'],a['name']) for a in json.load(sys.stdin)['assets'] if a['name'].endswith('arm64-docker.qcow2')]"
shasum -a 256 ~/.colima/images/colima-arm64-docker.qcow2

colima start --disk-image ~/.colima/images/colima-arm64-docker.qcow2 \
             --cpu 4 --memory 6 --disk 20

export LIMA_HOME=~/.colima/_lima
limactl shell colima -- sudo sh -c '
  cat > /etc/apt/sources.list.d/ubuntu.sources <<EOF
Types: deb
URIs: https://mirrors.ustc.edu.cn/ubuntu-ports/
Suites: noble noble-updates noble-backports noble-security
Components: main restricted universe multiverse
Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg
EOF
  sed -i "s|https://download.docker.com|https://mirrors.ustc.edu.cn/docker-ce|g" \
      /etc/apt/sources.list.d/docker.list
  pkill -f "apt-get update"          # boot.sh runs to the end and writes the done marker
'
# colima start then exits normally; install rsync afterwards (1.95 MB/s now)
limactl shell colima -- sudo sh -c 'apt-get update -q && apt-get install -y -q rsync'

2. plugin¶

What a plugin is, and how the SDK loads it¶

A domain capability package that travels with the repo. The framework code contains no domain knowledge; all of it lives in the plugin/ directory at the repo root, cloned with the code, reviewed with the code, tagged with the code.

The SDK-side wiring is two lines in build_options() in flower/core/agent.py:

PLUGIN_DIR = Path(__file__).resolve().parent.parent.parent / "plugin"
...
if use_plugin and PLUGIN_DIR.is_dir():
    opts["plugins"] = [{"type": "local", "path": str(PLUGIN_DIR)}]

Together with setting_sources=[] (covered separately below), this is why flower can be both "portable" and "aware of your domain": it doesn't ask what the host machine has installed, it only knows this one directory that came with the repo.

Directory layout¶

The difference between probabilistic and deterministic is the basis for choosing, not a difference in wording:

• A skill is knowledge sitting there. The model sees its description and only reads it if it thinks it is relevant to the current task. The relevance judgement belongs to the model, so the same request run twice may use it once and not the other time.
• A hook is code. It runs when the event matches, regardless of whether the model wants it or knows about it. flower's own spill and isolation are hooks, precisely because they cannot be allowed to work "sometimes".

So there is exactly one criterion: does this have to happen every time? It must — write a hook. It's merely "useful to know" — write a skill. Writing a must-happen thing as a skill stakes discipline on a single judgement by the model.

Right now plugin/ in the repo holds only two things: .claude-plugin/plugin.json and skills/example/SKILL.md. agents/, hooks/, .mcp.json do not exist yet — create them yourself if you need them, with the directory names exactly as in the table above.

Writing a skill: a complete example¶

Take "generate release notes", from nothing to confirmed working.

Step 1: create the directory. The directory name is the skill name, and must match name in the frontmatter.

mkdir -p plugin/skills/release-notes

Step 2: write plugin/skills/release-notes/SKILL.md. The filename must be SKILL.md, uppercase. The format is YAML frontmatter plus a Markdown body, with two frontmatter fields:

A minimal file you can use as-is:

---
name: release-notes
description: Use when putting together release notes. Use it when the user says "write release notes", "what changed in this version", "cut a release".
---

# Release notes

## Where to get the material

```bash
git describe --tags --abbrev=0        # the previous tag
git log --oneline <previous tag>..HEAD   # commits in this release
```

## Output format

Three sections, each an unordered list, one line per item, describing changes the user can perceive; no internal refactors:

- **Added** — what this version can do that it couldn't before
- **Fixed** — what was fixed, one sentence on the symptom
- **Breaking** — what has to be changed to upgrade. If there is none, drop the whole section

## Boundaries

- Don't invent the version number; read `version` from `pyproject.toml`.
- If you're unsure whether a commit is perceptible to the user, list it and ask; don't decide for them.

There is no required format for the body — it is just a piece of text read into the context. Follow the style of plugin/skills/example/SKILL.md: stating when to use it, the steps, what the output should look like and where the boundaries are is more useful than piling up background knowledge.

Step 3: confirm it was loaded. Check exactly one certain thing — whether the directory is there at all:

cd /path/to/flower
python3 -c "from flower.core.agent import PLUGIN_DIR; print(PLUGIN_DIR, PLUGIN_DIR.is_dir())"

Printing /path/to/flower/plugin True means the if in build_options() will be entered. Printing False means it wasn't loaded, and there is no error at run time; see the warning below.

Don't use "run something and see whether the example skill got invoked" as verification. Skills are probabilistic: if the model didn't call it, that could mean it isn't installed, or just that it didn't think the current task needed it — that signal can't tell the two apart. Also, build_options() never sets the SDK's session-level skills= option, and whether skills from the plugin actually appear in the coordinator's list of options has not been measured. The True/False from PLUGIN_DIR above is certain; use that.

To name which skills a given worker gets, use worker(..., skills=[...]) (flower/core/roles.py); use the name from SKILL.md, and the SDK also accepts the qualified form plugin-name:skill-name.

Why setting_sources=[] forces domain capabilities through the plugin¶

The same function also has this line:

"setting_sources": [] if portable else ["project"],

The SDK default is None = read all three sources: ~/.claude/settings.json (user), .claude/settings.json (project), .claude/settings.local.json (local). flower passes [] by default, turning all of them off.

.claude/ having no effect is not a missing config, it is the definition of the constraint: read a single byte from the host machine and "identical behaviour on another machine" no longer holds. So domain capabilities have exactly one channel — plugin/, which travels with the repo.

Two switches (both on build_options(), with the portable set as the defaults):

Incidentally: instructions goes through append (system_prompt's append), a different channel from the plugin — the former is in the context every turn, the latter is loaded on demand. Short, mandatory discipline goes in instructions; long knowledge that is only occasionally useful goes in a skill.

3. The docs site¶

The site you are reading is built with mkdocs-material; the source files are under docs/ in the repo, and pushing to main publishes it.

Editing docs locally:

pip install -r docs-requirements.txt
mkdocs serve                  # local preview
mkdocs build --strict         # run before committing; the same command CI uses

CI triggers on a push to main and changes hitting these paths; you can also trigger workflow_dispatch manually from the Actions page:

docs/**  mkdocs.yml  hooks/**  docs-requirements.txt  install.sh  .github/workflows/docs.yml

Why install.sh is served from Pages¶

The last line of the build step:

- run: cp install.sh site/install.sh

The install script is dropped into the site artifact, so it lives on the docs site's domain, and the one-line install looks like this:

curl -fsSL https://chenyuheee.github.io/flower/install.sh | sh

The reason is practical: raw.githubusercontent.com is unreachable from inside China while *.github.io works (measured). The script itself lives at the repo root; publishing just copies it once more — no second copy of the content to maintain, and no extra CDN.

What install.sh does on its own: pick a Python tool installer (uv > pipx > install uv > pip --user), install flower from GitHub, then tell you the next step. It does not touch credentials — the first flower run asks, and stores them in ~/.config/flower/.env.