# hermes-deliver — agent guide

**Live URL:** https://hermes-deliver.kobald.com/docs/delivery.md

Publish static sites from the Hermes workspace. No deploy step: write files under a project’s `public/` folder and they are live.

Base URL: `https://hermes-deliver.kobald.com`

## Publish (normal path)

1. Pick a project folder name (letters, numbers, `.`, `_`, `-` only), e.g. `demo`.
2. Put HTML/CSS/JS (and any static assets) in that project’s `public/` directory.
3. Open or `curl` the matching URL.

| On disk (Hermes workspace)                           | Live URL                                                    |
| ---------------------------------------------------- | ----------------------------------------------------------- |
| `/opt/data/workspace/<project>/public/index.html`    | `https://hermes-deliver.kobald.com/<project>/`              |
| `/opt/data/workspace/<project>/public/app.js`        | `https://hermes-deliver.kobald.com/<project>/app.js`        |
| `/opt/data/workspace/<project>/public/css/style.css` | `https://hermes-deliver.kobald.com/<project>/css/style.css` |

Working directory is usually `/opt/data/workspace`, so relative paths look like:

```text
<project>/public/index.html
```

### Example

```bash
mkdir -p /opt/data/workspace/demo/public
cat > /opt/data/workspace/demo/public/index.html <<'EOF'
<!DOCTYPE html>
<html><body><h1>hello</h1></body></html>
EOF

curl -fsS https://hermes-deliver.kobald.com/demo/
```

Files are served immediately from the shared volume. Do not copy into the deliver pod. Do not restart anything for static publishes.

Directories without `index.html` / `index.htm` show an automatic file listing (same for `/docs/` and project `public/` folders). `/` lists projects that have a `public/` folder.

Docs are the shared PVC folder `_docs/` (Hermes path `/opt/data/_docs`). Edit files there; `/docs` serves them directly.

Request a folder as a zip by appending `.zip` to its URL (e.g. `/docs/hermes-worker.zip`). If the zip is missing or older than one day, it is rebuilt from the folder. Directory listings include a `.zip` link next to each folder.

## Rules

- Only the `public/` tree is exposed. Sibling folders under the project (source, notes, `.git`, etc.) are **not** served.
- Project name is the first URL path segment. Do not use `api` as a project name.
- No auth on published files — treat them as public.
- Prefer `index.html` as the entry file so `/<project>/` works.

## Optional: install Node modules on the deliver server

Only when the deliver **server itself** needs a new npm package (not for project frontend deps — those belong in `public/` as static files or a bundler output).

`$DELIVER_API_KEY` is already in the Hermes shell environment.

### Read current package.json deps

```bash
curl -fsS https://hermes-deliver.kobald.com/api/packages \
  -H "Authorization: Bearer $DELIVER_API_KEY"
```

### Merge new dependencies (then pod restarts)

```bash
curl -fsS -X POST https://hermes-deliver.kobald.com/api/packages \
  -H "Authorization: Bearer $DELIVER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dependencies":{"chalk":"^5"}}'
```

Wait for the pod to come back, then verify:

```bash
until curl -fsS https://hermes-deliver.kobald.com/api/health >/dev/null; do sleep 2; done

curl -fsS https://hermes-deliver.kobald.com/api/packages \
  -H "Authorization: Bearer $DELIVER_API_KEY"
```

- `GET/POST /api/packages` require `Authorization: Bearer $DELIVER_API_KEY`.
- `GET /api/health` is public (liveness).
- After `POST /api/packages` the process exits and Kubernetes restarts the pod; `npm install` runs again on start into an ephemeral dir (not the PVC).

## Quick checklist

- [ ] Created `/opt/data/workspace/<project>/public/`
- [ ] Wrote `index.html` (and assets) there
- [ ] Verified with `curl -fsS https://hermes-deliver.kobald.com/<project>/`