Smoke Lab tutorial

Check every app connection end to end against built-in test services, without touching a real account.

Smoke Lab is an experimental developer page in Nexus Office that checks every way an app can connect, from sign-in to audit trail, against built-in test services. It ships a fake OAuth provider and two loopback MCP servers, so nothing touches a real vendor, a real account or a real credential.

Use it before you connect real accounts, or after an upgrade, to confirm that connecting, tool discovery, allowed reads, ask-first approvals, blocked calls, schema-change quarantine, revoking and audit evidence all still work. Results land in an Integration matrix with seven paths (P1 to P7) and a screenshot for every step.

Time: 20 minutes
For: Administrators and developers running a private (non-public) Nexus Office install

Before you start

A Nexus Office instance whose deployment exposure is private. Smoke Lab refuses to run on a public, internet-facing deployment. A local_trusted instance is always private.
You are an instance admin, or an owner or admin of the company. The Developer area under Apps is only open to administrators.
To fill in results you need a source checkout of Nexus Office with its dependencies installed, because the browser runner lives at tests/e2e/smoke-lab-browser-runner.mts. The runner uses node --experimental-strip-types, so use a Node version that supports that flag (Node 22.6 or newer).
Playwright with a Chromium browser available to that checkout. If you already have Chromium elsewhere, you can point the runner at it with SMOKE_CHROMIUM_PATH.
The browser runner calls the API without signing in, so point it at a local_trusted instance (the default mode, served at http://127.0.0.1:3100 unless you changed the port).

01Turn on Smoke Lab

Smoke Lab is off by default. It needs two switches on the Experimental settings page: "Apps", which shows the Apps area where Smoke Lab lives, and "Smoke Lab" itself.

Open Settings, then click Experimental under Instance settings.
You can also go straight to the page: its address ends in /company/settings/instance/experimental.
You should seeThe breadcrumb reads Settings > Instance settings > Experimental and a list of toggle cards appears.
Turn on the "Apps" toggle.
Its description reads: "Show the Apps navigation and allow access to app connections, gateways, and advanced app tooling." Without it, the Apps pages send you back to the dashboard.
You should seeThe toggle switches on and "Apps" appears in the main sidebar.
Turn on the "Smoke Lab" toggle.
If a toggle shows a managed badge and cannot be changed, the setting is controlled centrally and must be changed there.
You should seeThe toggle switches on.
Click Apps in the main sidebar, then click Smoke Lab under the Developer heading.
The page address ends in /apps/advanced/smoke-lab. The Developer heading is captioned "Advanced setup for developers. Most teams never open this."
You should seeA page titled "Smoke Lab" with an "Experimental" badge and a "Hands-on tutorial" link opens. The dashboard also gains an "Integration smoke" card.

Note

If you open the page while the Smoke Lab flag is off, it shows "Smoke Lab is turned off" and tells you to turn on Smoke Lab under Instance settings > Experimental.

02Start the test services and install the fixture apps

The "Fixture services" section at the top of the page shows two cards, each with a status (running, stopped or error) and a URL:

Click Start services.
You should seeA "Smoke services started" toast appears and both service cards show running with a green dot and a URL. Cards refresh every 10 seconds.
Click Install fixture apps.
This adds two apps to the company, "Smoke Lab HTTP MCP fixture" and "Smoke Lab stdio MCP fixture", with their connections, tool catalogs and a Smoke Lab profile. It is safe to click again: nothing is duplicated.
You should seeA "Fixture apps installed" toast appears the first time, or "Fixture apps already present" if they were already there.
Note the demo credentials shown under "Fake OAuth demo credentials".
They are [email protected] and smoke-password. These are fixed test values, safe to show, and the only credentials the fake provider accepts.
You should seeThe box shows email: [email protected] and password: smoke-password.

"Fake OAuth 2.0 provider": an in-process OAuth provider that only accepts fixed demo credentials. Its URL ends in /smoke-lab/oauth/authorize.
"HTTP MCP fixture": a small MCP server started on a free loopback port on the same machine.

03Run a smoke test

Be aware of how runs work before you start. The "Run browser smoke now" button in the Runs section only creates an empty run record (toast: "Smoke run started", "The browser runner records each step as it completes."). It does not drive a browser by itself. That record stays running with no steps, and the matrix says "No steps recorded for the selected run yet."

The checks are performed by the browser runner, a script in the Nexus Office source checkout. It opens a real headless Chromium, starts the services, installs the fixtures, signs in to the fake OAuth consent page by typing the demo credentials, walks all seven paths, and posts every step with a screenshot to its own new run, which then appears in the Runs list.

Decide which company the results should land in.
By default the runner creates a new throwaway company named "Smoke Lab Browser Run" followed by a timestamp. To see results in an existing company instead, set SMOKE_COMPANY_ID to that company's id. You can find ids by opening /api/companies on your instance.
The runner also turns on the Smoke Lab flag, adds a "Smoke Scout" agent and creates test rules on the fixture connections in whichever company it uses. A throwaway company keeps that out of your real one.
You should seeYou know whether you will set SMOKE_COMPANY_ID or let the runner create a company.
2
In a terminal at the root of the Nexus Office checkout, run the browser runner against your instance.
Replace the URL with your instance address if it is not on port 3100. Add SMOKE_COMPANY_ID=<id> in front to reuse a company.
```
SMOKE_BASE=http://127.0.0.1:3100 node --experimental-strip-types tests/e2e/smoke-lab-browser-runner.mts
```
You should seeThe terminal prints company=..., smoke_run=..., then a --- P1: ... --- header per path and a PASS or FAIL line for each step.
Wait for the RESULT block at the end.
It prints the company, run id and status, the number of steps per path, how many failed, and how many steps have a screenshot. Screenshots and a result.json summary are saved to SMOKE_SHOT_DIR (default /tmp/pap13350-shots). The process exits with code 0 when everything passed and code 2 when at least one step failed.
You should seeA line such as runId=... status=passed followed by failed=0.
Open Smoke Lab in the company the runner used.
You should seeThe new run is at the top of the Runs list with trigger manual and a passed or failed badge, and the Integration matrix is filled in.

Environment variable	What it does
`SMOKE_BASE`	The instance to test. Default `http://127.0.0.1:3211`, so set it to your real address.
`SMOKE_COMPANY_ID`	Reuse this company instead of creating a new one.
`SMOKE_SHOT_DIR`	Where screenshots and `result.json` are written. Default `/tmp/pap13350-shots`.
`SMOKE_ONLY`	Comma-separated subset of paths to run, for example `P1,P3`.
`SMOKE_TRIGGER`	Trigger recorded on the run: `manual` (default), `ci` or `routine`.
`SMOKE_CHROMIUM_PATH`	Path to a Chromium executable to use instead of the Playwright one.
`SMOKE_FORCE_FAIL`	Adds one deliberate failing step (`forced-failure`) to the first path, to check that failures are reported.

Tip

To try the fake sign-in yourself, open the Fake OAuth 2.0 provider URL from its service card. The page has a "SMOKE TEST - not a real provider" banner. Enter [email protected] and smoke-password and click "Authorize smoke test app". The provider then redirects to a loopback callback that does not load, which is expected.

04Read the results: the seven paths

Each row of the Integration matrix is one way an app can be connected. The runner uses the HTTP fixture for P1, P2, P5, P6 and P7, and the stdio fixture for P3 and P4.

Path	Name in the matrix	What it covers
P1	Remote HTTP · OAuth	HTTP MCP fixture behind the fake OAuth provider. The runner types the demo credentials into the consent page.
P2	Remote HTTP · API key	HTTP MCP fixture with a static bearer key.
P3	Local stdio (template)	stdio fixture via the runtime supervisor.
P4	Plugin integration	Plugin-provided catalog entry and install flow.
P5	Paste-a-config import	Import via Advanced setup.
P6	Token broker / gateway	Run-scoped connection token, with TTL and scope checks. Revoking cuts the token off.
P7	Governance surfaces	Profiles, ask-first rules and quarantine.

05Read the results: the eight columns

Each column is one stage of the governed lifecycle, run in order for every path.

A green check means pass.
A red cross means fail.
An amber dash means skipped.
A faint dot means not run: no step for that cell was recorded in the selected run.

Column	What was checked
Connect	The connection is set up. For P1 this includes signing in on the fake OAuth consent page.
Discover catalog	The fixture's tool catalog is visible in Nexus Office and includes the expected read tool.
Allowed read	A read-only tool call is allowed, returns no error and leaves an audit row.
Ask-first write	A write tool under a require-approval rule waits for approval, is approved and then completes.
Denied call	A tool under a block rule is refused with a reason code.
Schema-change quarantine	When the fixture changes a tool's schema, a catalog refresh quarantines the changed entry. Non-HTTP paths record this through fixture metadata.
Revoke	The connection is disabled (then re-enabled), or for P6 the gateway session is revoked and its token stops working.
Audit evidence	Activity and gateway audit rows exist for the decisions above.

06Read the results: runs, steps and screenshots

Look at the health dot next to the Runs heading.
It describes the selected run. green: finished with no failing steps. amber: still running, cancelled, or has no steps yet (an empty run from "Run browser smoke now" stays amber). red: the run is failed or any step failed, followed by "failing:" and the path names. It says "no runs yet" when there are none.
You should seeFor a clean runner pass the dot is green and reads green.
Click a run in the Runs list to select it.
Runs are listed newest first with their start time, trigger and status badge. The newest run is selected by default. The matrix always shows the selected run.
You should seeThe right panel shows "Started ... · finished ..." and one line per recorded step.
Read a step line.
Each line shows the path and step name, for example P1 · connect-consent, a detail message (on failure, the error), and the duration in milliseconds on the right.
You should seeFailing steps have a red cross and their detail explains what went wrong.
Click View screenshot on a step.
You should seeA full-page screenshot of the Nexus Office screen at that step opens in a new tab.
Check the Integration smoke card on the dashboard.
It summarises the latest run as "All paths passing", "Needs a run", "Failing paths" (with the path names) or "No runs yet", plus "Last run" and a time. Clicking it opens Smoke Lab.
You should seeAfter a clean run the card shows a green dot and "All paths passing".

07Stop, reset and clean up

Click Stop to switch the test services off.
This stops the HTTP MCP fixture and makes the fake OAuth provider reject requests. Your runs and fixture apps are kept.
You should seeA "Smoke services stopped" toast appears and both cards show stopped with "not running" as the URL.
Click Reset to remove everything Smoke Lab created in this company.
Reset stops the HTTP fixture, clears fake OAuth codes and tokens, deletes every smoke run for the company, and removes the two fixture apps and the Smoke Lab profile. It happens immediately, with no confirmation. The fake OAuth provider is left in the running state.
You should seeA "Smoke Lab reset" toast appears, the Runs list reads "No runs recorded yet." and the matrix is empty.
Optionally, turn off the "Smoke Lab" toggle under Instance settings > Experimental.
You should seeSmoke Lab disappears from the Developer list and the Integration smoke card leaves the dashboard.

Warning

If the runner created a throwaway "Smoke Lab Browser Run" company, Reset in your own company does not touch it. Open that company to reset it.

08Run it every day

The checkout includes a routine wrapper, tests/e2e/smoke-lab-routine.mts, built for a daily Nexus Office routine whose agent runs it. It checks the target instance is reachable and not public, turns on the Smoke Lab flag, runs the browser runner with trigger routine under a time budget, and reports back to a control-plane company.

On a pass it comments on the routine issue and attaches screenshots of the Smoke Lab page and the dashboard card. On a real failure it files a high-priority "Smoke Lab failure: <path> / <step>" issue with the failing screenshot. If the instance is unreachable, public, the flag cannot be turned on, the budget runs out or the runner crashes, it records an amber "skipped" note instead of filing a bug.

1
Run the wrapper once by hand with dry-run on.
SMOKE_DRY_RUN=1 logs the issues and comments it would create instead of creating them.
```
SMOKE_BASE=http://127.0.0.1:3100 SMOKE_DRY_RUN=1 node --experimental-strip-types tests/e2e/smoke-lab-routine.mts
```
You should seeLines prefixed with [routine] show the target, the browser run output and the DRY writes it would make.
Set it up as a routine command.
The agent that runs it must have NEXUS_OFFICE_API_URL, NEXUS_OFFICE_API_KEY, NEXUS_OFFICE_COMPANY_ID and NEXUS_OFFICE_RUN_ID in its environment (a routine run provides these). Results are recorded against ROUTINE_ISSUE_ID, which defaults to NEXUS_OFFICE_TASK_ID.
Optional: SMOKE_ONLY to limit paths, SMOKE_SHOT_DIR for screenshots, and SMOKE_BUDGET_MS for the time limit (default 600000, ten minutes).
You should seeEach daily run leaves a pass comment, a failure issue, or an amber skipped note on the routine issue.

Warning

Failure issues are assigned to built-in default agent ids. Set SMOKE_OWNER_DEFAULT, SMOKE_OWNER_UI and SMOKE_OWNER_CTO to agent ids from your own company so failures reach someone who exists.

09Troubleshooting

Smoke lab is disabled

The server returns this (HTTP 404) when the Smoke Lab flag is off.

Open Settings > Instance settings > Experimental and turn on the "Smoke Lab" toggle, then reload the Smoke Lab page.

Smoke lab is only available on private (non-public) deployments

The server returns this (HTTP 403) because the instance is configured with public exposure.

Run Smoke Lab on a private instance instead, for example a local_trusted instance on your own machine. Do not switch a real internet-facing deployment to private just to run it.

Fake OAuth provider service is stopped

The fake OAuth provider was switched off with Stop, so sign-in and token requests are rejected.

Click Start services (or Reset) on the Smoke Lab page and check the "Fake OAuth 2.0 provider" card shows running, then try again.

Invalid smoke OAuth demo credentials

The consent page only accepts the fixed demo values.

Enter [email protected] as the email and smoke-password as the password, exactly as shown under "Fake OAuth demo credentials".

Smoke OAuth redirect_uri must stay on this instance or loopback

The fake provider only redirects to localhost, 127.x.x.x, [::1] or the instance's own address.

Use a loopback or same-instance callback URL, such as the runner's default http://127.0.0.1/callback.

Couldn't start services: Timed out starting Smoke Lab HTTP fixture

The HTTP MCP fixture did not become ready within 5 seconds, and its card may show error with a detail message.

Click Stop, then Start services again. If it keeps failing, check the server logs. The fixture runs from scripts/mcp-fixtures/servers in the install, so that folder must be present.

The matrix stays empty after clicking "Run browser smoke now"

This is expected. The button only creates an empty run record, which stays running with amber health.

Run the browser runner from the checkout (see "Run a smoke test") to record steps. It creates its own run, so select the newest run in the Runs list.

The runner finished but my Smoke Lab page shows no new run

Without SMOKE_COMPANY_ID, the runner creates a new company named "Smoke Lab Browser Run" plus a timestamp and records the run there.

Switch to that company, or run again with SMOKE_COMPANY_ID set to your company's id.

The runner fails right away with a 401 or 403 error on an API call

The runner does not sign in, so it only works against a local_trusted instance.

Point SMOKE_BASE at a local_trusted instance and run it again.

Advanced setup is for administrators

The Developer area, including Smoke Lab, is limited to instance admins and company owners or admins.

Ask an administrator to run Smoke Lab or to give you the admin role in the company.

Smoke Lab tutorial

Before you start

01Turn on Smoke Lab

Open Settings, then click Experimental under Instance settings.

Turn on the "Apps" toggle.

Turn on the "Smoke Lab" toggle.

Click Apps in the main sidebar, then click Smoke Lab under the Developer heading.

02Start the test services and install the fixture apps

Click Start services.

Click Install fixture apps.

Note the demo credentials shown under "Fake OAuth demo credentials".

03Run a smoke test

Decide which company the results should land in.

In a terminal at the root of the Nexus Office checkout, run the browser runner against your instance.

Wait for the RESULT block at the end.

Open Smoke Lab in the company the runner used.

04Read the results: the seven paths

05Read the results: the eight columns

06Read the results: runs, steps and screenshots

Look at the health dot next to the Runs heading.

Click a run in the Runs list to select it.

Read a step line.

Click View screenshot on a step.

Check the Integration smoke card on the dashboard.

07Stop, reset and clean up

Click Stop to switch the test services off.

Click Reset to remove everything Smoke Lab created in this company.

Optionally, turn off the "Smoke Lab" toggle under Instance settings > Experimental.

08Run it every day

Run the wrapper once by hand with dry-run on.

Set it up as a routine command.

09Troubleshooting