Skip to content

docs: add trusted-peer sharing and peer-onboarding guides#23

Merged
colombod merged 1 commit into
mainfrom
docs/trusted-peer-sharing
Jun 19, 2026
Merged

docs: add trusted-peer sharing and peer-onboarding guides#23
colombod merged 1 commit into
mainfrom
docs/trusted-peer-sharing

Conversation

@bkrabach

Copy link
Copy Markdown
Collaborator

Summary

Adds two operational guides for sharing a self-hosted context-intelligence server with trusted external peers over an overlay network (Tailscale), plus a README link section.

What's included

docs/remote-access-sharing.md (operator guide):

  • Loopback binding to isolate the server to localhost only
  • Exposing only the /events path via tailscale serve for HTTPS
  • Per-peer access scoping with ACL grants (autogroup:member for your tailnet, explicit peer emails for shared users)
  • Critical ACL pitfall: a default src:["*"] allow-all grant includes shared/invited users and grants are additive (union), so a narrow grant is cosmetic until the broad rule is changed to autogroup:member
  • Network verification gates (bind isolation, auth rejection, path-rewrite correctness, end-to-end HTTPS)
  • Cold backup with docker stop (not pause) and restore-as-root-in-a-container (resolves file ownership issue)
  • Trust-model table documenting accept-or-harden decisions (single shared key, client-set workspace, no rate cap)

docs/peer-onboarding.md (peer-facing connect guide):

  • What to expect (Tailscale device share, API key configuration)
  • Step-by-step connection (accept share, install Amplifier bundle, set environment variables, verify)
  • Scope of access (only the ingestion endpoint, no admin/Neo4j interfaces)

References (not duplication)

Both docs reference rather than repeat:

  • The existing "Network Access and Security" section in README
  • docs/service-setup.md §10 (Caddy/TLS patterns)
  • The API-key bearer-token auth model already documented

Scope

  • Docs-only PR — no application code changes, no config changes, low CI risk
  • Generalized from a real deployment — all environment-specific values stripped (no tailnet IPs, node names, or keys)
  • A CLA bot comment is expected and fine

Next steps

This can be merged as-is, or flagged for any wording/structure feedback.

Adds two operational guides for sharing a self-hosted context-intelligence server
with trusted external peers over an overlay network (Tailscale), plus a README link
section.

remote-access-sharing.md (operator guide) covers:
- Loopback binding to isolate the server
- Exposing only the /events path via tailscale serve
- Per-peer access scoping with ACL grants
- The critical ACL pitfall: a default src:["*"] allow-all grant includes shared
  users and unions with narrow grants (so the broad rule must use autogroup:member)
- Network verification gates
- Cold backup with docker-stop and restore-as-root-in-a-container
- Trust-model accept-or-harden table (single key, workspace spoofing, no rate cap)

peer-onboarding.md is the peer-facing connect guide to hand each trusted user.

Content references (does not duplicate) the existing README "Network Access and
Security" section, docs/service-setup.md §10 (Caddy/TLS), and the API-key auth
model.

Generalized from a real deployment — no environment-specific values.

Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
@colombod colombod merged commit 52827d8 into main Jun 19, 2026
3 checks passed
@colombod colombod deleted the docs/trusted-peer-sharing branch June 19, 2026 22:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants