@atbash/sdk 0.10.13-dev.0 → 0.11.0

package/LICENSE

@@ -1,28 +1,202 @@
-Atbash CLI — Proprietary Software License
-
-Copyright (c) 2026 Atbash,
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
-
-1. Redistributions of source code must retain the above copyright notice, this
-   list of conditions and the following disclaimer.
-2. Redistributions in binary form must reproduce the above copyright notice,
-   this list of conditions and the following disclaimer in the documentation
-   and/or other materials provided with the distribution.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
-ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
-ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
-(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
-ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
-SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
-The views and conclusions contained in the software and documentation are those
-of the authors and should not be interpreted as representing official policies,
-either expressed or implied, Atbash.
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,10 @@
+@atbash/sdk
+Copyright 2026 Atbash Technologies Ltd.
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).
+Versions published before this change remain available under the license
+they were released with.
+
+This package bundles third-party components (the Rust crates in the native
+addon and the npm packages inlined into dist/). They and their licenses are
+listed in THIRD-PARTY-NOTICES.

package/README.md

@@ -29,18 +29,15 @@ const result = await atbash.judgeAction(
   "Outbound AML check — new recipient, over threshold",
 );
 
-// 3. Enforce the verdict
-switch (result.verdict) {
-  case "ALLOW":
-    // Proceed with the action
-    break;
-  case "HOLD":
-    // Held — operator must approve in the dashboard
-    console.log("Held for review:", result.toolCallId);
-    break;
-  case "BLOCK":
-    // Refused — agent is jailed in Enforcement tier
-    throw new Error(`Blocked: ${result.reason}`);
+// 3. Act on the decision. `allow` is the gate; `verdict` says why.
+if (result.allow) {
+  // Proceed with the action
+} else if (result.verdict === "HOLD") {
+  // Held — operator must approve in the dashboard
+  console.log("Held for review:", result.toolCallId);
+} else {
+  // Refused — agent is jailed in Enforcement tier
+  throw new Error(`Blocked: ${result.reason}`);
 }
 ```
 
@@ -63,15 +60,15 @@ Two ways to create an agent:
 
    ```ts
    import { generateKeypair } from "@atbash/sdk";
-   const { privKey, pubKey } = generateKeypair();
-   console.log("Save this private key somewhere safe:", privKey);
+   const { priv_key, pub_key } = generateKeypair();
+   console.log("Save this private key somewhere safe:", priv_key);
    ```
 
    Paste the public key into the **Onboard agent** form on the dashboard, assign it to an org, and attach a policy pack before calling `judgeAction`.
 
 ## Secret storage
 
-- Load the private key from an environment variable (`ATBASH_AGENT_KEY`) or a secret manager — never hardcode it.
+- Keep the private key in the key file (`~/.config/atbash/guard-client-key`, or a file named by `keyPath`), in `ATBASH_AGENT_KEY`, or in a secret manager — never hardcode it. See [Which key signs](#which-key-signs).
 - Never commit `.env` files containing the key.
 - If a key leaks, stop using it and create a new agent in the dashboard.
 
@@ -85,6 +82,8 @@ Every `judgeAction` call returns one of three verdicts:
 | `HOLD`  | Requires operator review | Pause — poll `getJudgmentStatus` until resolved |
 | `BLOCK` | Violates a red line | Abort — agent is jailed in Enforcement tier |
 
+> **Gate on `allow`, not on `verdict`.** `allow` is the canonical permission the SDK computes from every signal in the response; `verdict` is one of those signals, and reads as the reason. The two differ when an organisation does not enforce an agent's verdicts — Shadow Mode on an agent, or org-wide Monitor mode — where the action is judged and recorded on chain but deliberately not applied. Branching on `verdict` re-derives a denial the organisation chose not to make.
+
 > **NB:** If your org has no active subscription, the judge returns `"No verdict"` — actions are logged on-chain for the audit trail but not evaluated by an AI provider. Assign a plan at [atbash.ai/risk-engine/settings](https://atbash.ai/risk-engine/settings) for active verdicts.
 
 ## API
@@ -128,28 +127,71 @@ Standalone helpers for keypair handling.
 | `isValidPrivateKey(hex)` | Validate a private-key string |
 | `loadAgent(privkey)` | Validate the key + return `{ pubkey, privkey }` |
 
-## Configuration
+## Configuration resolution
 
-Configuration is resolved with priority: **constructor arg > env var > config file** (`~/.config/atbash/config.json`).
+`new Atbash(privkey, options)` takes everything explicitly. `Atbash.fromConfig(options)` fills in what you did not pass from the environment and then from `~/.config/atbash/config.json`, and finds the signing key for you.
 
 ```ts
 import { Atbash } from "@atbash/sdk";
-const atbash = Atbash.fromConfig();   // reads env + config file
+const atbash = Atbash.fromConfig();   // key file + env + config.json
 ```
 
-| Config key | Env var |
-|---|---|
-| `agentKey` | `ATBASH_AGENT_KEY` |
-| `orgName` | `ATBASH_ORG_NAME` |
-| `judgeEndpoint` | `ATBASH_ENDPOINT` |
-| `blockchainRid` | `ATBASH_BLOCKCHAIN_RID` |
-| `provider` | `ATBASH_PROVIDER` |
-| `providerModel` | `ATBASH_PROVIDER_MODEL` |
+### Settings: option, then env, then `config.json`
+
+Each setting is read from the first place that has it: the `fromConfig` option, then the environment variable, then the key in `config.json`.
+
+`judge` is taken whole. Pass it complete, or leave it out and use the environment or `config.json`: a `judge` with only an `endpoint` ignores `ATBASH_JUDGE_VERIFY_PUBKEY`, so a self-hosted host then fails the allowlist.
+
+| `fromConfig` option | Env var | `config.json` key | Notes |
+|---|---|---|---|
+| `judge.endpoint` | `ATBASH_ENDPOINT` | `judgeEndpoint` | Must pass the endpoint rules below. |
+| `judge.verifyPubKey` | `ATBASH_JUDGE_VERIFY_PUBKEY` | `judgeVerifyPubKey` | 66-hex response-signing key of a self-hosted judge. Set through the environment or `config.json` without an endpoint, it throws; passed in `judge` without an endpoint, the default endpoint is used. |
+| `network` | `ATBASH_DEFAULT_CHAIN_NETWORK` | `defaultChainNetwork` | Only `"private"` is accepted; anything else throws. A client that names no chain is pinned to it, even for an org the dashboard places on another chain. |
+| `debug` | `ATBASH_DEBUG` | `debug` | `1`, `true` or `yes` turns diagnostics on. |
+| `orgName` | `ATBASH_ORG_NAME` | `orgName` | `fromConfig` reads the option only. The env var and file key are read by `resolve("orgName")`, which the CLI and plugins use. |
+
+`agentKey` is not in this table on purpose: the signing key is never read from `config.json` (next section).
+
+Helpers: `saveUserConfig(config)`, `loadUserConfig()`, `resolve(key, flagValue?)`, `getConfigPath()`.
+
+### Which key signs
 
-Persistent config helpers: `saveUserConfig(config)`, `loadUserConfig()`, `resolve(key, flagValue?)`, `getConfigPath()`.
+`fromConfig` picks the first of these that is set:
 
-Agent policy and detail reads can resolve the organization's active network, or
-accept an explicit network override:
+1. `agentKey` option (hex private key in code).
+2. `keyPath` option. A path that does not exist throws; the SDK never falls through to another key when you named one.
+3. `ATBASH_AGENT_KEY` environment variable.
+4. `~/.config/atbash/guard-client-key`.
+5. `~/.config/atbash/atbash-client-key`.
+
+If none exists `fromConfig` throws `atbash key file not found. Looked for: <both default paths>`. The bare constructor never reads a key file.
+
+An `agentKey` inside `config.json` is ignored. A settings file is writable by anything on the machine and is shared by every Atbash integration, so it is not allowed to choose who you sign as. When you pass a `logger`, `fromConfig` warns:
+
+```
+[atbash] "agentKey" in config.json is ignored — settings do not choose the signing key. It holds <pubkey>; this client signs as the key file or ATBASH_AGENT_KEY instead. ...
+```
+
+and when no key file exists at all, the "not found" error names the pubkey stranded in `config.json` so you know where it went.
+
+A key file is either `key=value` lines or JSON. Both fields must be present; the public key is re-derived from the private key, and a `0x` prefix is accepted.
+
+```
+privkey=<64 hex>
+pubkey=<66 hex>
+```
+
+```json
+{ "privKey": "<64 hex>", "pubKey": "<66 hex>" }
+```
+
+For adapters and CI, keep the key in a file and point at it with `keyPath` (or let the default path be found). Passing the key on a command line puts it in shell history and process listings.
+
+### What `orgName` does
+
+`orgName` tells the SDK which chain to sign the call for: the org's network is looked up once through the dashboard, cached per client, and every judge and log call is signed for that chain. The SDK does not check that the name matches the org the agent was registered under; which org's policy judges the action is decided by the agent's registration, not by this string. On a deployment with a single chain a missing or different `orgName` therefore does not change the verdict. Org-scoped reads such as `getOrgTierInfo(orgName)` send the name as given; the dashboard answers an agent-authenticated call for the agent's own org, whatever name was passed.
+
+Agent policy and detail reads can take the org, or an explicit chain:
 
 ```ts
 await atbash.getAgentPolicy(atbash.pubkey, { orgName: "acme" });
@@ -158,6 +200,41 @@ await atbash.getAgentDetail(atbash.pubkey, {
 });
 ```
 
+### Judge endpoint rules
+
+Both `fromConfig` and the constructor validate the endpoint before any request. `validateJudgeEndpoint(...)` exposes the same check.
+
+- With no endpoint configured the SDK talks to the endpoint compiled into the build (`https://atbash.ai` for a release build).
+- An `https://` endpoint is accepted without further setup only on the trusted hosts: `atbash.ai`, `www.atbash.ai` and the build's own default host.
+- Any other `https://` endpoint is a self-hosted judge. It needs `policy: "self-hosted"` plus `verifyPubKey` (the judge's 66-hex compressed response-signing key), or `ATBASH_ENDPOINT` plus `ATBASH_JUDGE_VERIFY_PUBKEY`. Every judge response is then signature-checked against that key. Without the key the constructor throws `judge endpoint hostname "<host>" is not in the trusted allowlist`.
+- Plain `http://` is accepted only for loopback (`localhost`, `127.0.0.1`, `::1`), for a dashboard running on the same machine. Any other `http://` endpoint throws.
+- A URL with embedded credentials (`user:pass@host`) throws.
+
+```ts
+const atbash = Atbash.fromConfig({
+  judge: {
+    policy: "self-hosted",
+    endpoint: "https://judge.example.com",
+    verifyPubKey: "02…66 hex…",
+  },
+});
+```
+
+### From a key file to a first ALLOW
+
+1. Download the key file the onboarding wizard offers at its Deploy step (it is in the `key=value` form above) and save it, for example as `./agent.key`.
+2. Build the client from that file and judge an action:
+
+```ts
+import { Atbash } from "@atbash/sdk";
+
+const atbash = Atbash.fromConfig({ keyPath: "./agent.key" });
+const result = await atbash.judgeAction("read file", "list the files in ./src");
+console.log(result.allow, result.enforced, result.reason);
+```
+
+Dropping the same file at `~/.config/atbash/guard-client-key` lets `Atbash.fromConfig()` find it with no options at all.
+
 ## Error handling
 
 The SDK throws standard `Error` objects. Known failure modes are enriched with a pointer to the dashboard page that fixes them:
@@ -191,4 +268,69 @@ Policy authoring, operator reviews, and agent management happen at [atbash.ai](h
 
 ## License
 
-Proprietary — all rights reserved. See [LICENSE](https://atbash.ai/license).
+Licensed under the [Apache License, Version 2.0](LICENSE). See [NOTICE](NOTICE) for attribution. Versions published before this change remain available under the license they shipped with.
+
+## Telemetry — what the SDK sends
+
+The SDK reports how its own functions perform. It runs inside your agents and
+the data leaves your network, so the payload is **metadata only** and the list
+below is the whole of it.
+
+**Sent**
+
+| Field | Example |
+| --- | --- |
+| `function.name` | `judgeAction`, `memory.memory-add` |
+| `status` / `outcome` | `success`, `error` |
+| `duration_ms` | `142` |
+| `error.class` | `AtbashAPIError` |
+| `error.status` / `error.path` | `404`, `/api/v1/judge` — the route, never its query string |
+| `sdk.version` | `0.18.0` |
+| `sdk.language` | `node`, `python` — which binding sent it |
+| `chain` | the blockchain RID — public infrastructure, and it names no customer |
+| `agent.hash` | SHA-256 of the agent's **public** key, never the key itself |
+| `source` | `sdk`, `cli`, `plugin:openclaw` |
+
+**Never sent.** Action text, tool arguments, policy text, organisation names,
+memory file paths, memory contents, response bodies, and keys of any kind.
+`error.path` is the route alone — the query string is stripped where the error
+is built, because it carries org names, tool call ids and the agent pubkey. These are not fields
+that get emptied before sending — there is no field for them to go in.
+
+`agent.hash` is de-identification, not anonymisation: agent public keys are
+readable from the chain, so anyone holding that list can match a hash back to
+an agent. Supply your own salted hasher to `setupTelemetry({ hashAgentKey })`
+if you need it to be uncorrelatable.
+
+### Turning it off
+
+```bash
+export ATBASH_TELEMETRY_DISABLED=1
+```
+
+or create `~/.config/atbash/telemetry.json` containing `{ "enabled": false }`.
+
+**On a Private deployment, telemetry may already be off for everyone.** The operator disables collection by leaving `HONEYCOMB_API_KEY` unset on their Atbash service; the telemetry route then accepts the request and discards the payload, so nothing is forwarded and agents never see an error or retry. That is an operator setting on the deployment, not one you control from the agent — the switches above are yours.
+
+To keep the operational counters but drop the richer per-operation events:
+
+```bash
+export ATBASH_TELEMETRY_EVENTS_DISABLED=1
+```
+
+### Sending it to your own collector
+
+Point the SDK at any OTLP endpoint you control. Atbash is then bypassed
+entirely and **no Atbash credential is created or transmitted** — your headers
+are the only ones sent.
+
+```bash
+export ATBASH_TELEMETRY_COLLECTOR_URL=https://otel.yourcompany.example
+export ATBASH_TELEMETRY_COLLECTOR_HEADERS='{"x-api-key":"your-key"}'
+```
+
+Metrics go to `/v1/metrics` and events to `/v1/logs` beneath that URL. `https`
+is required; a collector on `localhost` additionally needs
+`ATBASH_TELEMETRY_ALLOW_LOOPBACK=1`, so a mistyped URL cannot silently turn
+exporting off. A URL that is refused raises at setup rather than quietly
+falling back to Atbash.