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.

Choose the right MCP connection

Codex supports this local coding-agent workflow: seamward setup installs the project's seamward-setup stdio server, then you restart your Codex client in that project. The agent uses local project tools and the setup server after you review their proposed effects.

For read-only workspace investigation, use the separate hosted server: Codex connection instructions or ChatGPT connection instructions. ChatGPT web does not run this local stdio server or inspect your local project. Connecting the hosted server does not complete automatic integration setup. CLI-independent hosted onboarding remains planned; follow the current steps below for local agent setup, or use the manual collector guides.

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.

Project setup uses a narrow Sandbox authorization, separate from account management login. Run seamward setup authorize to choose the workspace and approve local setup. The seamward login account session does not authorize project credential saving. Management commands select exact connections; application keys route observations to their configured mode.

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 in a protected local credential store 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 project setup once, then install the reviewed configuration:

seamward setup authorizeseamward setup

seamward setup authorize opens project consent in the browser. The command prints a URL and waits for you to press Enter before opening Seamward in the browser. Setup remains in the terminal after authorization. Confirm the code shown in your terminal, select the workspace, approve Sandbox setup, and return to the terminal. This grant is stored outside the project and stays separate from account management login.

Run seamward setup from the deployable backend service directory. It reuses the project authorization, installs the pinned setup MCP, and previews project-scoped configuration for Claude Code, Cursor and Codex while preserving unrelated entries. Approve the displayed files before applying. Use --dry-run for a read-only preview. The installer does not read or edit application environment files.

If project authorization is missing or revoked, rerun seamward setup authorize, then rerun setup. Account management login does not repair a project-scoped grant.

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

Verify instrumentation and real observations in Sandbox. Reuse the same source revision for Live. A workspace owner or admin configures the separate Live connection from Integrations in the dashboard. Review any selected contract and rule copying there; credentials and evidence stay independent. Copied rules start disabled.

An owner or admin places the Live Connection key and one-time ingest token directly in the hosting platform's secret manager under the variable names expected by the reviewed source. The management CLI and coding agent do not issue, copy, install or expose Live secrets. Deploy the source and verify an intended observation on the Live connection. There is no mode-specific CLI login or setup flag.

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

Project setup authorization and account management authorization are not ingest credentials. For each instrumented boundary, configure its Live connection in the dashboard and save the one-time pair directly in your hosting secret manager. Use the exact variable names from the reviewed instrumentation.

Each Connection key identifies one workspace, mode and connection. Each secret ingest token authorizes only that connection's ingestion and connection checks. Neither project names nor application .env filenames change that routing. Do not add SEAMWARD_ENVIRONMENT.

If a displayed token is lost, a workspace owner or admin reviews rotation in the dashboard and updates the hosting secret. The CLI has no deployment-secret export command. See runtime configuration and credential lifecycle.

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 setup authorize. A running coding agent reports authentication_required for the same condition. Authorize project setup 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.

Remove one mode connection

An Integration always has a Sandbox and a Live connection. Use connection-only deletion to clear one of them: its credential, configuration and evidence are removed, and a new, empty connection takes its place. 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. The replacement connection has a new ID, no credential of its own 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 management CLI supports separate reviewed connection and whole-Integration deletion, while the setup MCP uses whole-Integration deletion.