To connect StackBob.ai to an app that is hosted inside your private network and is not accessible from the internet, deploy StackBob On-Prem Bridge. The bridge runs as a container in your network and connects outbound to StackBob.ai. StackBob NCAP™ can then reach the app without inbound firewall rules or a VPN. Apps that are accessible from the internet connect through a Direct Internet Connection instead.
In this guide, you select On-Prem Bridge as the app’s connection type and generate an installation command in StackBob.ai. Then verify the bridge image, and run the bridge container on a host in your network. When you finish, the bridge is connected to StackBob.ai, and you can continue with the NCAP™ Integration setup for the app.
This guide uses Atlassian Suite as the example managed app. The steps are the same for any managed app. For the bridge architecture and security controls, see StackBob On-Prem Bridge architecture and security article
Roles
A bridge deployment involves two roles. One person can hold both.
Role | Responsibilities | Steps |
StackBob.ai admin | Holds the Org Admin role in StackBob.ai. Selects the connection type, generates the installation command, and confirms the connection. | 1, 2, 5 |
Infrastructure administrator | Has administrative access to a host in the network where the app runs. Verifies the image and runs the bridge. | 3, 4 |
⚠️ If the roles are held by different people, the StackBob.ai admin needs to send the installation command to the infrastructure administrator through a secure channel (as it contains the secret token), together with a link to this article.
Prerequisites
In StackBob.ai
A StackBob.ai organization where you hold the Org Admin role. See Create your StackBob Org.
The managed app added to your StackBob.ai Org. See Quickstart: Connect your first managed app.
In your network
A host that can reach the managed app and run Docker containers, such as a Linux server or virtual machine.
Permission to run Docker containers on the host.
Sigstore
cosign, installed on the host or on a workstation that can reachpublic.ecr.aws.The network access listed in the following table.
Direction | Destination | Port | Purpose |
Outbound |
| TCP 443 | Tunnel connection to StackBob.ai |
Internal | Managed app host | App port, such as 443 | Connections to the app |
Internal | Internal DNS | 53 | Resolving the app hostname |
Outbound, during installation and upgrades |
| TCP 443 | Image download. Not required if you use an internal registry mirror. |
Inbound | — | — | None |
✅ For production deployments, StackBob.ai recommends a dedicated Linux server or virtual machine, placed in a network segment that can reach only DNS and the managed app hosts.
ℹ️ If your environment cannot run Docker containers, for example a Windows Server host, contact StackBob.ai support. We will work with you to provide a suitable deployment option.
Step 1. Select On-Prem Bridge as the connection type in StackBob.ai
Performed by the StackBob.ai admin.
In StackBob.ai, open the managed app. The app initial status is Setup Required.
Under Select App Connection Type, select On-Prem Bridge, and then select Set Up Sync.
Step 2. Create the bridge in StackBob.ai and copy the installation command
Performed by the StackBob.ai admin.
Under Select On-Prem Connection, select New StackBob On-Prem Bridge, and then select Continue.
Under Name the Bridge, keep the default name or select the pencil icon to change it. The default name combines your organization name and the app name. The bridge will appear under this name in your StackBob.ai Organization Settings.
Under Run the Docker container using the installation command, select copy.
⚠️ The installation command contains the secret token for this bridge node. Share it only through a secure channel, and do not store it in tickets, chat messages, or shared documents.
Connection Status shows Bridge Pending and will automatically change to Bridge Established when the bridge connects. Until then, Continue option is unavailable.
Step 3. Verify the bridge image
Performed by the infrastructure administrator.
Docker does not verify image signatures when it pulls an image. Before you run the bridge, confirm that the image was built and signed by StackBob.ai’s CI pipeline.
Note the version tag at the end of the installation command, such as
2.1.0.Run the following command, replacing
<version>with that tag:
bashcosign verify \
--certificate-oidc-issuer https://gitlab.com \
--certificate-identity 'https://gitlab.com/mindswede/stackoon//.gitlab-ci.yml@refs/heads/main' \
public.ecr.aws/p2d9q2r4/stackbob-bridge:<version>Confirm that the command completes without errors.
⚠️ If verification fails, do not run the image. Contact StackBob.ai support.
ℹ️ To run the bridge from an internal registry, mirror the verified image with cosign copy. Then replace the image reference in the installation command with your registry path. Do not mirror with docker pull and docker push, because they do not copy signatures, and the mirrored image cannot be verified.
bash
cosign copy public.ecr.aws/p2d9q2r4/stackbob-bridge:<version> \
registry.example.com/stackbob-bridge:<version>
⚠️ If the container stops or reconnects repeatedly, see Troubleshoot StackBob On-Prem Bridge connections.
Step 4. Run the bridge container
Performed by the infrastructure administrator.
1. On the host, run the installation command from step 2. With Podman, use podman in place of docker.
bash
docker run -d --restart=always --network host \
-e STACKBOB_TOKEN=<token> \
public.ecr.aws/p2d9q2r4/stackbob-bridge:<version>
Part | Purpose |
| Runs the container in the background |
| Restarts the bridge after a host reboot or a failure |
| Uses the host’s DNS and network routes to reach the app |
| Provides the bridge node’s token |
2. Confirm that the container is running. The docker run command prints a container ID. To view the bridge’s logs, run docker logs <container-id>.
⚠️ Membership in the docker group on the host is equivalent to root access. Restrict Docker access to the administrators who manage the bridge.
ℹ️ On macOS and on Windows 10 or 11, the container runs in the Linux virtual machine provided by Docker Desktop, Colima, OrbStack, or Podman. Confirm that the app hostname and your internal DNS are reachable from that environment.
Optional settings
Add the following settings to the installation command as your environment requires:
Corporate proxy. If outbound traffic must pass through a proxy, set
HTTPS_PROXY. The proxy must permit WebSocket traffic overCONNECTtobridge.stackbob.ai:443.TLS inspection. StackBob.ai recommends excluding
bridge.stackbob.aifrom TLS inspection. If inspection cannot be bypassed, mount your inspection CA certificate and setSSL_CERT_FILE. The CA is added to the public root certificates.Token file. To keep the token out of environment variables, store it in a file and set
STACKBOB_TOKEN_FILEin place ofSTACKBOB_TOKEN. The file must contain only the token. It must also be readable by the container’s non-root user (UID 65532).JSON logs. To forward logs to a SIEM, set
STACKBOB_LOG_FORMAT=json.Debug logging. For troubleshooting, set
STACKBOB_DEBUG=1to log each relayed connection.
Example with a proxy, an inspection CA, a token file, and JSON logs:
bash
docker run -d --restart=always --network host \
-e HTTPS_PROXY=http://proxy.example.com:8080 \
-v /etc/stackbob/corp-ca.pem:/etc/stackbob/corp-ca.pem:ro \
-e SSL_CERT_FILE=/etc/stackbob/corp-ca.pem \
-v /etc/stackbob/token:/etc/stackbob/token:ro \
-e STACKBOB_TOKEN_FILE=/etc/stackbob/token \
-e STACKBOB_LOG_FORMAT=json \
public.ecr.aws/p2d9q2r4/stackbob-bridge:<version>
⚠️ If Connection Status remains Bridge Pending, see Troubleshoot StackBob On-Prem Bridge connections.
Step 5. Confirm the connection in StackBob.ai
Performed by the StackBob.ai admin.
Return to the app page in StackBob.ai. When the bridge connects, Connection Status changes from Bridge Pending to Bridge Established.
Select Continue to proceed with the NCAP™ Integration setup for the app.
All your bridges are also listed under Settings › Organization Settings › Integrations › On-Prem Bridges. It appears as an On-Prem Bridge Group, with its nodes, status, and the number of connected apps. The node you deployed in this guide is the Primary Node.
Add a backup node (optional)
A backup node can run on a second host and provide failover for the bridge. StackBob.ai checks the nodes of a bridge group in order and uses the first node that can reach the app. If the primary host becomes unavailable, traffic moves to a backup node automatically. A bridge group can include more than one backup node.
The second host must meet the same prerequisites as the primary host. It needs network access to the app, to your internal DNS, and to bridge.stackbob.ai.
✅ To get the most from failover, place the backup node in a different failure domain from the primary node, such as another hypervisor, rack, or availability zone.
Steps a, b, c and e are performed by the StackBob.ai admin. Step d is performed by the infrastructure administrator.
a. In StackBob.ai go to Settings › Organization Settings › Integrations › On-Prem Bridges.
b. In the row for the bridge group, select more actions (⋮), and then select Add backup node.
c. In the Add Backup Node panel that opens, under Run the Docker container using the installation command, select Generate secret command, and then copy the installation command.
⚠️ The command contains the secret token for the backup node. Share it only through a secure channel. Do not reuse the Primary Node’s installation command on the second host, because each node has its own token.
d. On the second host, complete Verify the bridge image and Run the bridge container (as described in Step 3 nd Step 4), using the backup node’s installation command.
e. In StackBob.ai on the On-Prem Bridges tab, confirm that the backup node’s status changes from Bridge Pending to Bridge Established.
Terminate a node or a bridge group
Terminating a backup node revokes that node’s token. Terminating a bridge group revokes the tokens of all its nodes.
Removing a node or a bridge group takes two actions, which can be done in either order. The StackBob.ai admin terminates the node or group in StackBob.ai, which revokes its token. The infrastructure administrator removes the bridge container from the host. If you suspect that a node’s installation command or token has been exposed, terminate the node in StackBob.ai immediately.
Terminate a single node
Terminate a single node when you no longer need it, for example a backup node on a decommissioned host, or when the node’s installation command has been exposed.
Go to Settings › Organization Settings › Integrations › On-Prem Bridges.
In the row for the node, select more actions menu (⋮), and then select Terminate Node.
Remove the bridge container from the node’s host, as described in Remove the bridge container below.
The other nodes in the bridge group continue to serve the connected apps.
⚠️ If no other node in the group has the status Bridge Established, StackBob NCAP™ can no longer reach the apps that were connected through the bridge.
Terminate the entire bridge group
Go to Settings › Organization Settings › Integrations › On-Prem Bridges.
In the row for the bridge group, select ⋮, and then select Terminate Entire Group.
Remove the bridge container from each host that ran a node of the group, as described in the next section.
Remove the bridge container
After you terminate a node or a bridge group, remove the bridge container from each affected host. To find the container ID, run docker ps.
bash
docker rm -f <container-id>
ℹ️ After termination, the bridge container exits with code 3 because its token is revoked. The container was started with --restart=always, so Docker keeps restarting it until it is removed.
ℹ️ Stopping the container on the host disconnects the node immediately but does not revoke its token. To revoke access permanently, terminate the node or the bridge group in StackBob.ai.
Next steps
Continue the NCAP™ Integration setup for the app. See Quickstart: Connect your first managed app.







