Configuration

Everything the collector reads from your environment and configuration, in one place. Options are set in code on createSeamwardCollector; this page covers the values themselves.

Credentials

Local persistence through the CLI (alpha)

Save Sandbox credentials from your project terminal:

seamward setup credentials

The default selects Sandbox. For an existing legacy Development grant, use seamward setup credentials --development to select that exact environment. Live and legacy Production or Staging credentials cannot be saved through this local workflow. See environment selection.

Select root .env or .env.local, review the destination and variable names, and approve saving. No startup loader is required. Existing matching values are preserved; conflicting credentials are never replaced. Saving does not start the application or change deployed configuration. Start your application with the selected file loaded. After saving, the CLI validates every saved connection with Seamward; no app is started. To repeat that check:

seamward setup verify

Exit 0 means all connection checks passed now. Failure exits 1 without undoing a successful save. Neither result verifies application traffic.

Start your application normally with the selected file loaded, then exercise an integrated route. Check observations in Seamward or with seamward setup --status. No startup script discovery is required. Secrets are never printed by these commands.

Agent MCP cannot perform either operation or inspect the environment file. Agent status saved_unchecked means a CLI save receipt exists, not that the current file or startup has been checked. CLI status can report current configuration and the last verified local run.

See the walkthrough and refusal codes.

Two values connect one integration to your backend:

Copy the Connection key and issue or rotate the ingest token from the integration's Collector setup tab. The token is shown once; store it in your backend secret manager and never in browser code, Git, logs, or support messages. Rotation invalidates the prior token immediately, so have the target deployment ready before confirming.

Environment variables

The conventional wiring, matching every example in these docs:

SEAMWARD_CONNECTION_KEY=sw_conn_v1.replace_meSEAMWARD_INGEST_TOKEN=sw_ing_L2mX9qT4vB7cD1fG6hJ8kN3pR5sV0wYzA1bC4dE7gSEAMWARD_INGEST_URL=https://api.seamward.com/ingest

SEAMWARD_INGEST_URL is read automatically by the Node.js collector and the published Laravel configuration. Framework-neutral PHP passes an endpoint to Connection::fromCredentials() and uses the same default, https://api.seamward.com/ingest. Set the override only for custom or self-hosted deployments.

Release context can also come from the environment. The collector reads these automatically at construction:

The Node.js and framework-neutral PHP collectors recognize these values at construction. Laravel resolves them through the published configuration so php artisan config:cache remains safe. Explicit deployment values win. When no release is set, the first 12 characters of the commit SHA are used. Invalid values are ignored rather than breaking your application. See release metadata for per-platform recipes.

Redaction policy

const seamward = createSeamwardCollector({  connectionKey: process.env.SEAMWARD_CONNECTION_KEY!,  ingestToken: process.env.SEAMWARD_INGEST_TOKEN!,  policy: {    version: "candidate-api-v1",    hashNamespace: "candidate-api-key-2026-08",    dropFields: ["full_name", "email", "phone_number"],    hashFields: ["candidate_external_id"],  },});

In Node.js, version, dropFields, and hashFields are required when you supply a custom policy. hashNamespace is optional. The custom policy replaces the Node.js default entirely (seamward-default-v1, which drops password, access_token, refresh_token, authorization, cookie, and set-cookie). PHP and Laravel default to shape-only-v1 with empty dropFields and hashFields lists; construct a RedactionPolicy with your own lists to configure those local helpers.

Understand what the policy actually controls, because the privacy guarantee is stronger than the policy:

• Payload values and headers never ship, policy or no policy. The envelope schema has no field for them; the collector derives structure (field names and types) and a fingerprint, nothing else.
• version is stamped into every envelope so evidence can be traced to the exact configuration that produced it. Change the version whenever you change the policy.
• Identifier hashing is keyed with a key derived inside the collector from your ingest token. Correlation and business-object identifiers you pass to the observe wrappers become sha256: hashes before transmission.
• hashNamespace identifies the hashing key generation without exposing the key. Set a stable, non-secret label when you manage rotations explicitly. When omitted, the collector derives a namespace from the current key. Rotating the ingest token changes that derived namespace, so hashes from the old and new key are never correlated accidentally.
• dropFields and hashFields configure optional local helpers, exported as redactPayload and redactHeaders in Node.js and Redactor::payload() and Redactor::headers() in PHP. The five credential headers (authorization, proxy-authorization, cookie, set-cookie, x-api-key) are always dropped by these helpers regardless of policy.

Delivery tuning

Framework-neutral PHP flushes only when your code calls flush(). Laravel flushes at documented framework lifecycle boundaries and supports an explicit manager flush for long-running workers. Neither PHP package performs timer-based or destructor network I/O.

The defaults suit most backends. Tune only with stats() evidence: persistent failedBatches means the endpoint is unreachable, rising dropped means the queue bound is being hit.

Next steps

• Collector SDK: the full API these options feed.
• Errors: what rejections look like and how to respond.

Node-only inspection, upload and shutdown budgets are listed in the collector resource limits. Use the defaults for a pilot. Monitor skippedInspections before raising a bound; increasing it trades customer-process memory or shutdown time for more telemetry.