Pre-Deployment Check

Before you install a forwarder anywhere, run two commands on one machine in the network you are about to deploy into: swell verify connectivity and swell verify compatibility. The first tells you whether this network lets Stairwell's endpoints be reached without something in the middle rewriting the traffic. The second tells you what is already on the host that could interfere. Two clean results are your green light, and the rollout that follows is a routine install. A bad result found here costs you one machine and an afternoon instead of a fleet and a week.

Why should I run this before deploying?

The failure this catches most often is a TLS-intercepting proxy, and it is expensive because it does not look like a network problem.

Plenty of enterprise networks route outbound HTTPS through a device that terminates TLS, inspects the plaintext, and re-signs it with the organization's own certificate authority. Browsers on those machines accept it, because that internal authority is trusted locally, so the network looks healthy to everyone who works on it. The forwarder does not accept it, because it verifies that it is talking to Stairwell and not to an intermediary. The install succeeds, the service starts, nothing errors loudly, and no data arrives. By the time somebody notices the gap, the agent is on a thousand machines and you are debugging a fleet rather than a host.

The other two failures in the same family are cheaper to fix and equally easy to miss:

• A firewall that allows the Stairwell web app but not the intake hostnames. The console loads, the forwarder registers, and file data never leaves the building.
• A proxy that passes ordinary HTTPS correctly but interferes with HTTP/2, which the gRPC endpoints ride on.

Each of these is a bypass-list entry before a deployment and a multi-team ticket after one. That is the whole argument for this page being first in the section.

What do I need before I run the checks?

The swell command line tool, on one machine that shares a network path with the machines you plan to deploy to. Install it from Windows, macOS, or Linux.

Two things about where you run it:

• Run it from the network you are deploying into. A pass in the datacenter says nothing about a branch office behind a different proxy, or about a cloud subnet with its own egress rules. If a rollout spans several network paths, check one machine on each.
• Nothing needs to be installed yet. The connectivity check does not need a forwarder, an asset, or a token. The compatibility check does not need a network. You can run both on a candidate machine that has never talked to Stairwell.

One optional extra: to include the end-to-end upload probe described below, you need the asset ID of a machine that is already registered in Stairwell.

How do I check connectivity?

swell verify connectivity probes every public Stairwell endpoint from the machine you run it on, prints each probe as it happens, and finishes with one row per endpoint.

$ swell verify connectivity
Running 4 connectivity probe(s)...

  [1/4] HTTPS https://app.stairwell.com:443 ... OK (109ms)
  [2/4] gRPC  api.app.stairwell.com:443 ... OK (127ms)
  [3/4] HTTPS https://http.intake.app.stairwell.com:443 ... OK (80ms)
  [4/4] gRPC  grpc.intake.app.stairwell.com:443 ... OK (92ms)

RESULT  KIND   ENDPOINT                                   LATENCY  DETAIL
PASS    HTTPS  https://app.stairwell.com:443              109ms
PASS    gRPC   api.app.stairwell.com:443                  127ms
PASS    HTTPS  https://http.intake.app.stairwell.com:443  80ms
PASS    gRPC   grpc.intake.app.stairwell.com:443          92ms

(Skipping upload probe. Pass --asset_id to include a real object upload.)

PASS means more than "the connection opened". It means the endpoint answered over TLS, the response came back through Stairwell's own edge, and the certificate presented was the one Stairwell serves rather than one signed by something local. That last part is what makes this check worth running: an intercepting proxy can produce a connection that looks fine and still fail this row.

Three things to read correctly in that output:

• An HTTP error response still counts as reachable. The probe is testing the path, not your credentials, so a 4xx or 5xx answer and a gRPC authentication error are both passes. What fails a probe is a network or TLS error.
• The four rows are not interchangeable. The first two are the web app and the API, which is what your analysts and your automation use. The last two are the intake endpoints, which is where file data goes. A fleet can register happily while intake is blocked, so the intake rows are the ones that decide whether a deployment will actually collect anything.
• Latency is context, not a verdict. It is there so you can spot a route that is technically working and painfully slow. Each probe is allowed ten seconds before it gives up.

The command exits non-zero when a required probe fails, so you can run it as a gate in whatever tooling pushes your installs rather than reading it by eye on every host.

What if a check fails?

Read the DETAIL column first, because it carries the reason and the reason determines who fixes it.

• possible MITM proxy. The connection completed, but what answered was not Stairwell: either the response did not come back through Stairwell's edge, or the certificate was not the one Stairwell serves. This is TLS inspection, and the fix belongs to whoever runs it. Add Stairwell's hostnames to the decryption bypass list and run the check again.
• A timeout or a refused connection. A firewall or an egress allowlist. The forwarder needs port 443 over HTTPS to *.app.stairwell.com, *.api.stairwell.com, downloads.stairwell.com, and storage.googleapis.com. Allow those, and add them to the TLS inspection bypass list at the same time so you do not solve this problem twice.
• A gRPC row failing while the HTTPS rows pass. A device that handles ordinary HTTPS correctly and interferes with HTTP/2. Proxies that pair TLS inspection with a protocol downgrade are the usual cause.
• WARN instead of FAIL. The two gRPC rows are advisory: a failure on them is reported as a warning and does not make the command exit non-zero. That is deliberate, because some environments reach those endpoints by a different path. Treat a warning as something to resolve before a wide rollout, not as a green light with a footnote.

Re-run the command after every change. It takes seconds, and a fix confirmed on the machine that found the problem is worth more than a fix confirmed in a firewall console.

When should I include the upload probe?

Pass --asset_id when you want to prove the whole ingest path rather than reachability. With the flag set, the check generates a one megabyte random file and uploads it through HTTP intake to the asset you named, so a pass means data from this network actually landed in Stairwell rather than that the door was open.

It is worth the extra step in four situations: before a large rollout, when you open a new site or subnet or cloud region, after any change to proxies or egress rules, and any time the network team tells you something has been adjusted. Reachability and delivery are different claims, and this is the flag that tests the second one.

Two practical notes. The asset ID has to belong to a machine already registered in Stairwell, so this is the probe you run once a pilot host is up and before the fleet follows. And the upload creates a real object attributed to that asset, so point it at a pilot or test machine rather than a sensitive production host.

How do I check host compatibility?

swell verify compatibility reports what is on this host that commonly needs an exclusion or a configuration change: endpoint protection and zero trust or proxy clients it recognizes, the state of the host firewall, and any proxy environment variables that are set.

$ swell verify compatibility
== Stairwell Compatibility Report ==
Generated:  2026-08-26T17:01:02Z
Host:       devbox-mike
Platform:   linux/amd64

No known security agents detected.
Host firewall:
  (unable to determine)

Proxy configuration (environment):
  (none set)

This report was generated locally and has not left your machine.
Share it with Stairwell support only if you choose to.

Read the report in three passes:

1. Detected agents. Anything listed here is software that watches file activity or reroutes traffic, which is also what the forwarder does. That tells you where to set exclusions on the other product, and which vendor's support you may need if the two disagree.
2. Proxy environment variables. If any are set, they apply to processes launched in that environment. Confirm that the proxy configuration you intend for the forwarder is the one you are actually going to get, and that Stairwell's hostnames are reachable through it.
3. Host firewall. Most useful when the connectivity check failed and you are deciding whether the block is on the host or in the network.

--output <path> writes the same report to a file as well as printing it, which is what to use when you want to attach it to a change ticket or keep it with your rollout notes.

What the forwarder itself collects, and what it leaves alone, is a separate control. That lives in the group's policy, covered in Asset Configuration.

Does the compatibility report leave my machine?

No. It makes no network calls and sends nothing to Stairwell. That is what the last two lines of the output are telling you, and it is a design choice rather than a disclaimer.

The check reads local process names, looks for known install paths, asks the host's own firewall tooling for its state, and reads proxy environment variables. Then it prints. If you want Stairwell support to see the result, you send it, deliberately, having read it first. Someone about to run a diagnostic on a production host should know that before they run it, not after.

The corollary is worth stating: the report contains the machine's hostname, its platform, and the names of the security products installed on it. Treat the file the way you would treat any other host inventory output.

What does "unable to determine" mean?

It means the check could not answer, and it is a normal result rather than an error. Asking a host firewall for its state often needs privileges the command was not given, and some hosts are protected by tooling the check does not query. An inconclusive line is not evidence that a host is unprotected, and it is not a reason to stop a deployment.

No known security agents detected reads the same way. It means nothing was recognized from the products the check knows about, not that nothing is installed. That list covers the products which most often conflict with a file-collecting agent, and it is deliberately not exhaustive, so a quiet report on a host you know runs endpoint protection tells you the check did not recognize it.

Neither line blocks a rollout. What blocks a rollout is a failed connectivity probe.

What do I do when I am green?

Install the forwarder. When every connectivity row passes and the compatibility report holds no surprises, the network questions are answered, and what remains is the install procedure for the operating system you are deploying to, which follows this page in this section.

Then confirm the deployment took, in this order:

1. The machine appears under Assets with a recent check-in. See Assets for what that view tells you.
2. Sightings begin arriving for it, which is the signal that the intake path you tested is being used in earnest.
3. The data lands where you expect. Your fleet is partitioned into environments, and a forwarder reporting into the wrong one is a configuration question, not a connectivity one.
4. Collection is tuned for the machines you deployed to, using the group policy described in Asset Configuration.

If Stairwell is new to you and you inherited this rollout from someone else, What Is Stairwell and How Stairwell Works explain what the files you are about to start collecting are for, and Your First Fifteen Minutes is the fastest way to confirm from the console that the deployment is doing its job.