@notiamo/runner 0.2.1 → 0.2.2

package/README.md

@@ -27,6 +27,7 @@ From a checkout of the Notiamo repository: `pnpm --filter @notiamo/runner build`
 | `notiamo-runner logs` | The last 50 lines of the log. |
 | `notiamo-runner stop` | Stop the service until the next login or boot. |
 | `notiamo-runner uninstall` | Remove the service (the runner's folder stays). |
+| `notiamo-runner env <projectId>` | Make or show the env file this machine gives the runs of one project (see "Your own projects" below). |
 | `notiamo-runner start` | Run in the foreground. This is what the service runs; you rarely need it. |
 
 The service is a launchd agent `com.notiamo.runner` on macOS, a Scheduled Task "Notiamo runner" (at logon) on
@@ -114,6 +115,43 @@ that arrives while the first still runs here).
 Each run at the same time has its own slot folder, `projects/0`, `projects/1` or `projects/2`, made when the runner
 starts: a run's sandbox cannot read the other slots at all, even a project cloned there after the run began.
 
+## Your own projects: an environment for the runs
+
+A run on a GitHub project gets a clean clone and nothing else. For a client's WordPress site that is all it needs.
+For a SaaS project of your own, the agent also needs to run the tests, and those need a database, a file store, a
+mail catcher and a `.env`. The runner machine gives them to the runs of one project with a plain file:
+
+```sh
+npx @notiamo/runner env <projectId>          # add --profile <name> for a named runner
+```
+
+`<projectId>` is the last part of the project page's address in Notiamo. The command makes
+`~/.notiamo-runner/env/<projectId>.env` (or the profile's `env/` folder), readable by you only, and prints the path.
+Put one `KEY=VALUE` per line (`#` comments, quotes and an `export ` prefix are fine; nothing is expanded). The next
+run of that project gets the variables in its shell, and the agent is told their names (never the values). Remove
+the file to take them away. The file never leaves the machine: Notiamo does not know it exists.
+
+With the file present, the run's shell may also reach services on `127.0.0.1` on macOS: your Postgres, MinIO,
+Mailpit, a dev server. You keep them running (Docker Desktop at login, say); the agent cannot start them, Docker
+stays out of its reach. Point the variables at them, for example `DATABASE_URL=postgres://app:app@127.0.0.1:5450/app_test`.
+On Linux the sandbox gives the shell its own network namespace, so `127.0.0.1` there is not the machine's: bind the
+services to the machine's LAN address and add that host on the Runners card under "Extra hosts". Windows has no
+shell sandbox, so there nothing stands between the shell and `127.0.0.1`.
+
+Rules:
+
+- **Dev and test values only.** The agent runs shell commands and can read every variable. Never a production key,
+  never a password you use elsewhere. Use the project's fake switches (`AI_FAKE=1`, `STRIPE_FAKE=1`…) instead of
+  real services where you can.
+- `PATH`, `HOME`, the proxy and certificate variables (`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`, `NODE_EXTRA_CA_CERTS`,
+  `SSL_CERT_*`), `NODE_OPTIONS`, `NODE_TLS_REJECT_UNAUTHORIZED`, `NOTIAMO_*`, `GIT_*`, `CLAUDE_*` and `ANTHROPIC_*` are
+  ignored (the log says so), and the runner's own variables always win over the file: the file can change what the
+  agent's commands see, never how Claude Code itself talks to Anthropic and Notiamo.
+- Values of 6 characters or more are masked as `[secret]` in the transcript Notiamo receives, like the run's tokens.
+  Short values (`1`, `true`) are not.
+- Keep **Runs at once** at 1 on a runner whose projects share a database through their env file: two runs of one
+  project at the same time would run their tests on the same database.
+
 ## A runner for one client
 
 When you make a runner in Notiamo, you can limit it to one client (workspace). It then takes only that client's runs.