Architecture and ownership
The browser remains the health-data authority. A loopback Companion owns the agent processes and translates their native protocols into authenticated HTTP streams. This is not an OpenAI-compatible API shim and is not the separate Agent Access relay.
See the source architecture note and MODULE_MAP.md for the full graph. Where older design prose differs from the current service authorization checks, the checks are authoritative.
Adapter boundaries
Local image support must be reported by the adapter and selected model. Do not infer it merely from a familiar model name. Hermes ACP does not currently expose session-scoped reasoning; preserve its inherited setting rather than rendering a nonfunctional slider. OpenCode variants and other agents’ reasoning catalogs are normalized only when advertised.
Personal gateways receive bounded, enabled context in the chat instructions but no local MCP credential, structured tool bridge, image feature route, or background feature inference. Their tool policy cannot be constrained by the local adapter’s allowlist. Unsupported approval, sudo, secret, or clarification requests fail with guidance to use the agent’s own application.
Turn and data flow
- Snapshot profile, conversation, provider, execution target, model, and generation ownership.
- Verify connection, catalog availability, and the required text/image/structured-output capabilities before sending health data.
- Build the same bounded, user-enabled context snapshot used by direct chat. Local structured tools extend this snapshot; they do not replace it.
- Start or resume the adapter session and stream normalized text, activity, tool calls, completion, errors, and usage.
- Execute registered tools in the originating browser, checking that the originating profile is still active. Return only the bounded projection.
- Persist normalized messages, provider/agent metadata, session references where supported, and the context receipt. Include successful data-returning tools in that receipt, not failed or draft-only calls.
Drafts never commit through a tool call. The browser sanitizes the proposal, presents Apply / Discard, revalidates profile ownership on Apply, and uses existing sync-aware persistence helpers. There is no generic database write, raw IndexedDB/DOM access, arbitrary JavaScript, credential-reading, or shell tool.
Source toggles apply to both baseline context and typed local reads. This deliberately differs from relay Agent Access’s separately authorized full-context snapshot. A profile switch invalidates ongoing reads/navigation and stale async UI work. See chat internals for generation, search, import, and storage race guards.
Connection and lifecycle security
- Bind only to loopback. Discovery probes the bounded port range 8324–8331; an explicit operator port stays strict.
- Official hosted origins and loopback development origins are allowlisted. Additional self-hosted origins require
GETBASED_AGENT_HOST_ALLOWED_ORIGINSwith exact, comma-separated origins. Never use a public bind or wildcard as a workaround. - Hosted discovery issues bounded, short-lived, origin-bound chat credentials. These credentials cannot call lifecycle controls, including pause/resume.
controlAuthorized: falsemust remain visible to the UI’s decision logic. - Installation controls require the persistent installation credential and the service’s local/origin checks. Do not return that secret to hosted pages, transfer it across discovered endpoints, or equate advertised control capability with authorization.
- The development server’s private API peer check applies independently of its bind address. Its status probe uses numeric loopback and refuses redirects before sending the pairing token.
- Executable updates use the fixed official HTTPS Companion bundle URL, refuse redirects, enforce a timeout and streamed size cap, and validate the candidate before replacement. Lifecycle operations reject active work where required. Updating and restarting are separate operations.
- Images uploaded to
/v1/uploadsare authenticated, validated and bounded, placed in a private temporary workspace, and removed after the turn or cancellation. Session tool credentials are private and turn-scoped. Error responses must not serialize arbitrary CLI stderr, paths, or secrets. - File-size checks and reads use the same open descriptor; bounded reads loop to EOF with a sentinel byte past the cap. A single
read()is not guaranteed to fill its buffer.
Build and operate
From an application checkout:npm run companion runs a standalone source Companion; npm run companion:install builds and installs it for login startup. The production build also emits getbased-companion.mjs for hosted setup. Do not tell a hosted user to run an npm script without a checkout.
The distributed file needs Node.js 20+. Linux uses a systemd user service, macOS a LaunchAgent, and Windows a least-privilege user scheduled task with a hidden launcher. Installation captures executable paths rather than relying on an interactive shell PATH. Windows command wrappers are validated and paths escaped. The headless bundle has no native tray GUI.
GETBASED_AGENT_HOST_PORT, GETBASED_AGENT_HOST_ALLOWED_ORIGINS, and executable overrides are advanced operator controls, not required onboarding fields. Keep tokens out of examples, logs, issues, and command-line arguments. Do not synchronize machine-local host endpoints or credentials as portable agent account setup.
Claude Agent release gate
Default discovery omits Claude Agent. The retained adapter requiresGETBASED_ENABLE_CLAUDE_AGENT=api-console and official CLI authentication using claude auth login --console. The installer preserves that explicit operator opt-in. This is the implemented distribution gate, not legal clearance for third-party consumer-subscription routing; self-hosting alone does not waive provider terms. Preserve the gate unless the project’s approval and distribution policy changes.
Models, feature routes, and voice
Catalog ownership is the exact agent/target pair. Discard responses that arrive after either changes. Direct catalogs remain isolated by provider and privacy mode. Exclude explicit unavailable entries; do not promise entitlement for entries without an availability signal. Personal gateways highlight their current/default model rather than importing generic recommended families.Follow chat assistant resolves the current CLI route and its capabilities for feature labels and dispatch. Unsupported routes fail clearly instead of falling back to stale direct-provider settings. All affected features should use the feature dispatcher, not call the direct API facade unconditionally. Keep each feature’s existing schema, consent boundary, review, and cancellation behavior.
CLI adapters expose no standardized audio transport. Automatic STT/TTS falls back on-device for CLI chat and must not pick a different saved cloud provider. Explicit voice selections remain independent; only the resulting transcript enters the chat request.
Verification checklist
Run change-scoped unit and browser tests locally; GitHub Actions owns the exhaustive browser/combined-coverage matrix. Do not run high-write suites without the repository’s required approval.- Exercise discovery, origin restrictions, persistent versus discovery authorization, stale endpoints, old capabilities, occupied ports, and stopped-service recovery.
- Test adapter catalog/target changes, unavailable models, effort persistence, image capability rejection, cancellation, and bounded upload cleanup without paid inference.
- Test read/navigation profile binding, sanitized proposals and explicit Apply, history restoration, decryption failure, switching profiles during silent responses, and late search/import callbacks.
- Verify startup resources separately from production bundle budgets and preserve measured per-resource diagnostics.
- Before claiming platform readiness, perform actual Windows/macOS service lifecycle and native file-drop checks. Browser emulation and Linux tests are not substitutes.