amness 0.1.0 → 0.1.2

package/README.md

@@ -5,7 +5,7 @@
 [![CI](https://github.com/amirsdream/Amness/actions/workflows/ci.yml/badge.svg)](https://github.com/amirsdream/Amness/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 ![Node](https://img.shields.io/badge/node-%E2%89%A5%2022.18-339933)
-![Runtime dependencies](https://img.shields.io/badge/runtime%20dependencies-0-brightgreen)
+![Runtime dependencies](https://img.shields.io/badge/required%20dependencies-0-brightgreen)
 
 <p align="center"><img src="docs/images/chat.png" alt="Amness full-screen interface: cards, diff, sidebar, input panel" width="900"></p>
 
@@ -16,12 +16,26 @@
 You need **Node 22.18+**, git, and an API key (OpenAI or Anthropic) or a local model server.
 
 ```bash
-git clone https://github.com/amirsdream/Amness.git && cd Amness && npm install
-export OPENAI_API_KEY=sk-...          # or ANTHROPIC_API_KEY=sk-ant-...
-npm link                              # gives you the `amness` command
-cd ~/your-project && amness           # start a conversation in your project
+npm install -g amness                 # gives you the `amness` command
+cd ~/your-project && amness           # first start: pick a provider and paste your key (see below)
 ```
 
+Or try it without installing: `npx amness`. To run the latest `main` from source (or to work on Amness), see [Run from source](#run-from-source).
+
+### Your API key
+
+Give Amness the key once, in whichever way suits you:
+
+| How | Command or step | Saved? |
+|---|---|---|
+| **Paste it on first start** | run `amness`, choose a provider, paste the key (hidden). Change it later in the settings or with `/provider`. | Yes, in your system's secure store: the macOS Keychain, the Linux keyring, or Windows DPAPI. The prompt tells you which. |
+| **Environment variable** | `export ANTHROPIC_API_KEY=sk-ant-...` or `export OPENAI_API_KEY=sk-...` (PowerShell: `$env:OPENAI_API_KEY="sk-..."`) | No. Used for that shell only, and never written to disk. It wins over a saved key. |
+| **Secret file** (Docker, Kubernetes) | `ANTHROPIC_API_KEY_FILE=/run/secrets/anthropic` (also `OPENAI_API_KEY_FILE`, `TAVILY_API_KEY_FILE`) | No. Read from the file each run. |
+| **Docker** | `docker run -it --rm -v "$PWD":/work -e ANTHROPIC_API_KEY amness` | No. Inside a container nothing is saved. |
+| **Library or CI** | pass `apiKey` in code, or set the variable as a CI secret | No. |
+
+`OPENAI_API_KEY` is used for every provider except Anthropic, including OpenRouter. To remove a saved key, clear "API key" in the settings. A Linux server with no keyring falls back to `~/.amness/config.json` (mode 600, **not encrypted**), so use an environment variable or your platform's secret manager there. Details: [Safety](docs/safety.md).
+
 More ways to start:
 
 ```bash
@@ -33,6 +47,17 @@ amness demo                                                    # a scripted tour
 
 New to it? Follow the [step-by-step guide](docs/getting-started.md). Inside the chat: `/help` lists everything · `Shift+Tab` changes how much it may do without asking · `Ctrl+P` opens the command palette · `@file` attaches a file or image · `!cmd` runs a shell command · `#note` saves a memory.
 
+## Run from source
+
+Use this for the latest `main` (changes not yet released to npm) or to work on Amness itself.
+
+```bash
+git clone https://github.com/amirsdream/Amness.git && cd Amness && npm install
+npm link                              # `amness` now runs your clone; `git pull` updates it
+```
+
+Update the npm version with `npm install -g amness@latest`. Contributors: see [Development](docs/development.md).
+
 ## What it looks like
 
 <p align="center"><img src="docs/images/approval.png" alt="An edit waiting for your approval, with the diff" width="780"></p>
@@ -172,7 +197,7 @@ More plugin ideas (finish gates, policies, loop strategies, custom metrics) are
 | **Evaluate and improve** | `amness eval` (ablations, SWE-bench-format suites, injection suite, leak audit), trace replay, failure mining, `amness tune` (changes kept only if they hold on unseen tasks). |
 | **Works where you work** | Full-screen and inline terminal UI, headless mode, git worktree sessions with `/review` and `/pr`, scheduled runs, a GitHub Action, an editor server (`amness acp`), image input, session branching. |
 
-Models: OpenAI (Responses and Chat), Claude, and any OpenAI-compatible local server. No runtime dependencies.
+Models: OpenAI (Responses and Chat), Claude, and any OpenAI-compatible local server. No required dependencies (the Claude SDK is an optional one that npm installs for you).
 
 ## Choose Amness if, choose something else if
 
@@ -184,7 +209,7 @@ Models: OpenAI (Responses and Chat), Claude, and any OpenAI-compatible local ser
 
 - **Tested:** about 375 automated tests (scripted models, mock servers, real git repositories, a pseudo-terminal), CI on Linux and Windows, and a Docker and npm-package smoke test.
 - **Measured on real models (small):** the guards and the reviewer showed no detectable pass-rate effect on [these tasks and models](docs/evaluation.md#measured-results-so-far); the guards and reviewer cost extra tokens, most visibly on strong models. Every newer feature (routing, `tune`, best-of-n, parallel parts, language-server diagnostics, the approval reviewer) is implemented and unit-tested but **not yet shown to help on real work**. The [roadmap](ROADMAP.md) lists the measurements still to run.
-- **Platforms:** developed on macOS and Linux. Windows runs the test suite but has no OS sandbox. Not on npm yet.
+- **Platforms:** developed on macOS and Linux. Windows runs the test suite but has no OS sandbox. Installed from npm; the Claude SDK comes with it.
 - Cost figures are estimates. Small local models vary widely in tool-calling quality.
 
 ## Documentation

package/dist/cli/amness.js

@@ -16,6 +16,7 @@ import { runSchedule } from "./schedulecli.js";
 import { ACP_HELP, runAcp } from "./acpcli.js";
 import { runEval, runTune } from "./evalcli.js";
 import { CLAUDE_MODELS, OPENAI_MODELS, PROVIDERS, home, loadConfig, mask, ready, saveConfig } from "./config.js";
+import { where } from "./keystore.js";
 import { DEMO_TASK, explain, runDemo } from "./demo.js";
 import { formatEvent } from "./format.js";
 import { Cancel, ask, bold, box, clearScreen, confirm, cyan, dim, gray, green, log, pause, red, select, spin, yellow } from "./ui.js";
@@ -90,7 +91,7 @@ async function ensureReady() {
         cfg.model = (await ask("Model", cfg.model)) || cfg.model;
     }
     if (PROVIDERS[id].needsKey)
-        cfg.apiKey = (await ask("API key (hidden; saved to ~/.amness/config.json, mode 600)", "", { secret: true })) || undefined;
+        cfg.apiKey = (await ask(`API key (hidden; ${where()})`, "", { secret: true })) || undefined;
     saveConfig(cfg);
     if (!ready(cfg))
         return false;
@@ -452,7 +453,7 @@ async function settings() {
             else if (what === "url")
                 cfg.baseUrl = (await ask("Base URL", cfg.baseUrl)) || cfg.baseUrl;
             else if (what === "key")
-                cfg.apiKey = (await ask("API key (hidden; stored in ~/.amness/config.json, mode 600)", cfg.apiKey ?? "", { secret: true })) || undefined;
+                cfg.apiKey = (await ask(`API key (hidden; ${where()})`, cfg.apiKey ?? "", { secret: true })) || undefined;
             else if (what === "tavily")
                 cfg.tavilyKey = (await ask("Tavily API key (blank to clear)", "", { secret: true })) || undefined;
             else if (what === "budget")

package/dist/cli/config.js

@@ -1,6 +1,7 @@
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { deleteSecret, getSecret, noStore, setSecret } from "./keystore.js";
 export const PROVIDERS = {
     anthropic: { label: "Anthropic (Claude)", baseUrl: "https://api.anthropic.com", model: "claude-opus-5-5", needsKey: true },
     openai: { label: "OpenAI", baseUrl: "https://api.openai.com/v1", model: "gpt-6.1-sol", needsKey: true },
@@ -11,30 +12,86 @@ export const PROVIDERS = {
 export const home = () => process.env.AMNESS_HOME ?? join(homedir(), ".amness");
 const file = () => join(home(), "config.json");
 export const defaults = () => ({ provider: "openai", baseUrl: PROVIDERS.openai.baseUrl, model: PROVIDERS.openai.model, maxTokens: 300_000 });
+const SECRETS = ["apiKey", "tavilyKey"];
+/** An environment variable, or the file NAME_FILE points to (Docker and Kubernetes secrets are mounted as files, for example /run/secrets/openai). */
+const envSecret = (name) => {
+    const v = process.env[name];
+    if (v)
+        return v;
+    const f = process.env[`${name}_FILE`];
+    if (!f)
+        return undefined;
+    try {
+        return readFileSync(f, "utf8").trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+let fromEnv = {};
 export function loadConfig() {
-    let c = defaults();
+    let c = defaults(), onDisk = {};
     try {
         if (existsSync(file()))
-            c = { ...c, ...JSON.parse(readFileSync(file(), "utf8")) };
+            onDisk = JSON.parse(readFileSync(file(), "utf8"));
+        c = { ...c, ...onDisk };
     }
     catch { /* corrupt config: start fresh */ }
-    // environment wins, so CI and one-off runs work without touching the saved file
+    // keys live in the OS credential store when there is one; a key still in the file (an older version wrote it there) is moved over, and removed from the file only after it reads back
+    let migrated = false;
+    for (const k of SECRETS) {
+        const stored = getSecret(k);
+        if (stored) {
+            c[k] = stored;
+            if (onDisk[k]) {
+                delete onDisk[k];
+                migrated = true;
+            }
+        }
+        else if (onDisk[k] && setSecret(k, onDisk[k])) {
+            delete onDisk[k];
+            migrated = true;
+        }
+    }
+    if (migrated)
+        writeConfigFile({ ...defaults(), ...onDisk, ...Object.fromEntries(SECRETS.map((k) => [k, undefined])) });
+    // environment wins, so CI and one-off runs work without touching the saved key. It is never written back (see saveConfig).
     const claude = c.provider === "anthropic";
-    const key = claude ? process.env.ANTHROPIC_API_KEY : process.env.OPENAI_API_KEY;
+    fromEnv = {};
+    const key = envSecret(claude ? "ANTHROPIC_API_KEY" : "OPENAI_API_KEY");
     if (key)
-        c.apiKey = key;
-    if (process.env.TAVILY_API_KEY)
-        c.tavilyKey = process.env.TAVILY_API_KEY;
+        c.apiKey = fromEnv.apiKey = key;
+    const tavily = envSecret("TAVILY_API_KEY");
+    if (tavily)
+        c.tavilyKey = fromEnv.tavilyKey = tavily;
     if (process.env.OPENAI_BASE_URL && !claude)
         c.baseUrl = process.env.OPENAI_BASE_URL;
     if (process.env.AMNESS_MODEL)
         c.model = process.env.AMNESS_MODEL;
     return c;
 }
-export function saveConfig(c) {
+function writeConfigFile(c) {
     mkdirSync(home(), { recursive: true });
-    writeFileSync(file(), JSON.stringify(c, null, 2));
-    chmodSync(file(), 0o600); // may hold API keys
+    writeFileSync(file(), JSON.stringify(c, null, 2), { mode: 0o600 }); // owner-only from the first byte
+    chmodSync(file(), 0o600); // and for a file that already existed
+}
+export function saveConfig(c) {
+    const out = { ...c };
+    for (const k of SECRETS) {
+        const v = c[k];
+        if (v && v === fromEnv[k]) {
+            delete out[k];
+            continue;
+        } // this value came from an environment variable: do not store it
+        if (!v) {
+            deleteSecret(k);
+            delete out[k];
+            continue;
+        }
+        if (setSecret(k, v) || noStore())
+            delete out[k]; // stored in the OS credential store; otherwise it stays in the file (mode 600), except in a container, where it is kept in memory only
+    }
+    writeConfigFile(out);
 }
 export const ready = (c) => !PROVIDERS[c.provider].needsKey || !!c.apiKey;
 export const mask = (k) => (k ? k.slice(0, 3) + "…" + k.slice(-4) : "not set");

package/dist/cli/keystore.d.ts

@@ -0,0 +1,9 @@
+export type Backend = "keychain" | "secret-service" | "dpapi" | "file" | "none";
+export declare function backend(): Backend;
+export declare const where: () => string;
+/** True when keys must never be written to disk (containers). */
+export declare const noStore: () => boolean;
+/** Save a secret. Returns false when the OS store is not available or refused, so the caller can fall back to the file. */
+export declare function setSecret(name: string, value: string): boolean;
+export declare function getSecret(name: string): string | undefined;
+export declare function deleteSecret(name: string): void;

package/dist/cli/keystore.js

@@ -0,0 +1,108 @@
+// Where API keys live. macOS: the login Keychain. Linux: the desktop secret service (`secret-tool`). Windows: DPAPI, which encrypts the key so only your Windows user on this machine can decrypt it.
+// If the OS store is missing or refuses (a Linux server or Docker image with no keyring), the key stays in the config file with mode 600, and `where()` says so.
+// The key goes to the OS tool on stdin, never on the command line (a command line is visible to other users in `ps`), and is hex-encoded so no quoting can go wrong.
+// Tests and any run with a custom AMNESS_HOME use the file, so they never touch your real store. AMNESS_KEYSTORE=file|keychain|secret-service|dpapi|none forces one.
+// In a container (Docker, Kubernetes) nothing is saved at all ("none"): pass the key as an environment variable or a secret file (see config.ts), so it is never written into an image or a volume.
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const SERVICE = process.env.AMNESS_KEYSTORE_SERVICE || "amness"; // the override is for tests
+const run = (cmd, args, input, timeout = 10_000, env) => {
+    try {
+        const r = spawnSync(cmd, args, { input, encoding: "utf8", timeout, env });
+        return r.error ? undefined : r;
+    }
+    catch {
+        return undefined;
+    }
+};
+export function backend() {
+    const want = process.env.AMNESS_KEYSTORE;
+    if (want === "file" || (!want && process.env.AMNESS_HOME))
+        return "file";
+    if (want === "keychain" || want === "secret-service" || want === "dpapi" || want === "none")
+        return want;
+    if (process.platform === "linux" && (existsSync("/.dockerenv") || process.env.KUBERNETES_SERVICE_HOST))
+        return "none";
+    if (process.platform === "darwin")
+        return "keychain";
+    if (process.platform === "win32")
+        return "dpapi";
+    if (process.platform === "linux" && run("secret-tool", ["--version"])?.status !== undefined)
+        return "secret-service";
+    return "file";
+}
+export const where = () => ({ keychain: "saved in the macOS Keychain", "secret-service": "saved in the system keyring (secret-tool)", dpapi: "saved with Windows encryption (DPAPI, this user only)", file: "saved in ~/.amness/config.json, mode 600, not encrypted", none: "not saved: this is a container, so pass the key as an environment variable or a secret file (OPENAI_API_KEY_FILE / ANTHROPIC_API_KEY_FILE)" })[backend()];
+/** True when keys must never be written to disk (containers). */
+export const noStore = () => backend() === "none";
+// Windows: PowerShell turns the key into an encrypted string that only this Windows user on this machine can decrypt (DPAPI). The string is kept in ~/.amness/secrets/<name>.dpapi.
+const dir = () => join(process.env.AMNESS_HOME ?? join(homedir(), ".amness"), "secrets");
+const blob = (name) => join(dir(), `${name}.dpapi`);
+// A parent PowerShell 7 (pwsh) leaves a PSModulePath that Windows PowerShell 5.1 cannot load its Security module from; dropping it lets 5.1 use its own default.
+const psEnv = () => { const e = { ...process.env }; for (const k of Object.keys(e))
+    if (k.toLowerCase() === "psmodulepath")
+        delete e[k]; return e; };
+const ps = (script, input) => run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], input, 60_000, psEnv()); // Windows PowerShell can take several seconds to start
+const PS_ENCRYPT = "$p = [Console]::In.ReadToEnd().Trim(); ConvertTo-SecureString $p -AsPlainText -Force | ConvertFrom-SecureString";
+const PS_DECRYPT = "$e = [Console]::In.ReadToEnd().Trim(); $s = ConvertTo-SecureString $e; [Runtime.InteropServices.Marshal]::PtrToStringBSTR([Runtime.InteropServices.Marshal]::SecureStringToBSTR($s))";
+const hex = (s) => Buffer.from(s, "utf8").toString("hex");
+const unhex = (s) => Buffer.from(s.trim(), "hex").toString("utf8");
+/** Save a secret. Returns false when the OS store is not available or refused, so the caller can fall back to the file. */
+export function setSecret(name, value) {
+    const b = backend();
+    if (b === "file" || b === "none")
+        return false;
+    if (b === "dpapi") {
+        const r = ps(PS_ENCRYPT, hex(value));
+        if (r?.status !== 0 || !r.stdout.trim())
+            return false;
+        try {
+            mkdirSync(dir(), { recursive: true });
+            writeFileSync(blob(name), r.stdout.trim(), { mode: 0o600 });
+        }
+        catch {
+            return false;
+        }
+        return getSecret(name) === value;
+    }
+    if (b === "keychain") {
+        const r = run("security", ["-i"], `add-generic-password -U -s ${SERVICE} -a ${name} -w ${hex(value)}\n`);
+        return r?.status === 0 && !/error|fail/i.test(r.stderr ?? "") && getSecret(name) === value;
+    }
+    const r = run("secret-tool", ["store", `--label=amness ${name}`, "service", SERVICE, "account", name], hex(value));
+    return r?.status === 0 && getSecret(name) === value;
+}
+export function getSecret(name) {
+    const b = backend();
+    if (b === "file" || b === "none")
+        return undefined;
+    if (b === "dpapi") {
+        if (!existsSync(blob(name)))
+            return undefined;
+        const r = ps(PS_DECRYPT, readFileSync(blob(name), "utf8"));
+        const v = r?.status === 0 ? unhex(r.stdout) : "";
+        return v || undefined;
+    }
+    const r = b === "keychain" ? run("security", ["find-generic-password", "-s", SERVICE, "-a", name, "-w"]) : run("secret-tool", ["lookup", "service", SERVICE, "account", name]);
+    if (r?.status !== 0 || !r.stdout.trim())
+        return undefined;
+    const v = unhex(r.stdout);
+    return v || undefined;
+}
+export function deleteSecret(name) {
+    const b = backend();
+    if (b === "file" || b === "none")
+        return;
+    if (b === "dpapi") {
+        try {
+            rmSync(blob(name), { force: true });
+        }
+        catch { /* already gone */ }
+        return;
+    }
+    if (b === "keychain")
+        run("security", ["delete-generic-password", "-s", SERVICE, "-a", name]);
+    else
+        run("secret-tool", ["clear", "service", SERVICE, "account", name]);
+}

package/dist/cli/tui/commands.js

@@ -4,6 +4,7 @@ import { SHELL_CHOICES, STRATEGIES, chooseShell, currentShell, loadPrompts, setS
 import { join, resolve } from "node:path";
 import { collectFiles, effortsFor, loadMcp, readBundle, writeBundle } from "../../src/index.js";
 import { CLAUDE_MODELS, OPENAI_MODELS, PROVIDERS } from "../config.js";
+import { where } from "../keystore.js";
 import { bold, cyan, dim, green, red, yellow } from "../ui.js";
 import { estimateCost, fmtCost, fmtDuration, fmtTokens } from "./pricing.js";
 import { codeBlocks } from "./clipboard.js";
@@ -48,7 +49,7 @@ export function buildCommands() {
                 const key = id === "anthropic" ? process.env.ANTHROPIC_API_KEY : process.env.OPENAI_API_KEY;
                 let apiKey = key;
                 if (PROVIDERS[id].needsKey && !apiKey) {
-                    apiKey = await a.askText(`${PROVIDERS[id].label} API key (hidden; stored in ~/.amness/config.json, mode 600)`, { secret: true });
+                    apiKey = await a.askText(`${PROVIDERS[id].label} API key (hidden; ${where()})`, { secret: true });
                     if (!apiKey)
                         return;
                 }

package/dist/src/anthropic.d.ts

@@ -1,6 +1,6 @@
 import type { Message, Model } from "./harness.ts";
 /**
- * Claude backend via the official Anthropic SDK (an optional peer dependency: `npm i @anthropic-ai/sdk`).
+ * Claude backend via the official Anthropic SDK (an optional dependency, installed with the package: `npm i @anthropic-ai/sdk` if it is missing).
  * Defaults follow Anthropic's guidance for agent loops: adaptive thinking, auto prompt caching, streaming,
  * server-side refusal fallbacks. Credentials: `apiKey`, ANTHROPIC_API_KEY, or an `ant auth login` profile.
  */

package/docs/architecture.md

@@ -87,7 +87,7 @@ flowchart TB
 
 **Limits.** The diagrams show the main paths only. Many small files in `src/` (for example `permissions.ts`, `hooks.ts`, `sandbox.ts`) are called by the agent layer and are not drawn.
 
-The runtime has no required packages. The Claude adapter needs the optional package `@anthropic-ai/sdk`.
+The runtime has no required packages. The Claude adapter uses the optional dependency `@anthropic-ai/sdk`, which npm installs with Amness.
 
 ## Find which file does what
 

package/docs/bench.md

@@ -44,16 +44,15 @@ Do these steps in PowerShell.
 
 2. Install [Git for Windows](https://git-scm.com/download/win). The bench needs `git` on your PATH. The hidden checks of the built-in tasks use bash tools such as `test`. Amness looks for the `bash.exe` that comes with Git (in `Program Files\Git\bin`) and for any `bash.exe` on PATH. It skips `C:\Windows\System32\bash.exe`, because that is the WSL launcher and it sees other files (see `src/shell.ts`).
 
-3. Download Amness and install its packages:
+3. Install Amness from npm:
 
    ```powershell
-   git clone https://github.com/amirsdream/Amness.git
-   cd Amness
-   npm install
-   npm link
+   npm install -g amness
    amness --version
    ```
 
+   To bench the latest `main` instead of the release, install from a clone: `git clone https://github.com/amirsdream/Amness.git`, then `cd Amness`, `npm install` and `npm link`.
+
 4. Install and log in to the other tools yourself. Follow their own documentation. This page does not repeat install commands, because they change.
    - Claude Code: <https://docs.claude.com/en/docs/claude-code>
    - Codex: <https://github.com/openai/codex>

package/docs/development.md

@@ -70,7 +70,7 @@ The file `.github/workflows/ci.yml` has these jobs:
 | `windows` | `npm run typecheck` and `npm test` on Windows. It is informational (`continue-on-error`) |
 | `action` | runs the GitHub Action (`action.yml`) with no API key and checks that it reports instead of crashing |
 
-A second workflow, `.github/workflows/publish.yml`, runs type check and tests, then `npm publish`, when you push a tag that starts with `v`. It needs an `NPM_TOKEN` secret. Whether the package is published on npm is not verified here.
+A second workflow, `.github/workflows/publish.yml`, runs type check and tests, then `npm stage publish --provenance`, when you push a tag that starts with `v`. It needs an `NPM_TOKEN` secret (a stage-only token is enough). It only stages the version; you release it with `npm stage approve <id>` and your 2FA code.
 
 ## Find your way around the project
 

package/docs/getting-started.md

@@ -13,21 +13,19 @@ You need Node.js 22.18 or newer, git, and a terminal. A *diff* is a view of the
 
 ## 1. Install Amness
 
-Amness is **not on npm yet**. You install it from the source code.
+Amness is a package on npm. You install it with one command.
 
-1. Download the code and install its packages.
+1. Install it. The `-g` flag makes the `amness` command available in every folder.
 
    ```bash
-   git clone https://github.com/amirsdream/Amness.git && cd Amness && npm install
+   npm install -g amness
    ```
 
-2. Create the `amness` command.
+   This also installs the Anthropic SDK, which the Claude models use. It is an optional dependency, so Amness still installs if the SDK cannot. If you see "Claude support needs the SDK", run `npm install -g @anthropic-ai/sdk`.
 
-   ```bash
-   npm link
-   ```
+   You can also run Amness once without installing it: `npx amness`.
 
-3. Check that the command works.
+2. Check that the command works.
 
    ```bash
    amness --version
@@ -35,6 +33,17 @@ Amness is **not on npm yet**. You install it from the source code.
 
    You see a version number, for example `0.1.0`.
 
+To update later, run `npm install -g amness@latest`.
+
+**Run the latest `main` from source.** Use this if you want a change that is not released yet, or if you want to work on Amness itself:
+
+```bash
+git clone https://github.com/amirsdream/Amness.git && cd Amness && npm install
+npm link
+```
+
+`npm link` makes the `amness` command point at your clone, so `git pull` updates it.
+
 Amness is developed on macOS and Linux. The tests also run on Windows, but Windows has **no OS sandbox** for shell commands.
 
 ## 2. Set an API key or choose a local model
@@ -57,7 +66,7 @@ ollama pull qwen2.5-coder:7b
 
 Start Amness, run `/provider`, and choose "Ollama (local)". You need no key. Small local models can be weak at tool calling. See [Providers and models](providers.md).
 
-You can also do nothing now. On the first start, Amness asks you to pick a provider and paste a key. It saves the key in `~/.amness/config.json`, where only you can read it.
+You can also do nothing now. On the first start, Amness asks you to pick a provider and paste a key. It saves the key in your system's secure store (the macOS Keychain, the Linux keyring, or Windows DPAPI) and tells you which one. See [Safety](safety.md) for the details and for servers that have no keyring.
 
 ## 3. Start in a project
 

package/docs/headless.md

@@ -166,7 +166,12 @@ You see one line on stderr for each attempt, for example `attempt 1: failed veri
 
 ## Docker and GitHub Actions
 
-- A `Dockerfile` is included: `docker build -t amness .`, then `docker run -it --rm -v "$PWD":/work -e ANTHROPIC_API_KEY amness`. The old version of this page said it has not been built or tested. The README lists a Docker smoke test. **Not verified:** which of the two is right.
+- A `Dockerfile` is included: `docker build -t amness .`, then `docker run -it --rm -v "$PWD":/work -e ANTHROPIC_API_KEY amness`. CI builds the image and runs `--version` and a self-test in it (see [Development](development.md)).
+- **Keys in Docker.** Inside a container Amness never saves a key to disk. Pass it in one of two ways:
+  - an environment variable: `-e ANTHROPIC_API_KEY` (with no value, Docker copies it from your shell, so it is not typed on the command line);
+  - a Docker secret, which is mounted as a file: `-e ANTHROPIC_API_KEY_FILE=/run/secrets/anthropic`. `OPENAI_API_KEY_FILE` and `TAVILY_API_KEY_FILE` work the same way.
+
+  The image sets `AMNESS_KEYSTORE=none`. Amness also detects `/.dockerenv` and Kubernetes on its own. If you type a key into the chat in a container, it is used for that session only.
 - The repository has a GitHub Action in `action.yml`. Its inputs are `task`, `verify`, `provider`, `model`, `max-tokens` and `comment`. See [Features: Scheduled runs and the GitHub Action](features.md#scheduled-runs-and-the-github-action).
 
 ## Related pages

package/docs/library.md

@@ -17,34 +17,25 @@ Everything is exported from `src/index.ts`. The code samples on this page were t
 
 **Why you would use it.** You get the same guards as the chat (argument checks, verify gate, loop guard, budgets) inside a script, a server or a test.
 
-**How to use it.** The README says Amness is not on npm yet, and this page could not confirm a release. Use a clone.
-
-1. Clone and build:
-
-```bash
-git clone https://github.com/amirsdream/Amness.git
-cd Amness
-npm install
-npm run build
-npm pack
-```
+**How to use it.**
 
-2. Install the tarball in your own project:
+1. Install the package in your own project:
 
 ```bash
-cd ../my-project
-npm install ../Amness/amness-0.1.0.tgz
+npm install amness
 ```
 
-3. Or skip the build and import the source from the clone. Node.js can run `.ts` files:
+2. Import what you need:
 
 ```ts
-import { createCodeAgent, openai } from "../Amness/src/index.ts";
+import { createCodeAgent, openai } from "amness";
 ```
 
-The CI job `package` does steps 1 and 2 and checks that `import("amness")` works.
+To use the latest `main` before it is released, clone the repository, run `npm install && npm run build && npm pack`, and install the tarball it makes with `npm install ../Amness/amness-<version>.tgz`. You can also import the source directly, because Node.js can run `.ts` files: `import { createCodeAgent, openai } from "../Amness/src/index.ts";`.
+
+The CI job `package` packs the tarball, installs it in a new folder, and checks that `import("amness")` works.
 
-**Limits.** The Claude adapter needs the optional package `@anthropic-ai/sdk` (`npm install @anthropic-ai/sdk`). The OpenAI adapter uses plain `fetch` and has no dependency.
+**Limits.** The Claude adapter uses the optional dependency `@anthropic-ai/sdk`, which `npm install amness` adds for you (if it is missing, run `npm install @anthropic-ai/sdk`). The OpenAI adapter uses plain `fetch` and has no dependency.
 
 ## Run a coding agent
 

package/docs/providers.md

@@ -64,7 +64,7 @@ The model list in `/model` (with prices per million tokens as shown in the picke
 
 **Limits and common problems.**
 
-- Amness saves a key you type in `~/.amness/config.json` with file mode 600 (only you can read it).
+- Amness saves a key you type in your system's secure store: the macOS Keychain, the Linux keyring (`secret-tool`) or Windows DPAPI. In Docker or Kubernetes it saves nothing: pass the key as an environment variable or a `*_FILE` secret. On a Linux server with no keyring it uses `~/.amness/config.json` with file mode 600, which is not encrypted. See [Safety](safety.md).
 - The environment variable wins over the saved file. `ANTHROPIC_API_KEY` is used when the provider is `anthropic`. `OPENAI_API_KEY` is used for **every other provider**, including `openrouter`. `OPENROUTER_API_KEY` is not read as a key.
 - If the chat says "check your key with /provider", the provider answered with an authentication error (401 or 403).
 - The test call checks that the model replies. It does not check that the model can call tools.

package/docs/safety.md

@@ -35,7 +35,20 @@ Notes about the provider:
 
 ## Know where your keys are stored
 
-- Keys come from the environment variables `OPENAI_API_KEY` and `ANTHROPIC_API_KEY`, or from `~/.amness/config.json`. Amness writes that file with mode 600. Only your user can read it.
+- Keys come from the environment variables `OPENAI_API_KEY` and `ANTHROPIC_API_KEY`, or from the key store. A key from an environment variable is used for that run and is never saved.
+- The key store depends on your system. The prompt tells you which one is in use.
+
+  | System | Where the key is saved | Protection |
+  |---|---|---|
+  | macOS | the login Keychain (service `amness`) | encrypted by macOS |
+  | Linux with a desktop keyring | the secret service, through `secret-tool` | encrypted by the keyring |
+  | Windows | `~/.amness/secrets/apiKey.dpapi` | encrypted with DPAPI: only your Windows user on this machine can decrypt it |
+  | Docker or Kubernetes | nowhere: kept in memory for that run | nothing is written to the image or a volume. Pass the key as an environment variable or a secret file (`ANTHROPIC_API_KEY_FILE=/run/secrets/anthropic`). |
+  | Linux server with no keyring | `~/.amness/config.json` with mode 600 | **not encrypted**, only your user can read it. Prefer an environment variable or your platform's secret manager. |
+
+- Amness passes the key to the system tool on standard input, never on the command line, where other users could see it in the process list.
+- A key that an older version saved in `config.json` is moved to the key store the next time you start Amness, and removed from the file once the move is checked.
+- To remove a saved key, open the settings and clear "API key", or on macOS run `security delete-generic-password -s amness -a apiKey`.
 - The environment variable wins over the saved key.
 - Amness does not write keys into a project folder.
 - Commands the agent runs do not get your Amness keys. The variables `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `TAVILY_API_KEY`, `OPENROUTER_API_KEY` and `AMNESS_OTLP` are removed from their environment (`childEnv` in `src/secrets.ts`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amness",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "description": "A terminal coding agent for any model: streaming chat TUI, permission modes, plan mode, undo, memory, MCP, with a small reliability harness underneath. OpenAI (Responses API), Claude, and local models.",
   "license": "MIT",
@@ -52,19 +52,13 @@
     "test:pty": "python3 test/pty/tui.py",
     "prepack": "npm run build"
   },
+  "optionalDependencies": {
+    "@anthropic-ai/sdk": "^1.3.0"
+  },
   "devDependencies": {
-    "@anthropic-ai/sdk": "^1.3.0",
     "@types/node": "^22.0.0",
     "typescript": "^5.8.0"
   },
-  "peerDependencies": {
-    "@anthropic-ai/sdk": "^1.3.0"
-  },
-  "peerDependenciesMeta": {
-    "@anthropic-ai/sdk": {
-      "optional": true
-    }
-  },
   "files": [
     "dist",
     "docs",