Environment configuration

New workspaces start with Sandbox and Live. Seamward creates both with the workspace. Users do not add, rename, or delete environments. Existing workspaces retain their Development, Staging, and Production records until reviewed migration. Setup authorization selects an existing environment; it does not create Staging. Automation can discover exact targets through the workspace environment API.

Environment model

Optional local credential saving

The automatic setup guide describes the alpha seamward setup credentials terminal wizard. Agent MCP cannot read or save these files, including through direct tool calls. Its internal CLI review/save services operate only with Sandbox authorization or an exact existing Development grant and a user-selected root .env or .env.local file. Saving does not require a startup loader. You are responsible for loading that file when starting the application. A filename alone does not establish the deployment environment.

After saving, the CLI checks every saved Connection key and ingest token against Seamward. Repeat this read-only check at any time:

Code example

seamward setup verify

It checks the selected file, not shell overrides or retained login credentials. CONNECTION VERIFIED means every expected Integration and environment matched at check time. It does not start the app, send observations or persist a success receipt. A failed check leaves saved credentials intact and exits 1.

Saving is opt-in and does not configure Live or legacy Production or Staging. Files contain plaintext secrets, even with owner-only permissions. Keep them out of Git, recordings and shared backups. Before modifying an existing file, the tool saves an owner-only timestamped backup in your user account's .seamward-runtime-backups directory. Recovery is manual: review the backup privately before restoring it, because old tokens may have been revoked. Do not edit the file while saving. These protections cannot defend against malicious software running as your user. Git-ignored files are discoverable; ignoring a file does not hide it from this wizard. Existing matching credentials must have owner-only permissions. Refused permissions require an explicit local correction, not automatic permission changes.

Temporary plaintext is staged in that private directory outside Git, not inside the project. Atomic saving requires both locations to share a filesystem; otherwise it fails without changing the target. A hard crash may leave a private pending.env there. Confirm no save is active before removing an orphan privately.

Successfully saving a file does not prove that your running application loaded it or sent observations. Start your application normally with that file loaded and confirm actual observations.

Explicit startup diagnostic

This is not required for onboarding. If you specifically request an automated startup test, the reviewed saved runtime mode starts the normal command without injected Seamward credentials and requires observations from fresh synthetic traffic. It reads but does not modify the approved local file. Its receipt proves the last reviewed run, not a deployed environment or ongoing service health.

An Integration belongs to the workspace. Each environment has an independent connection for that Integration:

Code example

Workspace  -> Integrations       -> Sandbox connection       -> Live connection

For example, Candidate ATS and Billing webhooks are separate Integrations. Each can have independent Sandbox and Live credentials without duplicating its business identity. Use the Test mode switch in the console header: off and gray selects testing, and on and blue selects Live. Testing pages show a bright amber Test mode banner with dark text at the top of the screen, above the sidebar and header. The banner names the selected environment and stays visible while you scroll. The dashboard, Integrations, observations, and incidents follow that environment. Notifications and workspace settings remain shared across modes.

During the compatibility migration, Development and Staging are testing environments, and Production is Live. Existing Staging links keep their exact environment. Entering testing selects Sandbox when available, then Development, then Staging; the console remembers the last testing environment for each workspace. Selecting a mode does not create a connection, copy configuration, change credentials, or change your plan allowance.

The selected environment stays in the URL so a shared link opens the same context. Switching from an integration, observation, or incident detail opens the corresponding list in the destination mode. Unsaved form changes require a discard confirmation; switching is unavailable while an action is running or when the destination environment is missing. A full-page progress animation covers the current view while the destination loads. The control and data change together when loading finishes. With reduced motion enabled, the progress indicator stays still.

Required values

Each connection owns two runtime values:

Code example

SEAMWARD_CONNECTION_KEY=sw_conn_v1.replace_meSEAMWARD_INGEST_TOKEN=sw_ing_replace_me

Variable	Purpose	Secret?
`SEAMWARD_CONNECTION_KEY`	Routes observations to one Integration in its workspace environment	No
`SEAMWARD_INGEST_TOKEN`	Authenticates and signs writes for that Integration	Yes; secret store only
`SEAMWARD_INGEST_URL`	Overrides the default endpoint (`https://api.seamward.com/ingest`) for custom or self-hosted deployments	No

Copy both values from the Integration's Collector setup tab. The token is shown only when issued or rotated. Automatic setup stores it outside the repository in a protected local credential store and reports the environment variable name your deployment needs.

Release context

Deployment metadata links changes to a release. Set it explicitly:

Code example

deployment: {  service: "candidate-api",  release: process.env.RELEASE_VERSION,  commitSha: process.env.GITHUB_SHA,}

The Node.js and framework-neutral PHP collectors also recognize SEAMWARD_SERVICE, SEAMWARD_RELEASE, SEAMWARD_COMMIT_SHA, VERCEL_GIT_COMMIT_SHA, RENDER_GIT_COMMIT, RAILWAY_GIT_COMMIT_SHA, and GITHUB_SHA. Invalid values are ignored instead of breaking the host application. Laravel's published configuration resolves the same known values while configuration is loaded, so cached configuration remains deterministic. See release metadata for deployment recipes.

Environment separation

Set up a Sandbox connection for testing and a separate Live connection for production traffic. On the Integrations list, select Set up Sandbox or Set up Live for the missing connection. Owners and admins can start empty or review selected configuration from the other mode before copying it. Copied contracts start as drafts and copied rules are disabled. Credentials, baselines, observations, incidents, and approval history are not copied. Existing connections are not overwritten by this flow.

Each connection has its own Connection key, ingest token, baselines, and incidents:

Sandbox traffic never changes Live baselines.
Rotating a Sandbox connection's token cannot interrupt Live delivery.
An incident's environment comes from the authenticated Integration, not from caller-supplied payload data.
Revoking one connection's token stops only that observation boundary.

Never reuse a Live connection's token in local or testing deployments. Existing legacy Development, Staging, and Production connections retain their exact credentials and evidence until reviewed migration. Legacy CLI flags select those stored targets; they do not provision or substitute a canonical mode.

The runtime does not need SEAMWARD_ENVIRONMENT. The authenticated Connection key and ingest token select the correct environment. A production deployment therefore needs only the exact generated Connection-key and ingest-token variables printed by:

Code example

seamward deployment env --live

Next steps

Configuration reference: every option, format, and default.
Node.js collector setup: use the published ESM package.
Laravel collector setup: configure named connections with the alpha package.
PHP collector setup: build on the framework-neutral alpha core.

Manage an existing connection

On the Integration page in the desired mode, open Manage this connection. Select declared contracts and rules from its other configured mode, then choose Review copy. Check source and destination revisions and apply that exact review. Contracts start as drafts and rules are disabled. There is no automatic synchronization. Review compensation on the completed copy removes only pristine, unused copied artifacts.

To remove only one mode, choose Review connection deletion, inspect the record counts and pending-work hazards, type the displayed confirmation, and apply. The shared Integration and its other mode are preserved. Deletion is permanent; setup later creates a new connection with new credentials and no restored evidence. Save the review URL for Check operation status after a lost response. Whole-Integration deletion on the Integration page removes all modes.

See Sandbox limits and account usage before sending test traffic.