Creating a Bridge using shell bridge in Strobes

7 min readEdit

On this page⌄

Overview

A shell is a connection that lets Strobes run commands on a machine, so the AI agent can test systems that the Strobes cloud cannot reach directly. A Shell Bridge is the simplest way to create one. You download a small agent to the machine, run one connect command, and the machine connects out to Strobes. No inbound firewall ports need to be opened. This article shows you how to create a Bridge shell, and explains how it differs from an SSH shell so you can choose the right one.

Why Is It Needed?

Many targets sit inside private networks, such as internal applications, IP ranges, and code repositories. A shell inside that network gives the agent a place to run its tools from. A Bridge shell does this without changing your firewall, which makes it easy to approve and quick to set up.

Bridge or SSH: Which Shell Should I Choose?

Strobes supports two shell types. Both let the agent run commands inside your network. They differ in how the connection is made.


Bridge

SSH (Jumphost)

How it connects

The machine connects out to Strobes over HTTPS

Strobes connects in to your server over SSH

Inbound firewall rules

None needed

Port 22 (or your SSH port) must be open to Strobes

What you set up

Download an agent and run one command

Generate SSH keys, store them in the Credential Manager, and enter the host, user, and port

Where it can run

Any machine that can reach Strobes outbound, such as a server, VM, or laptop

A dedicated server that Strobes can reach by public IP or VPN

Stays connected

While the agent process is running, or permanently if installed as a service

While the SSH server is reachable

Credentials

A Strobes API key, used once in the connect command

An SSH key or password stored in the Credential Manager

Choose it when

You cannot or do not want to open inbound ports, or you want the fastest setup

You already run a hardened jumphost and can allow SSH from Strobes

If you are not sure, choose Bridge. It works in most environments without any firewall change. For the SSH option, see "Setting up a Jumphost (SSH shell)".

Prerequisites

Before you start, make sure you have:

  • Owner or Manager access to your Strobes account.
  • Terminal access to the machine you want to connect: PowerShell as Administrator on Windows, or Terminal on Linux or macOS.
  • Outbound internet access from that machine to your Strobes URL.
  • Access to Settings > API Access to get your API key.

Part 1 — Create the Shell in Strobes

Step 1 — Click Settings in the Left Sidebar

Click Settings in the left sidebar. The Settings section opens with a submenu of configuration options.

Creating a Bridge using shell bridge in Strobes: Step 1 — Click Settings in the Left Sidebar (screenshot 1)

Step 2 — Click Shells

Click Shells in the Settings sidebar. The Shells page opens showing a table of existing shells and a Download Shell Bridge section with agent binaries for each supported operating system.

Creating a Bridge using shell bridge in Strobes: Step 2 — Click Shells (screenshot 2)

Step 3 — Click Create Shell

Click the Create Shell button in the top right corner of the Shells page. A form appears to configure the new shell.

Creating a Bridge using shell bridge in Strobes: Step 3 — Click Create Shell (screenshot 3)

Step — 4 Select Bridge as the Shell Type

Click the Type dropdown and select Bridge. Bridge is the shell type that uses the outbound agent — no inbound firewall ports are required.

Creating a Bridge using shell bridge in Strobes: Step — 4 Select Bridge as the Shell Type (screenshot 4)

Step 5 — Enter a Name and Description for the Shell

Click the Name field and type a name for this shell. Use a name that identifies the machine or purpose — for example, Production Server or Dev Machine.

Creating a Bridge using shell bridge in Strobes: Step 5 — Enter a Name and Description for the Shell (screenshot 5)

Step 6 — Click Create

Click Create. Strobes creates the shell record and the Bridge Shell Setup modal opens automatically.

Creating a Bridge using shell bridge in Strobes: Step 6 — Click Create (screenshot 6)

Part 2 — Download the Shell Bridge Agent

Step 7 — Review the Bridge Shell Setup Modal

Review the Bridge Shell Setup modal. The modal has two sections:

  • Download buttons — one for each supported platform: Linux (x86_64), Linux (ARM64), macOS (Apple Silicon), and Windows (x86_64).
  • "Then run:" section — a pre-filled connect command with your Organization ID and Bridge ID already inserted. The only value you need to replace is YOUR_API_KEY.
Creating a Bridge using shell bridge in Strobes: Step 7 — Review the Bridge Shell Setup Modal (screenshot 7)

Step 8 — Click the Download Button for Your Operating System

Click the download button that matches the machine you want to connect:

  • Linux (x86_64) — for most Linux servers and desktops.
  • Linux (ARM64) — for ARM-based Linux machines (e.g. Raspberry Pi, AWS Graviton).
  • macOS (Apple Silicon) — for Macs with M1/M2/M3 chips.
  • Windows (x86_64) — for Windows machines.

The agent binary downloads to your machine. The button shows a download progress percentage while the file is being saved.

Creating a Bridge using shell bridge in Strobes: Step 8 — Click the Download Button for Your Operating System (screenshot 8)

Step 9 — Copy the Connect Command from the Modal

Copy the connect command shown in the "Then run:" section. The command already contains your Strobes URL, Organization ID, and Bridge ID. You will complete it in a later step by replacing YOUR_API_KEY with your actual key. Keep this command available — paste it into a text editor for easy editing.

Creating a Bridge using shell bridge in Strobes: Step 9 — Copy the Connect Command from the Modal (screenshot 9)

Part 3 — Get Your API Key from Strobes

Step 10 — Click API Access in the Settings Sidebar

Click API Access in the Settings sidebar. The API Access page opens, showing your API key (masked) and your Organization ID.

Creating a Bridge using shell bridge in Strobes: Step 10 — Click API Access in the Settings Sidebar (screenshot 10)

Step 11 — Click the Eye Icon to Reveal Your API Key

Click the eye icon (👁) next to the API key field. The key is revealed as a full string of characters.

Creating a Bridge using shell bridge in Strobes: Step 11 — Click the Eye Icon to Reveal Your API Key (screenshot 11)

Step 12 — Copy the API Key

Click and drag to select the full API key, then copy it (Ctrl+C on Windows/Linux, Cmd+C on Mac). Be careful to select the entire key without any extra spaces.

Creating a Bridge using shell bridge in Strobes: Step 12 — Copy the API Key (screenshot 12)

Part 4 — Run the Connect Command on Your Machine

Step 13 — Paste Your API Key into the Connect Command

Open your text editor and locate the connect command you copied in Step 9. Replace the YOUR_API_KEY placeholder with the API key you copied in Step 12. The complete command should look like this:

Text
./strobes-shell-agent connect \
  --url https://<your-strobes-url> \
  --api-key <YOUR_API_KEY> \
  --org-id <YOUR_ORG_ID> \
  --bridge-id <YOUR_BRIDGE_ID> \
  --name "<YOUR_SHELL_NAME>"

All values except <YOUR_API_KEY> are already pre-filled from the modal.

Note: Copy the path of the downloaded binary and paste it.

Creating a Bridge using shell bridge in Strobes: Step 13 — Paste Your API Key into the Connect Command (screenshot 13)

Step 14 — Open the Terminal on Your Machine

Creating a Bridge using shell bridge in Strobes: Step 14 — Open the Terminal on Your Machine (screenshot 14)

Open a terminal on the machine you are connecting:

  • Windows — Open as Administrator PowerShell (search for "PowerShell" in the Start menu).
  • Linux / macOS — Open Terminal.

Step 15 — Navigate to the Folder Containing the Downloaded Agent

Navigate to the folder where the agent binary was downloaded. By default this is the Downloads folder.

  • Windows (PowerShell): cd "$env:USERPROFILE\Downloads"
  • Linux / macOS: cd ~/Downloads

Step 16 — (Linux / macOS only) Make the Binary Executable

Windows does not require this step.

On Linux or macOS, run the following command to make the binary executable before running it:

Terminal
chmod +x strobes-shell-agent

Step 17 — Run the Connect Command

Creating a Bridge using shell bridge in Strobes: Step 17 — Run the Connect Command (screenshot 15)

Paste the completed connect command into the terminal and press Enter.

Windows (PowerShell) / Linux / macOS::

Text
./strobes-shell-aent connect --url https://<your-strobes-url> --api-key <YOUR_API_KEY> --org-id <YOUR_ORG_ID> --bridge-id <YOUR_BRIDGE_ID> --name "<YOUR_SHELL_NAME>"

Step 18 — Confirm the Agent Is Connected

Creating a Bridge using shell bridge in Strobes: Step 18 — Confirm the Agent Is Connected (screenshot 16)

The terminal displays a confirmation block when the agent connects successfully:

Text
Strobes Shell Bridge Agent v0.3.x
  Bridge ID:    <YOUR_BRIDGE_ID>
  Name:         <YOUR_SHELL_NAME>
  Org:          <YOUR_ORG_ID>
  Server:       https://<your-strobes-url>
  CWD:          <current working directory>

Leave the terminal window open. Closing it will disconnect the agent. The shell remains connected as long as this process is running.

Please wait until the status turns "Connected" on the Strobes instance.

Part 5 — Verify the Shell Status in Strobes

Step 19 — Return to Settings > Shells

Return to Settings > Shells in Strobes. The shell you created now appears in the table with:

  • Type: Bridge
  • Status: Connected
  • State: Active

The shell is ready to use in your security assessments.

Creating a Bridge using shell bridge in Strobes: Step 19 — Return to Settings > Shells (screenshot 17)

Tips

Rename the downloaded file to remove spaces before running it on Windows. Windows PowerShell has trouble with file paths that contain spaces and parentheses (such as strobes-shell-agent-windows-amd64 (5).exe). Right-click the file in File Explorer, select Rename, and simplify the name to strobes-shell-agent.exe before running the connect command.

Keep the terminal window open while the shell is in use. The agent process must be running for Strobes to communicate with the shell. If you close the terminal, the shell status changes to Disconnected. Run the connect command again to reconnect.

To run the agent permanently on Windows, use the one-line installer. Open PowerShell as Administrator and run:

Text
irm https://<your-strobes-url>/api/v1/organizations/<YOUR_ORG_ID>/ai/bridge/install.ps1 | iex

This downloads the agent, installs it to a permanent location, and registers it as a scheduled task that starts automatically at logon.

To run the agent permanently on Linux, set it up as a systemd service. Create a service file that runs the connect command on startup so the shell reconnects automatically after reboots.

The Bridge ID is unique to each shell. If you create multiple shells, each has its own Bridge ID from the modal. Use the correct Bridge ID in the connect command for each machine.

Your API key grants full access to your organization. Treat it like a password — do not share it or store it in version-controlled files.