Automatic setup

Supported collector stacks

The collector screen offers TypeScript, JavaScript, PHP, and Laravel examples. Its selector changes instructions only. It does not inspect your repository or change the Integration, contract, or credentials.

Automatic setup derives a stack from the service runtime and discovered source language. TypeScript and JavaScript require a Node backend. Laravel requires PHP 8.3+ and Laravel 12 or 13, with a supported HTTP client or webhook source shape. Framework-neutral PHP uses the manual PHP collector guide, including an application-supplied transport. A directory declaring both Node and PHP backends must be narrowed to one service before setup.

Agents can request a stack with review_setup.local.collectorStack, using typescript, javascript, php, or laravel. An explicit choice is checked against the runtime and selected operations; it cannot enable an unsupported adapter. The guided proposal editor offers the same choices. The selected stack is recorded in new local plans and changes their approval fingerprint.

Moving an existing boundary to another stack

Reuse the existing Integration when its environment, direction, protocol, and monitored boundary are unchanged. Review the new plan before applying it. Seamward retains the local binding and remote Integration identity, but requires fresh implementation verification. A retained ingest token is preserved; if a replacement credential is needed, that effect must appear in the remote proposal.

Automatic migration stops while the previous instrumented source file remains in the service. Review that old implementation first. An unchanged owned generated file can be removed during the approved move; a modified generated file blocks replacement. Old collector dependencies are not automatically uninstalled because another Integration may still use them.

Legacy plans without a stack are replanned for review without deleting their saved binding. Selecting a different dashboard example does not perform this migration or prove that the new application has sent traffic.

Set up one deployable backend service with one project command and one coding-agent prompt. Seamward analyzes the repository locally, separates independent integration boundaries, proposes the source changes, runs the project's verification commands, and connects each reviewed contract only after approval.

Before you begin

You need owner or admin access to a Seamward workspace. Fresh workspaces contain Sandbox and Live. Existing legacy workspaces retain their recorded environments until reviewed migration. Authorization never provisions a missing Staging environment. You do not create an application or ingest token before starting.

Login asks you to select the workspace in the browser. The CLI command binds the mode: no flag or --sandbox means Sandbox; --live means Live. For a legacy workspace, use --development, --production, or --staging explicitly. Each legacy flag selects the exact existing environment. It does not migrate a grant, alias it to another mode, or authorize additional connections. After you approve the remote preview, Seamward creates or reuses each reviewed Integration, issues its one-time ingest token, and stores that token outside the repository with owner-only file permissions. See Collector configuration and credentials for credential formats and rotation.

Install once, then run one project command

Install the Seamward CLI once:

npm install -g @seamward/cli@alpha

Authorize the CLI once:

seamward login

Login prints the authorization URL and waits for you to press Enter before opening the browser. Select a workspace, approve access, and wait for the Seamward success screen. The browser stays on Seamward. The waiting login command polls securely and continues automatically after approval.

Then run this from the deployable backend service directory:

seamward setup

Setup remains in the terminal. It:

1. Reuses the active workspace-environment authorization stored outside the repository.
2. Installs an exact @seamward/setup-mcp version.
3. Adds project-scoped MCP configuration for Claude Code, Cursor, and Codex while preserving unrelated configuration.
4. Stops with an authentication error before changing the project when login is missing, expired, or revoked.

The installer never reads or edits an environment file. It shows every project file it will change and asks once before applying those changes. Use --dry-run to inspect the project changes without applying them.

Only seamward login opens a browser. If automatic launch fails, open the printed URL manually. In a non-interactive terminal, login prints the URL without launching a browser. Denying access stops login immediately. A timed-out request can be restarted safely by running login again.

The login command uses a short-lived device code, so no local callback page or listener is exposed in the browser. After the success screen appears, return to the terminal. Login finishes there, and you can run seamward setup when ready.

The setup grant is narrower than workspace-wide write access. It is bound to one workspace environment and lets setup preview and create or reuse only reviewed Integrations in that environment.

The setup alpha supports up to 100 Integration connections in one environment. If the selected environment exceeds that limit, authorization stops with setup_context_unavailable instead of silently omitting Integrations. Contact Seamward support before continuing with that workspace.

Choose your next prompt

Reopen your coding agent after installing the project tools, then choose one:

Review-only prepares a proposal without applying it. A status request checks the existing setup without authorizing changes. Local credential review requires a connected Sandbox setup and hands off to the terminal CLI. Saving credentials requires a separate approval and never targets a Production file. These are suggested requests, not auto-approval modes. Installing the tools alone does not verify Integrations or runtime traffic.

If the terminal still offers only one prompt, it is using an older setup package. When the mode-aware alpha release is published, update @seamward/cli@alpha, rerun seamward setup, and reopen the agent. Do not reset existing Integrations.

Promote the verified setup

Local repository analysis, instrumentation, connection checking, and observation confirmation happen in Sandbox. When the same source revision is ready for Live, authorize and promote it from the project directory:

seamward login --liveseamward setup --live

Live setup stays in the terminal. It re-verifies the saved Sandbox source evidence, previews which Live Integration connections and contracts it will create or reuse, and waits for confirmation. It does not run the coding agent, edit source, rerun local instrumentation, read an environment file, or write an environment file.

Commands without a flag always return to Sandbox, even when a Live login is active. Legacy flags require their exact existing authorization.

Prompt your coding agent

Restart or reopen the coding agent so it loads the new project MCP configuration. Then ask:

Set up Seamward in this project.

That is the full prompt. Do not identify a provider, protocol, contract path, or internal setup action. Seamward discovers supported HTTP API, webhook, queue, and scheduled-feed boundaries and presents plain-language choices only when the repository is ambiguous.

One repository may contain several Integrations. Candidate webhooks, payment notifications, and an outbound messaging provider remain separate even when two use the same protocol. Seamward prepares a distinct local plan, generated collector binding, runtime Connection key name, contract lifecycle, and status for each boundary.

Repository scripts, tests, fixtures, mocks, tools, build output, and provider simulators are excluded from automatic service-boundary discovery. Ordinary first-party HTTP routes remain visible to explicit discovery, but the one-line flow selects only the shipped automatic boundaries: inbound webhook handlers and outbound HTTP provider calls in supported Node.js and Laravel source.

Review the setup

The coding agent follows this lifecycle:

Analyze repository locally  -> Explain the selected boundary and proposed source diff  -> Propose Integration names, create/reuse decisions, and contract effects  -> Ask once to approve the complete local and remote proposal  -> Install the exact Node.js or Laravel collector, then instrument it  -> Run the repository's tests, typecheck, and build  -> Connect the approved remote structure only after local verification succeeds  -> Hand off to seamward setup credentials in a standalone command block  -> User selects the local environment file and reviews key names  -> CLI asks before saving Sandbox credentials  -> CLI checks every saved connection without starting the app  -> Confirm connection; user starts the app normally with that file loaded  -> Confirm actual observations in Seamward

Analysis and status checks do not require repeated approval. The combined review keeps its local proposal in memory and may create an expiring remote preview operation, but does not modify application source, install dependencies, stage credentials, or create Integrations. One approval covers all reviewed setup effects.

For a fresh supported Laravel project, the local preview lists composer.json as a dependency change but does not run Composer. After local approval, setup installs exact compatible PHP and Laravel collector versions, verifies both in the production lock, and only then changes source. If installation, source instrumentation, or project verification fails, it restores composer.json, composer.lock, generated configuration, setup state, and reviewed source.

The remote preview says Create or Reuse for every detected boundary and shows its name, provider, direction, protocol, and contract effect. Ask the agent to adjust a proposed name or provider before approval when its inference does not match your team's terminology. Applying the same approved operation again returns the same Integrations instead of creating duplicates.

The agent displays the complete proposal, then waits for your reply in the conversation. Reply approve, describe the changes you want, or reply reject. The agent carries the exact proposal fingerprint between tools; you do not copy internal identifiers. A revised proposal needs a new decision. Silence and auto mode are not approval.

Conversational approval trusts the agent to relay your decision faithfully. It is not independently authenticated reviewer consent. Your host may still require its own tool permissions. Native approval remains an explicit compatibility option for guided clients, not a required popup in the conversational flow.

Cancellation returns approval_cancelled; declining returns approval_declined. Both stop setup until you ask to continue or request changes. An invalid response returns approval_invalid. These results must not trigger automatic retries.

If an explicitly selected native client cannot collect approval, setup stops with approval_unavailable; it does not silently approve on your behalf. Auto mode is not approval of a new proposal. Preview freshness and source verification checks still apply.

Older clients can declare form approval using the legacy capability format; Seamward accepts that format without requiring a different setup prompt. The client must still display the proposal and collect your decision. Updating the setup tools requires restarting your coding-agent session to load them.

Successful completion reports the connected Integrations, verification and first observations, plus any remaining runtime steps. Recovered installation issues are not current blockers. Unresolved failures, partial setup, and runtime credential requirements remain visible. The MCP returns canonical customer text and asks supporting coding-agent hosts to display it verbatim. Seamward controls this tool response, not a third-party host's final wording or interface.

New named Node bindings use readable paths such as src/seamward/candidate-ats.generated.ts. Name collisions receive transport qualifiers. Saved paths and environment-variable names remain stable on re-review, including legacy hashed filenames. The saved plan records generator version and expected generated-content hashes. Do not put business logic in generated files.

If a handler moves, setup retains an unambiguously matched saved identity. If the match is ambiguous, it stops before creating or retiring integrations. Tell the agent which existing boundary the moved code belongs to and review its revised proposal. Existing remote names and providers are not renamed by this lifecycle.

Existing modified generated files, or differing files whose setup metadata is missing, require manual conflict resolution. Preserve your edits outside the generated file or restore the matching ownership metadata, then request a fresh review. An audit does not authorize replacement.

The credential-free setup-session receipt records progress, not reusable consent. After a restart, review again. Setup reconciles saved bindings rather than assuming the previous approval remains valid. Verified observations do not prove persistent local startup: credentials loaded temporarily for validation are not automatically available to the next terminal session.

To read the output directly from Seamward instead, use seamward setup --guided in an interactive Sandbox terminal. Choose y to approve, e to revise names/providers, or Enter to cancel. --yes cannot bypass this approval. Use seamward setup --guided --dry-run --json for a structured proposal, or seamward setup --status --json for read-only status. Guided apply stops at connection, not runtime verification. Continue in the terminal with the credential flow below, start the app normally with the selected file loaded, then check status again. Status exits zero only when setup is fully connected with observations. Bare seamward setup still installs tooling.

The result separates tooling readiness, a proposal awaiting approval, local verification, remote connection, waiting for observations, and verified setup. Creating an Integration is not runtime verification. No result asks you to invent a different setup prompt: continue the same conversation and follow the reported next action. A new decision or approval is still required at each trust boundary. Setup does not save runtime credentials by default. Optional Sandbox-only saving has its own review and approval, described below.

When the reviewed document exactly matches an already-active contract, Seamward links that exact already-active version to the verified local setup without a registration or activation request. A JSON Schema operation binding is required when the document does not identify an operation, so observations cannot be compared with an ambiguous schema.

Automatic source instrumentation supports common Node.js and TypeScript outbound HTTP calls and inbound webhook handlers. It also supports Laravel Http facade calls with a statically recoverable route and literal Route webhook declarations. Dynamic URLs, custom PendingRequest variables, queues, scheduled feeds, arbitrary PHP clients, Laravel outside versions 12 and 13, and PHP below 8.3 return a structured manual result before any write. Clear multiple boundaries are prepared together. Ambiguous boundaries or contract candidates are presented as readable choices.

Laravel compatibility results use stable codes: php_runtime_unavailable, unsupported_php_version, unsupported_laravel_version, collector_not_installed, collector_incompatible, unsupported_source_shape, and unsupported_framework. The result also includes the observed PHP, framework, and collector versions without reading an environment file.

Confirm normal application traffic

The agent hands off to the CLI after connection:

seamward setup credentials

Saving checks the credentials without starting your app. Start your application normally with the selected file loaded and exercise an integrated route. Check the received observations in Seamward or run:

seamward setup --status

Waiting for traffic is not a credential failure. If observations do not arrive, check your application's environment loading and instrumentation with your agent. You do not need to provide startup commands or traffic scripts to complete onboarding.

Explicit application diagnostic

Only use this command when you specifically want an automated startup and traffic test and already have a supported startup command and reviewed synthetic scripts. It is not an onboarding step and is not required for completion:

seamward setup verify-app

The CLI collects supported startup and safe traffic scripts, loopback readiness, and approval. Credential and runtime operations are not callable through agent MCP. Review the commands in your terminal before approving.

After approval, saved-mode CLI verification starts only the reviewed package script. It injects no Seamward credentials; the service loads the selected environment file. It runs each distinct reviewed traffic script once, stops the complete service and traffic process trees, and polls Seamward for fresh observations. Approval also binds the executable repository artifacts, not only the package-script names. Verification reads the saved configuration but does not change it. If the repository has no safe traffic script, do not use this diagnostic. Start the app normally and use an integrated route instead.

setup verify-app checks startup with saved credentials. Cancelling grants no later approval.

Review also supports explicit PORT and ENABLE_TEST_CONTROLS child-process overrides. The port must match the readiness URL and be available both during review and immediately before startup. runtime_port_unavailable requires a fresh review with another port; setup never stops an unrelated process. Review test-control prerequisites before running traffic. Changing a script or override, or letting a preview expire, requires a new displayed review and fresh approval.

The CLI records credential-free progress under .seamward/. If traffic finishes but a status request fails, follow the CLI's recovery instructions. Do not assume that a failed status check means traffic was never sent. Service, readiness, traffic, cancellation, and status failures have separate stable error codes and report only the affected phase and script name.

Configure deployed runtime ingestion

The setup authorization is not an ingest credential. Before deploying the instrumented service, print the Live values explicitly and store them in the service's secret environment:

seamward deployment env --live

The command prints sensitive values because you requested them directly. Send the output to the hosting platform's secret manager and do not commit it. The output contains one Connection key and one ingest token for each binding:

SEAMWARD_CONNECTION_KEY_CANDIDATE_C5E54BF1=sw_conn_v1...SEAMWARD_INGEST_TOKEN_CANDIDATE_C5E54BF1=sw_ing_...SEAMWARD_CONNECTION_KEY_PAYMENT_C5E54BF1=sw_conn_v1...SEAMWARD_INGEST_TOKEN_PAYMENT_C5E54BF1=sw_ing_...

The generated names come from the reviewed local plan, so copy the exact names reported for your repository. Each public Connection key identifies one workspace environment and Integration. Each secret ingest token authorizes observation delivery and connection checking for that Integration. Seamward stores only the token hash. The setup tool saves the one-time plaintext in its protected local credential store and never includes it in repository files, previews, or remote operation status.

For a deployed service, place these values in the hosting platform's secret environment. Automatic setup does not silently change a deployment platform or send production traffic.

Do not add SEAMWARD_ENVIRONMENT. The Connection key and ingest token already bind each observation to the correct workspace, Integration, and environment. The production server does not run the CLI or MCP. It starts the same instrumented application with the Live runtime values supplied by the hosting platform.

If a manual console request completes but its one-time token response is lost, refresh the Integration's Collector setup tab and choose Rotate ingest token. Seamward does not retain plaintext tokens for replay.

Do not put either value in an agent prompt, project MCP file, source file, or committed configuration.

Save Sandbox credentials locally (alpha)

This optional feature supports macOS and Linux. Windows local saving is not supported in this alpha.

After connecting your Integrations, run this in the project terminal:

seamward setup credentials

The CLI discovers root .env and .env.local files, including Git-ignored files, and offers an existing file, a new file, or an existing supported path. Saving does not inspect startup scripts or require package.json. You select the file and are responsible for loading it when starting your application. The tool does not alter scripts or choose how your application starts.

Review the absolute filename, missing/configured/conflicting variable names, and backup policy, then answer the terminal save prompt. Values are never shown. The CLI calls the shared save service with that exact review and confirmation. The file must be untracked and ignored by Git. Only Sandbox runtime credentials are saved, never your CLI access or refresh token. Existing conflicting keys, duplicate entries, unsafe links and production filenames stop the operation. It preserves unrelated content and creates a private backup before changing an existing file. Declining leaves the file unchanged.

The save result is saved or already_configured. The CLI then validates every saved connection against Seamward without starting your application. It prints CONNECTION VERIFIED and exits 0 only if all pairs match the configured Integrations and Sandbox environment. If checking fails, it exits 1 and keeps the saved file intact. To repeat only this read-only check:

seamward setup verify

Connection verification is not proof of application traffic and is not stored as a permanent success. Start the application normally with your selected file loaded. Seamward shows observations as your instrumented application sends them. Check received traffic without starting or stopping the app:

seamward setup --status

No supported startup loader or test script is required for this flow. Return to the agent and ask to check setup after sending traffic. The agent reads the observed result; your chat message alone is not completion evidence. Keep credential files closed while recording. See environment configuration for backup boundaries and troubleshooting for refusal codes.

Verify completion

After using an integrated route, check actual observations. At any time, ask the coding agent:

Check Seamward setup status.

The result progresses through these states:

connected confirms ingestion. It does not claim that every operation ran or that every expected business outcome is healthy.

Agent localCredentialsStatus reports not_checked or receipt-backed saved_unchecked. Agent localStartupStatus stays not_verified; the agent does not inspect env files. CLI status can additionally report configured or stale credentials and verified or stale startup. Only a saved-mode run with fresh observations permits CLI verified startup. Source, startup artifacts, credential-file snapshot or Integration identity changes invalidate that proof. The receipt describes the last verified local run, not ongoing health or deployment. MCP schema /18 and customer output /8 distinguish ephemeral_verified from terminal local verified; status without a local runtime receipt stays connected.

waiting_for_traffic appears only after current source evidence is verified and the reviewed contract is active. It never hides a stale or incomplete local setup behind a traffic status.

Return after code changes

Run seamward setup and the same prompt weeks later. Seamward reuses the project-scoped authorization when it remains valid, analyzes the current code, reuses unchanged bindings, and identifies verified source that became stale. It does not wrap already verified handlers again.

A setup package upgrade also regenerates the review when its generator version changes. Compatible binding paths and remote identity are retained, while old verification evidence is rechecked. Compatible installed collectors remain in place. Do not delete setup state or patch installed packages to force an upgrade.

The current alpha safely reuses unchanged bindings and marks changed verified source as stale. When an Integration boundary is removed, the next setup preview lists its generated collector file and local binding state for removal. Approval snapshots current and retired binding files together, applies the reviewed changes, removes only those setup-owned local files, and verifies the final project tree. Any failure restores the complete snapshot. The remote Seamward Integration is deliberately left active so removing code from one repository cannot silently retire a shared workspace Integration. After confirming that no other service uses it, an owner or admin can delete it from the Integration danger zone, run seamward integrations delete <integration-id>, or ask the setup MCP to preview and delete it. For MCP deletion, the MCP client asks the authorised reviewer directly to type the exact Integration name and acknowledge that deletion cannot be undone. Tool arguments cannot bypass that confirmation. Every path requires a current impact preview and exact-name confirmation. Remote deletion does not edit application source or environment files, so remove obsolete local instrumentation and deployed runtime variables in a separate reviewed change.

Setup validates its stored grant before reuse. If refresh is no longer possible because access was revoked, membership changed, or the Integration was deleted, it exits before changing the project and tells you to run seamward login. A running coding agent reports authentication_required for the same condition. Login again, then rerun setup or retry the coding-agent operation.

Disconnect a local project

To remove this project's locally stored setup authorization without changing source or project MCP configuration, run:

seamward logout

To invalidate active access and refresh tokens, revoke the Project setup client from Workspace settings > MCP. The settings screen shows the workspace environment authorized for each setup client. Local project files remain unchanged.

Privacy and safety

• Repository analysis runs locally.
• Source contents are not uploaded through the setup MCP.
• Agent setup does not read or change environment files. CLI local saving requires separate approval and accepts only .env or .env.local under Sandbox authorization.
• CLI OAuth credentials and runtime backups are stored outside the repository with owner-only permissions. Optional Sandbox runtime credentials are plaintext in the reviewed ignored, untracked .env or .env.local inside the project directory, also with owner-only permissions.
• A connection check reads the selected credential file without starting your application or sending application observations.
• Contract registration and activation require a reviewed remote change.
• The collector redacts and fingerprints observations before transmission.
• Repositories containing several deployable services must run setup once from each service directory.

Manual and headless setup

Open Collector setup on the Integration for installation, credential configuration, and instrumentation snippets. These steps are visible by default and do not require the CLI or a coding agent. The Set up with a coding agent link opens this guide. When using assisted setup for an existing Integration, provide its Integration ID and ask the agent to reuse it. Review the proposal before applying changes. Workspace API keys remain available for headless automation and CI, but they are not required for the normal browser-authorized setup flow.

The advanced API-key flow requires integrations:read, contracts:read, contracts:write, contracts:activate, and observations:read. Select Manage contracts and read observations when creating the key. API-key scopes cannot be changed after creation, so create a replacement key when an existing key lacks one of those scopes. Keep that key outside the repository and do not pass it in a coding-agent prompt.

For lower-level automation, see the CLI reference. For runtime failures, see Integration troubleshooting.

For later credential changes, use the connection credential API. Read and review the current revision before issue, rotation, or revocation. Keep the original request and idempotency key if the response is lost. A recovered receipt never reveals the token again. Read current status and review a separate rotation when the token was not saved. See credential change troubleshooting.

Set up the other mode

In a workspace already using Sandbox and Live, an owner or admin can add the missing connection for an existing Integration from the console Integrations list. Select the destination mode and open its setup flow. Start empty or select declared contracts and reconciliation rules from the other connection. Review the exact source, destination, and selected configuration before applying.

The review lasts ten minutes and must remain unexpired until setup completes. Current management permission is required for both apply and operation status. If expiry or permission loss occurs during apply, no new connection, configuration, credential, or completion receipt is saved. Restore access when needed, then review the current configuration again. Checking status does not extend an approval.

Save the new connection's one-time runtime credential separately. Copied contracts are drafts and copied rules are disabled. Credentials, observations, baselines, incidents, and repair history are never copied or synchronized. After a lost response, check status using the original authorized session or key. A completed receipt is token-free and historical; it does not show that your application is sending traffic.

These console and workspace API operations set up a missing mode connection. For an existing destination, use the separate reviewed configuration copy and compensation API. Owners and admins can also open Manage this connection on the destination Integration page to select, review, apply and recover the same operation. For HTTP automation, use the reviewed mode connection API. For a refused review, see mode connection troubleshooting.

Remove one mode connection

Use connection-only deletion when you are retiring one Sandbox or Live connection while keeping the shared Integration. An owner or admin must provide a workspace API key with integrations:manage.

1. Find the exact int_ connection ID and mode in the Integration inventory.
2. Create an empty-body deletion preview. Review its mode, counts, preserved connection IDs, and ten-minute expiry. Any nonzero hazard blocks deletion.
3. After work settles and cross-connection references are resolved, create a fresh preview. Submit its exact confirmation challenge and fingerprint with a new retained idempotency key.
4. Confirm status: "completed" through the retained status endpoint. A lost response can be recovered with the same active key or the exact original apply request.
5. Remove obsolete instrumentation and that connection's runtime variables from your own service in a separate reviewed change. The API does not edit your source or configuration.

This operation has no undo. Re-adding the connection starts with new credentials and no recovered evidence. The shared Integration, other connection, usage totals, audit history, and canonical operation receipts remain. To retire the whole Integration, use its separate reviewed deletion flow; the CLI and setup MCP commands delete the whole Integration, not one mode.

Enable a copied rule through the API

Copying configuration creates disabled reconciliation rules. To use one, list connection rules on the exact destination with an integrations:read workspace key. Review its definition and returned connection revision. Use an integrations:manage key to PATCH that exact rule with the reviewed expectedRevision and enabled:true, using a new retained idempotency key.

Keep the new operation ID for recovery. After an unknown response, read its status with the original actor or retry the unchanged request and key. A stale revision needs a fresh read and review; never replace the revision on an old idempotency key. Test the Sandbox definition before separately enabling the Live copy. Setup authorization does not grant this workspace-key rule lifecycle.