git:20260713.f77a88e to git:20260725.62fb100

---

name: agami-deploy

description: "EARLY ACCESS (in testing) — usable today, but newer than the local single-player path; feedback welcome via a GitHub issue. Prepares a ready-to-run, self-hosted agami deploy bundle ON THE USER'S MACHINE so a team can stand up a shareable MCP server their Claude connects to. Conversationally gathers the hard-floor inputs (hostname, admin identity), auto-detects the local model, writes docker-compose.yml + Caddyfile + a filled agami.env (referencing the PUBLISHED image ghcr.io/agamiai/agami-core — no clone, no build), and stages the model artifacts. Generates the signing secret via deploy_preflight; the admin password is typed by the user into the file (never in chat). Then runs `docker compose up` if Docker is local, otherwise prints the exact VM steps + the shareable MCP URL. Username/password auth only on this paved path."

when_to_use: "Use when the user says 'deploy agami', 'self-host agami', 'set up the agami server for my team', 'stand up a shared agami', 'host agami on a VM / in the cloud', '/agami-deploy', or otherwise wants the multi-user HTTP server (not the local single-player setup — that's agami-serve). Requires agami-connect to have run first (needs a semantic model + credentials). This is the TEAM path: it produces an internet-reachable server with OAuth + admin that claude.ai connects to."

---

# agami deploy — prepare a self-host bundle the user ships to their own host

You are preparing a **deploy bundle** on the user's machine so they can stand up the multi-user agami

server (the HTTP MCP server with OAuth + admin) that their team's Claude connects to. The bundle pulls

the **published image** (`ghcr.io/agamiai/agami-core`) — there is **no repo to clone and nothing to

build**. You gather a few inputs, write the bundle locally, and hand off the cloud steps you can't do.

The local mirror of this (single-player, no network, no auth) is `agami-serve` — if the user only wants

agami in their own Claude Desktop, point them there instead.

## HARD RULES (load-bearing — a deploy handles secrets)

1. **Never ask for the admin password (or any secret) in chat — not even temporarily.** The password is

typed by the **user** directly into the `agami.env` file (Phase 2 hand-off), exactly like `agami-connect`

does for DB credentials. You never see it.

2. **Never put a secret on a Bash command line.** `prepare_deploy.py` takes only non-secret values;

`deploy_preflight` generates the signing secret *into the file*. Hosts render Bash calls in chat.

3. **Username/password is the only auth this skill sets up.** Do **not** collect Google/Microsoft client

id/secret. Social login ships free but is a manual `agami.env` step — point the user at the in-repo deploy

README if they ask, and move on.

4. **No signup, no license key, no LLM/embedding key.** None are required; don't ask for any.

## Conversation style

Tight and oriented. Print one-line progress markers (`✓ Bundle written to …`, `✓ agami.env validated`).

Be honest about what's the user's clicks (provision the VM, point DNS) vs what you automate.

## Phase −1: Plan-mode preflight

Run the detection logic from [`shared/plan-mode-check.md`](../../shared/plan-mode-check.md). This skill

writes files and may run Docker. If plan mode is active, refuse with: *"I can't prepare a deploy bundle

in plan mode — it writes the bundle + your agami.env and may run Docker. Switch to **Auto** or **Edit

Automatically** mode (Shift+Tab) and re-invoke me."* **DO NOT** write a plan file or call `ExitPlanMode`.

## Phase 0: Preflight

1. **Resolve the environment** — `python3 "$AGAMI_PLUGIN_ROOT/scripts/connect_resolve.py"` prints JSON;

read `data.artifacts_dir` (the local model dir) and `data.interpreter.python3` (call it `$PY` — the

interpreter that has the agami-core package; use it for `deploy_preflight`).

stop and invoke `/agami-connect` first — the deployed server has nothing to serve without one.

## Phase 1: Gather the hard floor, then write the bundle

Ask only these (everything else is defaulted or generated). Prefer one compact exchange:

1. **Hostname** — "What address will your team connect to?" It must be a **hostname, not a bare IP**

(TLS + OAuth need a DNS name). → `PUBLIC_BASE_URL=https://<host>`.

- If they have **no domain / can't open ports**, offer the **Cloudflare tunnel** path (profiles

`bundled-db,tunnel`; they'll add `CLOUDFLARE_TUNNEL_TOKEN` to `agami.env`). The tunnel still needs a

domain on Cloudflare — it removes the public IP, not the name.

2. **Admin** — first name, last name, work **email** (the email is the admin identity).

3. *(only if they bring their own Postgres)* note it → use profiles `edge` (drops the bundled DB). The

managed `postgresql://…` URL is a **credential**, so do **not** collect it in chat — after the bundle

is written, the user sets `APP_DATABASE_URL` in `agami.env` themselves (the same hand-off as the password).

4. **Which datasource(s)?** — list the models in the artifacts dir (one per profile:

one**, ask: *"You have N datasources — `<names>`. Deploy all, or pick?"* Pass the chosen set as

`--datasources a,b` (omit to deploy all). The server serves **every** datasource you stage, and each needs

its own DSN (Phase 2).

**Confirm where to write the bundle.** Ask: *"Where should I put the deploy bundle? (default `~/agami-deploy`)"*

and use their answer as `--target`. It must **not** be inside the artifacts dir (prepare_deploy rejects that —

it copies the model *out of* artifacts *into* the bundle). Then write it:

```bash

python3 "$AGAMI_PLUGIN_ROOT/scripts/prepare_deploy.py" \

--target <chosen-dir, default ~/agami-deploy> \

--artifacts-dir "<data.artifacts_dir>" \

--public-base-url "https://<host>" \

--admin-email "<email>" --admin-first "<first>" --admin-last "<last>" \

--profiles "bundled-db,edge"

```

**Append these flags to the command when they apply** (add each as another `\`-continued line): `--datasources

"a,b"` to stage a subset of models; on a **version upgrade** `--image-tag "<version>"` to bump it (omit it on a

model-only re-stage so an existing pin isn't changed).

(Use `--profiles "bundled-db,tunnel"` for the tunnel, or `--profiles "edge"` for managed Postgres — then

have the user set `APP_DATABASE_URL` in `agami.env` by hand, never on the command line.)

**Read the status line** and branch on the first token:

- `PREPARED <dir>` — a **fresh** bundle. Go to Phase 2 (fill the secrets).

- `UPGRADED <dir> new_keys=<a,b,…>` — an **existing** bundle upgraded **in place**: every value the user

typed (password, secret, DSN) is kept. If `new_keys` is **non-empty**, this version added settings — tell

the user exactly which to set (e.g. *"this version added `DATASOURCE_URL` — set it in `agami.env` before we

restart"*). If it's **empty**, nothing new is needed. Existing secrets are already there — don't re-ask;

continue to Phase 3 (deploy).

## Phase 2: Hand off the secrets (then end the turn)

**Open the file for them** so they don't have to hunt for it (it's a plain visible file, `agami.env`, in the

bundle dir): `open -t -- "<target>/agami.env"` on macOS (opens it in the default text editor; the `--` stops a

path that starts with `-` being read as a flag); on other platforms

just print the **absolute path**. Then tell the user (do **not** proceed past this in the same turn). These are

credentials — the user types them by hand; you never see them, they stay in the file on their machine:

> Open `<target>/agami.env` (I just opened it for you) and set, then save:

> - **`AGAMI_ADMIN_PASSWORD=`** — a strong admin password.

> - the **warehouse DSN(s)** — the connection string(s) the model queries (the scheme picks the type:

> `postgresql://` `mysql://` `redshift://` `snowflake://…`). *(These live here now — **not** shipped in

> the bundle.)* Name them per the datasource(s) you deployed:

> - **one datasource** → **`DATASOURCE_URL=`** (e.g. `postgresql://<user>:<password>@host:5432/db`).

> - **several** → one per datasource: **`DATASOURCE_URL__<TOKEN>=`**, where `<TOKEN>` is the datasource id

> upper-cased with every non-alphanumeric char turned to `_` (so `sales-pg` → `DATASOURCE_URL__SALES_PG`).

> *(List the exact var names for the datasources they chose in Phase 1.4.)*

> agami only runs read-only SELECTs, so the warehouse user only needs read access — a read-only user is

> safest. Ask for "the read-only grant" and I'll hand you the SQL ([`shared/readonly-grants.md`](../../shared/readonly-grants.md)).

> - *(only if you chose managed Postgres)* **`APP_DATABASE_URL=`** — your Postgres URL.

>

> Then tell me to continue.

End the turn here. The user fills the secrets and re-invokes (or says "continue").

## Phase 3: Finalize + deploy

1. **Validate + generate the signing secret:** `$PY -m deploy_preflight ~/agami-deploy/agami.env`. If it

reports missing inputs (e.g. the password still blank, or a non-https URL), relay them and stop. On

success it has written `AGAMI_SIGNING_SECRET` + derived `AGAMI_PUBLIC_HOST` into the file.

2. **Bring it up:**

- **Docker present here** (the user is on the target host, or testing locally) — run

`cd ~/agami-deploy && ./deploy.sh` (pulls the image + `docker compose up -d`).

- **No Docker / deploying to a remote VM** — hand off: have them copy `~/agami-deploy` to the host

(`scp -r` or a synced folder), then run `./deploy.sh` there. Give them the **cloud checklist** below.

3. **Print the share lines:** the connector URL **`<PUBLIC_BASE_URL>/mcp`** (what teammates add in

claude.ai → Connectors), and the admin console **`<PUBLIC_BASE_URL>/admin`**.

## The cloud steps you can't do (👤 — walk them through it)

- **A VM** (~2 vCPU / 4 GB RAM / 20 GB disk), Ubuntu LTS, **only ports 80 + 443 open** (or the tunnel).

- **DNS:** an **A-record** for their hostname → the VM's public IP. (Skip for the tunnel.)

- **Docker** on the host: `curl -fsSL https://get.docker.com | sudo sh`.

- Then `./deploy.sh` on the host → wait ~30s for Caddy to issue the cert → open `<PUBLIC_BASE_URL>/admin`.

## Re-running later (model update vs version upgrade)

A re-run of `/agami-deploy` over an existing bundle is **non-destructive** — it never touches the secrets the

user typed (`UPGRADED` status); it re-stages the model, appends any settings new in this version, and reports

them as `new_keys`. Two cases:

- **Model update** (they changed the semantic model): re-run **without** `--image-tag` (keeps the pinned

version), then on the host `docker compose restart agami` — the server re-ingests the model on boot. No

rebuild, no DB access.

- **Version upgrade** (a newer agami release): re-run **with** `--image-tag "<version>"` (bumps it), set any

`new_keys` the run reports, then `cd <target> && ./deploy.sh` (pulls the new image + recreates).

## Notes

- This is the **team** path. For a quick local feel of the same tools, that's `agami-serve` (stdio, no

network). For a fully managed, governed, always-on server, that's the hosted product — see

`docs/open-vs-hosted.md`.

- The bundle is self-contained and re-shippable: the generated signing secret lives in its `agami.env`, so a

VM rebuild that re-uses the same bundle keeps every connected Claude working (no reconnect).