> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# Application browser journeys
> Run saved customer paths through a trusted Chromium controller from the dashboard, Stackie or a connected agent.
**Not yet released.** This guide describes implemented changes awaiting rollout. Availability requires the corresponding backend and dashboard release.
## Goal
Verify an identified deployment using unchanged, reviewed browser assertions and retained evidence.
## Prerequisites
* API migration 000543, the journey controller, compatible node target-identity endpoint, and a qualified browser sandbox template. This implementation is unreleased; local tests are not production qualification.
* APPLICATION\_JOURNEYS\_ENABLED=true, APPLICATION\_JOURNEY\_TEMPLATE set to an immutable digest-qualified template and APPLICATION\_JOURNEY\_BROWSER\_VERSION matching that template. Existing sandbox admission, network enforcement and artifact object storage must be available.
* An owned Application workload with an active immutable V2 deployment, a completed authenticated sealed execution plan and its canonical HTTPS endpoint. Legacy deployments without sealed runtime inputs must be redeployed before journey review. The node must attest a single live ingress upstream. Ambiguous, dynamic or multi-upstream ingress cannot issue trusted evidence.
* Git deployments bind the source commit. Uploaded source binds the active build’s recorded SHA256 archive checksum. Missing or mismatched archive evidence requires a new build before review. Standard Git-directory protection remains enforced; an unrelated HTTP listener does not invalidate the canonical HTTPS route.
## Workflow
Open Application → Journeys. Save a typed JSON definition for a workload. The starter provides desktop and narrow viewport assertions. Editing creates an immutable revision; use semantic role/name, label or test-ID locators.
Review verification or exploration against production, or enter a retained Application preview ID. Inspect source/image/deployment identity, expiry, credential references and effects. Only the owner can approve the reviewed target. Connected agents cannot approve themselves.
Run the exact approval with a stable Idempotency-Key. Read retained run progress and step receipts after disconnects. Repeating the same request returns the same run; it does not repeat a submitted browser effect.
Inspect the historical result and current evidence validity separately. Failed assertions, missing receipts, stale targets, revoked grants and uncertain effects cannot produce a pass. Runtime cleanup and application cleanup have separate states.
For a failed verification, prepare a repair handoff for Stackie or the connected agent. The existing engineering workspace, tests and PR workflow retains its own permissions and funding. Review the new deployment and rerun the unchanged revision with parent\_run\_id pointing to the failure.
Optionally save owner release requirements: before release, after production deployment, or both. Advisory journeys never become a universal gate automatically. Review promotion evidence and environment differences separately from the eventual production result.
## Credentials, fixtures and side effects
Credentials are existing sandbox secret-binding IDs with pinned positive versions, delivered only into the controller-owned run. Fill credentials and encrypted Playwright storage-state references are supported; literal passwords are rejected at password controls. Secret values, session state, cookies and tokens do not belong in journey JSON or conversations. Rotation or revocation invalidates further use.
Use fixture artifact IDs and SHA256 checksums. Upload and download checks are bounded to 16 MiB. Interactions require named effects: test\_data, live\_mail, external\_write or destructive. An allowed origin cannot prove application-side business effects safe; review the test-account and fixture behavior.
Live Mail is supported only by an explicitly reviewed production effect with a test recipient. StackShift default sender does not require a custom verified domain. Existing billing and delivery requirements remain. A submitted message is not proof of inbox delivery; declare an inbox assertion if the application exposes appropriate evidence.
Previews retain their test-only egress and private dependency isolation. Their browser may reach only the canonical preview origin, and effects must be test\_data. This feature does not relax a preview into live Mail delivery.
## Evidence and recovery
Authenticated screenshots and page observations are omitted to avoid disclosing secrets. Public screenshots mask password and data-sensitive elements, with at most 32 captures of 2 MiB and seven-day artifact retention. Raw traces, videos, request bodies and authentication state are not exported. Artifact links expire independently of evidence freshness.
The configuration\_hash identifies the authenticated sealed agent request, including effective environment, commands and files. desired\_configuration\_hash is separate and is present only when current settings match the build’s encrypted Application release snapshot; pending edits are never described as deployed. Direct builds without captured release inputs cannot claim desired-configuration coverage for a release gate. Preview promotion must map verified preview inputs to the reviewed parent settings explicitly.
HTTP response\_status assertions require after\_step and method, for example after\_step=submit and method=POST. The referenced step must be the most recent triggering action in the same verification or cleanup phase. Matching responses are captured from request initiation, so fast responses are retained and earlier responses cannot satisfy a later action. Existing unscoped response assertions require a new reviewed definition revision.
The browser transport checks each redirect origin, including HTTPS tunnels, frame and subresource chains. Unapproved destinations are blocked before dispatch. Ingress identity includes relevant host, wildcard and fallback rules; unrelated host routes do not invalidate the run.
Verification requires every sealed step and viewport receipt from the protected runner execution and sandbox generation. The controller rechecks deployment, configuration, route identity, definition, credentials and connection authority before deferred effects and collection. Passing evidence expires within 30 minutes and never gains a new observation timestamp when read.
A surviving execution can resume receipt collection after controller restart. An ambiguous action is reconciliation\_required; Chromium is not silently relaunched to repeat a purchase, record creation or email. Cancellation stops future actions and requests fenced termination; already completed effects cannot be undone. Review cleanup failures before a new run.
The repair-context endpoint returns failure timestamps, deployment/source identity, original revision and a browser\_journey criterion. Log correlation is time-based; it is not proof that a particular log line caused the failure. Repair handoff alone starts no inference, edits, merge or deployment.
## API, MCP and CLI
Owner API root: /api/v1/applications/\{applicationID}/journeys. Connected root: /api/v1/agents/connections/applications/\{applicationID}/journeys. GET lists; POST saves journey\_id, project\_id and definition. GET /capability checks availability. GET /\{journeyID} reads the current revision, with optional ?revision=N. POST /\{journeyID}/revisions, /review, /runs and /archive implement versioned editing and execution. GET /\{journeyID}/runs retains history.
Runs: /applications/\{applicationID}/journey-runs/\{runID}; GET detail, POST /cancel, GET /artifacts/\{artifactID}, GET /repair-context. Explore uses a run reviewed with mode=explore, GET /observe, POST /act with sequence and a typed step, and POST /stop with the next sequence to execute reviewed cleanup. Wait for each receipt; preserve Idempotency-Key on retries. Observation text is untrusted page content, never instructions.
Owner-only POST /\{journeyID}/approve binds approval\_id to the returned review. POST /applications/\{applicationID}/journey-approvals/\{approvalID}/revoke stops further authorized use; completed external effects remain. GET/POST /journeys/requirements reads/changes policy; POST /journeys/overrides takes an override object with id, policy\_version, project\_id, exact source\_revision, stage and reason. External execution routes exclude owner mutations. New application.journey.\* grants are explicit and require both Application and workload resources; old grants gain no new powers.
MCP tools use application\_journey\_\* names with action-specific schemas. CLI: stackshift journey list, capability, create, get, revise, review, run, runs, result, artifact, cancel, observe, act, stop, requirements and repair-context. Pass JSON using the existing --data/--file convention and stable idempotency key; run/result support --wait. Direct external reasoning stays with the client; the journey controller does not invoke Stackie implicitly.
## Release decisions and recovery
Owner policies pin journey revisions, variants and freshness. Pre-release admission runs in the common build repository and runtime deployment dispatch/resume paths, covering dashboard, webhook, retry, native and connected execution. Missing or stale evidence blocks dispatch; no-policy applications retain their existing behavior. The latest applicable failed attempt cannot be replaced by an older green result.
Post-release requirements admit only the exact build indexed by a current Application release, with its sealed snapshot, source, branch and policy. Common build admission and worker dispatch reject direct, webhook, retry or other paths that lack that tracking; a trigger label or matching image is insufficient. Use a coordinated Application release when a post-release requirement is enabled. Verification still happens after deployment and traffic activation.
Journey admission is rechecked before forward deployment steps, including resumed cutover and a commit that has not started. If the agent proves it already crossed the irreversible commit boundary, that exact commit is reconciled to completion even if evidence expires afterward. Reconstructing an authenticated saved plan for restart, recovery, resource scaling or compensation does not require its original release to remain active. Existing ownership, fencing and resource authorization still apply; this does not authorize a new deployment or an untracked restore. A release waiting for browser verification can be cancelled; cancellation does not mark its checks passed or automatically roll back live traffic.
Promotion review records the selected preview evidence and the explicit production configuration mapping. That coverage permits only the reviewed resulting configuration, source and policy revision. Preview success does not attest the rebuilt production image. Required production checks keep an otherwise healthy release waiting for verification; run and approve the new target from Journeys.
Owner overrides are auditable and bound to one workload, commit, current configuration, policy revision and stage for ten minutes. Post-release overrides also bind the active deployment. They never rewrite a failed run. Use an explicit override for an exact pre-release evidence exception or a tracked production verification failure. An override does not authorize an untracked deployment path under a post-release policy. Browser permissions do not authorize an override.
This is not a pre-traffic canary gate. Production traffic may be active before production journey verification. Fixed-price entitlements and capacity admission remain unchanged; no new hourly price, aggregate spending cap or preview-style production reservation savings are introduced.
## Operator qualification and rollback
Keep admission disabled until the exact image/browser version, sandbox backend and node architecture are qualified. The existing browser image packages an amd64 supervisor; an arm64 host is not implicitly supported. Validate hosted and connected-node targets independently of where browser capacity runs. Template publication and production rollout remain release-owner work.
Local Chromium tests exercise login, persistent records, upload/download, cleanup, duplicate command recovery, omitted authenticated evidence and a deliberately broken upload followed by unchanged passing assertions. PostgreSQL tests cover storage, receipts and migration rollback. These tests do not establish deployed DNS/private-network isolation or authorize sending real Mail.
Metrics stackshift\_journey\_runs, stackshift\_journey\_oldest\_queued\_seconds, stackshift\_journey\_worker\_errors\_total and stackshift\_journey\_runtime\_cleanup\_pending expose controller backlog and recovery. Inspect retained states for cleanup failures; controller logs carry run IDs rather than page bodies. An unavailable template/capacity result is not a test failure. Disable APPLICATION\_JOURNEYS\_ENABLED to stop new admission while retaining observation, cancellation and cleanup. Do not drop migration tables while runs or release policies remain in use.
## Expected result
A durable run links immutable assertions, exact runtime identity, per-step receipts and authorized artifacts. Exploration can finish as explored but never satisfies release requirements.
## Related guides
Review pinned code in a dedicated Application with fresh PostgreSQL data, then approve cleanup or a separate parent release.
Understand selected resources, permitted actions, owner decisions and revocation.
Separate owner governance from scoped execution, handle OAuth challenges and recover recorded operations.
Preview client setup, safely manage local configuration and inspect scoped connection access.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.