First Install

[HCH-hash]

First: thank you for building this. It's running, it's doing the job, and the
board model is the part I'd have found hardest to build myself. What follows is
the setup experience written down while it was still fresh — mostly friction,
because that's the useful part, but I want to be clear up front that I got where
I was going and I'd choose it again.

The constraint that shaped everything

I installed Paca unattended. The whole thing was driven by an AI coding agent
issuing commands over SSH from a CI job — at no point was there a human at a
terminal. That's not a stunt; it's how I run infrastructure changes, so that
every step is reviewable afterwards and no password is ever typed into a screen.

That single constraint is what put me on the manual setup path rather than
install.sh, and nearly everything below follows from it.

What was easy, and genuinely good

• The production compose file is well made. Healthchecks that mean something,
  --scale escape hatches for external Postgres and S3, and a backup sidecar with
  retention and a cron expression. That last one is the kind of thing most projects
  leave as an exercise for the reader.
• The workflow model clicked immediately. Statuses carrying a category, and a
  workflow deriving its done state from having exactly one terminal status, is a
  clean idea. I modelled a nine-step release chain with two human gates in it and
  the model just absorbed it without me fighting it.
• ACP agents were the highlight. Being able to point an agent at a coding CLI
  already logged in on the host means the agent runs on an existing subscription
  and Paca never holds a model provider credential at all. That's a better security
  story than passing an API key in, and it saved me real money.
• Read-only project roles. I have verifier agents whose whole value is judging
  work they didn't do. Assigning them a read-only role turned that independence
  from a sentence in a prompt into something the server enforces. I didn't expect
  to find that already built, and it's the feature I'd point at first.

Where I got stuck

Ten things, roughly in the order I hit them. Each is: what I did, what happened,
what it actually was.

1. The env template and the compose file disagree about images.
.env.production.example sets PACA_API_IMAGE=paca-api:latest and friends — bare
tags that only resolve if you built from source. The compose file already defaults
these correctly to pacaai/*, so the template's job here is purely to override a
good default with a broken one. I copied the template as instructed and got
pull access denied for paca-realtime. The template does carry a comment saying to
override them for a registry, which I missed — but a template that ships values
guaranteed to fail is a trap worth removing. PACA_AI_AGENT_IMAGE isn't in the
template at all, so it silently tracked :latest while I thought I'd pinned
everything.

2. Two required variables exist in compose but in no template.
The api service needs AI_AGENT_INTERNAL_KEY (fed from INTERNAL_API_KEY) and
AGENT_API_KEY. Both are ${VAR:-} in compose, so the stack starts and then
restart-loops with "AI_AGENT_INTERNAL_KEY must be set". Neither name appears in
.env.production.example.

3. …and deploy/README.md already knows this. Its manual-setup section
correctly lists AGENT_API_KEY, INTERNAL_API_KEY and ENCRYPTION_KEY as
required — while pointing at the env template as the reference to work from. The
two documents contradict each other, and I happened to follow the wrong one. I
had actually added INTERNAL_API_KEY on an earlier attempt and then removed it
because it wasn't in the template. The template was the thing that was wrong.

4. SITE_ADDRESS is undocumented and defaults to :80.
This is the quiet one. Everything comes up healthy, the site loads, and you have
no TLS — Caddy was never asked for a certificate and nothing anywhere says so. It
isn't in the env template either.

5. The Caddyfile bind mount fails in the least helpful way.
Compose bind-mounts ./caddy/Caddyfile. Miss the download step and Docker
helpfully creates a directory at that path, then refuses to mount a directory
onto a file. The compose header does list downloading it as step 1 — my miss —
but the failure gives you no hint that a missing file is the cause.

6. GET /api/v1/agent-types is documented but doesn't exist.
It's in docs/ai-agent/api-design.md, and it 404s. I can't find a route for it
registered anywhere in the API service. My script died on it.

7. /agents is the exact opposite — real, but undocumented.
Because of #6 I concluded agents had to be created by hand through the UI and
wrote that into my notes. They don't: there's a full agents REST API, it's just
absent from the main API reference. So the docs and the build disagree in both
directions, which meant the only reliable strategy was to stop reading and start
probing for endpoints.

8. Creating an agent demands an LLM API key you may not need.
Every create call was rejected for a missing llm_api_key — for the exact thing
my existing subscription already covered. The reason is only visible in the DTO:
agent_type defaults to llm, and the LLM fields are required only in that case.
Setting it to acp with an acp_provider means no key is involved at all. That
default costs money if you don't notice it.

9. page_size above the maximum is silently clamped.
The max of 100 is documented — my bug for asking for 1000. But the request
didn't fail, it just quietly returned less. My existence check therefore saw 100
of 164 items, concluded everything past the first page was new, and created it all
a second time. A 400 would have cost me one confused minute instead of a
duplicate-cleanup script.

10. install.sh has no unattended mode. 733 lines, every prompt a read -p,
no flags, no env-driven answers. There's no supported way to install Paca from a
script, which is why I was on the manual path for all nine of the above.

Two small ones while I'm here: the API health endpoint is /api/healthz and I
wasted a while on a guessed /api/v1/health; and once a certificate is issued, an
http:// health probe gets a 308 — the redirect that proves it worked reads
as a failure to any check that doesn't follow redirects. Both are one line each in
the deployment docs.

Mistakes that were mine

So the list above is fair: I skipped the recommended installer, I copied a
template past its own override comment, I missed a documented download step, I
invented three variable names that never existed (and used two more under the
wrong names, so my admin login was never actually set), and I asked for a page
size over the documented maximum. Several of these are exactly what the
recommended path exists to prevent.

What I'd suggest

1. An unattended mode for install.sh — --non-interactive reading answers
   from environment variables. This is the root cause of nine of my ten problems.
   And it seems worth naming plainly: this is a product whose pitch is humans and
   AI agents working as equals, and right now the agent can't install it. Everyone
   automating a deployment is pushed onto the manual path and will hit the same
   rocks I did.
2. Make the env template a superset of what compose requires — add
   AGENT_API_KEY, INTERNAL_API_KEY, SITE_ADDRESS, ENCRYPTION_KEY, and
   either drop the image lines or ship them as the registry paths they have to
   become. I'm happy to send this as a PR if it'd be useful.
3. Fail fast on missing required config. A startup check naming the empty
   variable beats a restart loop. I ended up writing this for myself — parsing
   compose for ${VAR} with no fallback and reporting any left empty — and it
   turned the next gap of this kind into a warning before the start instead of a
   mystery after it.
4. Reject an over-maximum page_size with a 400 rather than clamping. Silent
   clamping turned one client-side mistake into duplicated data across a board.
5. Either document the agents API or mark agent-types as not yet
   implemented. Right now a careful reader is misled twice.

None of this stopped me shipping, and the parts that are good are good in ways
that are hard to copy. The setup path is just a long way behind the product — and
it's the first thing every new self-hoster meets.

[pikann]

Hi @HCH-hash , thank you so much for the detailed and thoughtful feedback
Your point about AI agents needing a seamless setup is spot on! We're reviewing your suggestions and will be updating Paca soon