agent-message 0.1.2 → 0.1.4

package/README.md

@@ -1,5 +1,11 @@
 # Agent Message
 
+```bash
+npx skills add https://github.com/siisee11/agent-message --skill agent-message-cli
+```
+
+Install the skill above, then ask your coding agent (e.g. Claude Code) to "set up agent-message" — it will handle installation and configuration for you.
+
 ```bash
 npm install -g agent-message
 ```
@@ -25,7 +31,10 @@ Default ports:
 - API: `127.0.0.1:45180`
 - Web: `127.0.0.1:45788`
 
+For self-hosted local use, `agent-message start` creates and uses a local SQLite database by default.
+Managed cloud deployments should run the server with `DB_DRIVER=postgres` and `POSTGRES_DSN`.
 After `agent-message start`, open `http://127.0.0.1:45788` in your browser.
+The bundled CLI uses `https://am.namjaeyoun.com` by default unless you override `server_url` for self-hosting.
 The bundled CLI continues to work from the same command:
 
 ```bash
@@ -36,6 +45,12 @@ agent-message open bob
 agent-message send bob "hello"
 ```
 
+Port conventions:
+- `8080`: source server default (`cd server && go run .`) and server container port
+- `45180`: local API port used by `agent-message start`
+- `45788`: local web gateway port used by `agent-message start`, `--with-tunnel`, and the containerized gateway
+- `5173`: Vite dev server only
+
 You can override the runtime location and ports when needed:
 
 ```bash
@@ -44,6 +59,12 @@ agent-message status --runtime-dir /tmp/agent-message --api-port 28080 --web-por
 agent-message stop --runtime-dir /tmp/agent-message
 ```
 
+Web Push for installed PWA notifications:
+- `agent-message start` automatically creates and reuses a local VAPID keypair.
+- The generated config is stored in `<runtime-dir>/web-push.json`.
+- To override it, set `WEB_PUSH_VAPID_PUBLIC_KEY`, `WEB_PUSH_VAPID_PRIVATE_KEY`, and optionally `WEB_PUSH_SUBJECT` before `agent-message start`.
+- iPhone web push needs the app to be installed from a public HTTPS origin. For local development, use `agent-message start --with-tunnel`; otherwise use a deployed HTTPS host.
+
 PWA install:
 - Open the deployed web app in Safari on iPhone.
 - Use `Share -> Add to Home Screen`.
@@ -53,6 +74,14 @@ PWA install:
 
 This section covers local development and local production-like testing from a checked-out repository.
 
+To expose the checked-out repository on your `PATH` as `agent-message`, run:
+
+```bash
+npm link
+```
+
+That symlinks this checkout's `npm/bin/agent-message.mjs`, so `agent-message ...` uses your local source tree.
+
 ## Prerequisites
 
 - Go `1.26+`
@@ -74,15 +103,20 @@ Default server settings:
 - `SQLITE_DSN=./agent_message.sqlite`
 - `UPLOAD_DIR=./uploads`
 - `CORS_ALLOWED_ORIGINS=*`
+- `WEB_PUSH_VAPID_PUBLIC_KEY`, `WEB_PUSH_VAPID_PRIVATE_KEY`, `WEB_PUSH_SUBJECT` are optional, but required if you want push notifications when running `go run .` directly
 
 Example override:
 
 ```bash
 cd server
-DB_DRIVER=sqlite SQLITE_DSN=./dev.sqlite UPLOAD_DIR=./uploads go run .
+DB_DRIVER=sqlite SQLITE_DSN=./dev.sqlite UPLOAD_DIR=./uploads \
+WEB_PUSH_VAPID_PUBLIC_KEY=... \
+WEB_PUSH_VAPID_PRIVATE_KEY=... \
+WEB_PUSH_SUBJECT=mailto:you@example.com \
+go run .
 ```
 
-### Option B: Local production-like stack (Server + PostgreSQL)
+### Local production-like stack (Server + PostgreSQL)
 
 ```bash
 docker compose up --build
@@ -106,6 +140,47 @@ To also remove persisted DB/uploads volumes:
 docker compose down -v
 ```
 
+## Home Server Container Deploy
+
+For a home Mac server, you can run the managed-cloud stack entirely with containers. The `gateway` image builds `web/dist` during `docker compose build`, so you do not need to run `npm run build` on the host first.
+
+1. Copy the example env file and fill in your values:
+
+```bash
+cp .env.home.example .env.home
+```
+
+Required values:
+- `APP_HOSTNAME`
+- `POSTGRES_PASSWORD`
+- `CLOUDFLARE_TUNNEL_TOKEN`
+
+Web push keys are optional in `.env.home`.
+- If `WEB_PUSH_VAPID_PUBLIC_KEY` / `WEB_PUSH_VAPID_PRIVATE_KEY` are blank, the server container generates them on first boot and stores them in the `web_push_data` volume.
+- If `WEB_PUSH_SUBJECT` is blank, it defaults to `https://<APP_HOSTNAME>`.
+- On startup, the server container normalizes ownership for the `uploads` and `web_push_data` volumes before dropping privileges to the unprivileged `app` user.
+
+2. Start the stack:
+
+```bash
+docker compose --env-file .env.home -f docker-compose.home.yml up -d --build
+```
+
+3. Check status:
+
+```bash
+docker compose --env-file .env.home -f docker-compose.home.yml ps
+docker compose --env-file .env.home -f docker-compose.home.yml logs -f
+```
+
+The home-server stack includes:
+- `postgres`
+- `server`
+- `gateway`
+- `cloudflared`
+
+No host port needs to be exposed on the Mac. Public traffic should come through Cloudflare Tunnel.
+
 ## Web Quickstart
 
 ```bash
@@ -131,33 +206,36 @@ cd web
 npm run build
 ```
 
-## Local Bundle Commands
+## Local Lifecycle Commands
 
-From the project root, you can start the SQLite-backed API server and the production-like local web gateway together:
+From a checked-out repo, use the same lifecycle command as the packaged app, but add `--dev` to build from the local source tree before launch:
 
 ```bash
-./dev-up
+agent-message start --dev
 ```
 
 This will:
 - build `web/dist`
 - build the Go server binary into `~/.agent-message/bin`
-- start the API on `127.0.0.1:18080`
-- start the local web gateway on `127.0.0.1:8788`
+- start the API on `127.0.0.1:45180`
+- start the local web gateway on `127.0.0.1:45788`
 
 To stop both processes:
 
 ```bash
-./dev-stop
+agent-message stop --dev
 ```
 
 If you also want to start or stop the named tunnel that serves `https://agent.namjaeyoun.com`, use:
 
 ```bash
-./dev-up --with-tunnel
-./dev-stop --with-tunnel
+agent-message start --dev --with-tunnel
+agent-message stop --dev
 ```
 
+`--with-tunnel` assumes the default web listener `127.0.0.1:45788`, because the checked-in Cloudflare config points there.
+Use `--with-tunnel` when testing iPhone push notifications from a local checkout; without a public HTTPS origin, Safari-installed PWAs will not receive web push reliably.
+
 When publishing from the repo, `npm pack` / `npm publish` will run the package `prepack` hook, which:
 - builds `web/dist`
 - bundles `deploy/agent_gateway.mjs`
@@ -179,12 +257,12 @@ npx skills add https://github.com/siisee11/agent-message --skill agent-message-c
 
 ## CLI Quickstart
 
-Run from `cli/` with optional `--server-url` override.
+Run from `cli/`. By default the CLI talks to `https://am.namjaeyoun.com`. For self-hosting, pass `--server-url` or set `server_url` in config.
 
 ```bash
 cd cli
-go run . --server-url http://localhost:8080 register alice 1234
-go run . --server-url http://localhost:8080 login alice 1234
+go run . register alice 1234
+go run . login alice 1234
 go run . profile list
 go run . profile switch alice
 ```
@@ -193,25 +271,28 @@ Common commands:
 
 ```bash
 # Conversations
-go run . --server-url http://localhost:8080 ls
-go run . --server-url http://localhost:8080 open bob
+go run . ls
+go run . open bob
 
 # Messaging
-go run . --server-url http://localhost:8080 send bob "hello"
-go run . --server-url http://localhost:8080 read bob --n 20
-go run . --server-url http://localhost:8080 edit 1 "edited text"
-go run . --server-url http://localhost:8080 delete 1
+go run . send bob "hello"
+go run . send bob --attach ./screenshot.png
+go run . send bob "see attached" --attach ./screenshot.png
+go run . read bob --n 20
+go run . edit 1 "edited text"
+go run . delete 1
 
 # Reactions
-go run . --server-url http://localhost:8080 react 1 👍
-go run . --server-url http://localhost:8080 unreact 1 👍
+go run . react 1 👍
+go run . unreact 1 👍
 
 # Realtime watch
-go run . --server-url http://localhost:8080 watch bob
+go run . watch bob
 ```
 
 CLI config is stored at `~/.agent-message/config` by default.
 Each successful `login` or `register` also saves a named profile, and `go run . profile switch <username>` swaps the active account locally.
+For a self-hosted server, set `server_url` once with `go run . config set server_url http://localhost:8080` or use `--server-url` per command.
 
 ## Validation and Constraints (Phase 7)