---
title: "Walkthrough: Run the Device & Gateway individually against a hosted TrustBridge (Windows/Linux/macOS)"
description: .
---

[Skip to content](https://portal.sandgrain.eu/knowledge-base/walkthrough-run-the-device-gateway-individually-against-a-hosted-trustbridge-windows#main-content)

English

Show submenu for translations

![SandGrain\_Logo\_RGB\_white-bijgesneden (1)](https://portal.sandgrain.eu/hs-fs/hubfs/SandGrain_Logo_RGB_white-bijgesneden%20(1).png?width=427&height=83&name=SandGrain_Logo_RGB_white-bijgesneden%20(1).png)

Open main navigation

Close main navigation

- English
  
  Show submenu for translations
- [Contact us](https://portal.sandgrain.eu/login)

[Contact us](https://portal.sandgrain.eu/login?hsLang=en)

 How can we help you?

- There are no suggestions because the search field is empty.

1. [Knowledge Base](https://portal.sandgrain.eu/knowledge-base?hsLang=en)
2. [SDK](https://portal.sandgrain.eu/knowledge-base/sdk?hsLang=en)
3. [SandGrain SDK](https://portal.sandgrain.eu/knowledge-base/sdk?hsLang=en#sandgrain-sdk)

October 6, 2026

# Walkthrough: Run the Device & Gateway individually against a hosted TrustBridge (Windows/Linux/macOS)

## This is for the users who already have a TrustBridge deployed remotely and just want to run the native SandGrain Gateway and Device individually against it.

 **This is the easy setup.** Your TrustBridge is already running in the public environment, which means all the heavy machinery (database, message broker, backend, frontend, cloud agent) is taken care of. All you need to run on your laptop are two small programs: the **Gateway** and the **Device**. You won't even need Docker Desktop.

**By the end of this guide**, your Device will talk to your Gateway, your Gateway will talk to the hosted TrustBridge, and you'll run a full mutual authentication round-trip to the cloud.

### How is this different from the full-stack guide?

|  | **Full-stack guide** | **This guide** |
| --- | --- | --- |
| TrustBridge | You run it yourself in Docker | **Already hosted** |
| How you launch | One script starts everything | **For windows:** `run_gateway.ps1` and `run_device.ps1` each in its own window. **For Linux/macOS:** `run_gateway.sh` and `run_device.sh` each in its own window. |
| Docker Desktop | Required | **Not needed** |
| Cloud agent | Runs on your laptop | Runs in the cloud |

Everything the Gateway and Device need from TrustBridge (authentication messages, triggers, the device whitelist) arrives automatically over MQTT. Your laptop only runs the two SandGrain programs.

### Topology

![image1-1](https://portal.sandgrain.eu/hs-fs/hubfs/image1-1.png?width=670&height=58&name=image1-1.png)

 

Think of it like this: the **Device** and **Gateway** both live inside the same Linux environment (WSL2) on your laptop, so they talk to each other locally at `127.0.0.1:8080`. Only the **Gateway** reaches out to the internet - it connects to the hosted TrustBridge's message broker.

**Prerequisites:**

- [*Prerequisites on Windows*](https://portal.sandgrain.eu/knowledge-base/install-prerequisites-on-windows?hsLang=en) for Windows OS  and
- [*Prerequisites on Linux* or *Prerequisites on macOS*](https://portal.sandgrain.eu/knowledge-base/install-prerequisites-on-macos?hsLang=en) for Linux/macOs.
- [*Get the Code & Run the Setup Script*](https://portal.sandgrain.eu/knowledge-base/get-the-code-run-the-setup-script?hsLang=en) completed, repo on [`release/v3.6.0`](https://github.com/SandGrain-CyberRock/SandGrain-TrustBridgeSDK/tree/release/v3.6.0).

### Step 1: Check you're in the right place

Open PowerShell and confirm your branch and scripts:

```
cd C:\path\to\SandGrain-TrustBridgeSDK\SandGrain-SDK git branch   # should show: * release/v3.6.0 
```

### Step 2: Start the Gateway (window 1)

**For Windows:** 

Open a PowerShell window in `SandGrain-SDK` and run:

```
.\run_gateway.ps1
```

It runs run\_gateway.sh inside WSL, which prompts for the connection.

**For Linux/macOS:**

Open a terminal window in `SandGrain-SDK` and run:

```
bash run_gateway.sh
```

Now, the script will ask a few questions. Here's exactly what to answer:

| **When it asks...** | **Type...** | **Why** |
| --- | --- | --- |
| Cloud / BE host | `<public_url/ip>` | That's your hosted TrustBridge |
| MQTT broker host | just press **Enter** | It defaults to the host above |
| MQTT port | `1883` |  |
| MQTT username | leave **empty**, press Enter | The broker doesn't need credentials |
| MQTT password | leave **empty**, press Enter | Same |
| Gateway listen port | `8080` | This is where your Device will connect |

![image2-2](https://portal.sandgrain.eu/hs-fs/hubfs/image2-2.png?width=670&height=380&name=image2-2.png)

💡 **Nice to know:** your answers are saved to `.env.gateway`, so next time you can just press Enter through everything. Add `--no-build` to skip rebuilding too.

![image3-1](https://portal.sandgrain.eu/hs-fs/hubfs/image3-1.png?width=670&height=313&name=image3-1.png)

**You'll know it worked when you see:**

```
[GW] Connected to MQTT broker at 52.220.111.145:1883 [GW] Subscribed to whitelist sandgrain/v1/gw/whitelist [GW] channel_0 listening on :8080
```

Your Gateway is up, connected to the cloud, and waiting for the Device.

***One warning you can safely ignore**:* the Gateway tries a quick `curl` to the backend on port 3000. If that port isn't open to you, it prints a warning and moves on - the whitelist arrives over MQTT anyway.

### Step 3: Start the Device (window 2)

**For Windows:**

Open a **second** PowerShell window in the same folder and run:

```
.\run_device.ps1
```

**For Linux/macOS:**

Open a **second** terminal window in the same folder and run:

```
bash run_device.sh
```

![image4-1](https://portal.sandgrain.eu/hs-fs/hubfs/image4-1.png?width=670&height=372&name=image4-1.png)

### First, connect your USB Token

 **For Linux/macOS** **-** No usbipd is needed as the Token is already visible natively 

 **For Windows -** The script shows a list of USB devices and asks which one to forward into WSL. Pick the BUSID next to the STMicroelectronics device - for example:

![image5-1](https://portal.sandgrain.eu/hs-fs/hubfs/image5-1.png?width=670&height=398&name=image5-1.png)

```
BUSID   VID:PID      DEVICE                             STATE 1-4     0483:5740    STMicroelectronics Virtual COM     Not shared Enter the BUSID to attach [1-4]:
```

The first run may need an elevated `usbipd bind` - the script tells you if so.

### Then answer the connection questions

| **When it asks...** | **Type...** | **Why** |
| --- | --- | --- |
| Gateway IP / hostname | `127.0.0.1` | The Gateway is on the same machine |
| Gateway port | `8080` | Must match what you set in Step 3 |
| USB serial | nothing - it's auto-detected | It finds `/dev/ttyACM0` on its own |

![image6-1](https://portal.sandgrain.eu/hs-fs/hubfs/image6-1.png?width=670&height=382&name=image6-1.png)

Saved to .env.device. The Device builds, then runs in **--listen** **(BE-driven)** mode with the interactive menu also available.

**You'll know it worked when you see:**

```
[DEV] connected to gateway 127.0.0.1:8080 [READY] Listening for TrustBridge triggers
```

...and over in the Gateway window:

```
[GW] HELLO from device - TID 8000... [PRESENCE] 8000... -> online
```

Your Device is connected and registered with the cloud.

### Step 4: Run your first authentication

Two ways to do it - both end the same way:

**Option A : from the Device menu.** In the Device window, type `1` and press Enter. Done.

**Option B : from the TrustBridge web UI.** Open the hosted TrustBridge in your browser (commonly `http://52.220.111.145` - ask your deployer if unsure), find your device, and click to trigger an authentication.

**Success looks like this**, about 3-5 seconds later, in both windows:

```
[DEV] ... AUT_OK [GW]  ... Flow completed OK
```

That's it - your Device just completed a mutual authentication that round-tripped through the hosted cloud. 

### What "pass" looks like

| **Check** | **Expected** |
| --- | --- |
| Gateway → broker | Connected to MQTT broker at 52.220.111.145:1883 |
| Device → gateway | connected to gateway 127.0.0.1:8080 + HELLO ... TID on the Gateway |
| Presence | PRESENCE 8000... -\> online |
| Auth verdict | AUT\_OK + \[GW\] Flow completed OK |

### Something not working?

| **What you're seeing** | **What to do** |
| --- | --- |
| `MissingTokenError` (error\_code=10) | Your Token isn't enrolled yet. Enroll it in the TrustBridge web UI, then try again. Nothing is wrong with your setup. |
| Gateway says port in use | Something else has port 8080. Re-run the Gateway with port `18080`, and use `18080` for the Device too. |
| Gateway never says "Connected to MQTT broker" | It can't reach the cloud. Check the host is up, port 1883 is open to you (firewall), and you left username/password empty. |
| Device can't open `/dev/ttyACM0` | The USB forward didn't stick. In an **admin** PowerShell: `usbipd bind --busid <BUSID>`, then `usbipd attach --wsl --busid <BUSID>`. |
| Auth hangs early | If you've customized anything to talk to a broker directly, always use `127.0.0.1` — never `localhost` (Windows resolves it to IPv6 and the connection silently dies). |
| A `curl ... whitelist` warning | Totally harmless — ignore it. |
| Builds are slow | Add `--no-build` to either script to reuse the last build. |

### When you're done

Press **Ctrl+C** in each window.

In case of **Windows OS**, give the Token back to Windows:

```
usbipd detach --busid <BUSID> 
```

In case of **Linux/macOS**, there is nothing to detach - the Token was read natively, never forwarded.

#### Launcher quick reference

| **Script** | **What it does** | **Remembers your answers in** | **Handles the USB Token?** |
| --- | --- | --- | --- |
| **Windows:** |  |  |  |
| `run_gateway.ps1` | Runs the Gateway in WSL | `.env.gateway` | No. The Gateway doesn't need it |
| `run_device.ps1` | Runs the Device in WSL | `.env.device` | Yes. Forwards it automatically |
| **Linux/macOS:** |  |  |  |
| `run_gateway.sh` | Runs the Gateway in terminal | `.env.gateway` | No. The Gateway doesn't need it |
| `run_device.sh` | Runs the Device in terminal | `.env.device` | Yes. Forwards it automatically |

 

- [User Documentation](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#main-content)

    - [Quick Starter Guide](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#quick-starter-guide)
    - [User Manual](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#user-manual)
    - [Whitepaper](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#whitepaper)
    - [Token Leaflet](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#token-leaflet)
    - [Claim Token Procedure](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#claim-token-procedure)
    - [Daisy Chain](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#daisy-chain)
    - [Release Note](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#release-note)
    - [Naming Convention](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#naming-convention)
    - [SandGrain SDK](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#sandgrain-sdk)
    - [TrustBridge](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#trustbridge)
- [API Documentation](https://portal.sandgrain.eu/knowledge-base/api-documentation?hsLang=en#main-content)

    - [Device API Integration](https://portal.sandgrain.eu/knowledge-base/api-documentation?hsLang=en#device-api-integration)
    - [Daisy Chain and Attestation](https://portal.sandgrain.eu/knowledge-base/api-documentation?hsLang=en#daisy-chain-and-attestation)
- [SDK](https://portal.sandgrain.eu/knowledge-base/sdk?hsLang=en#main-content)

    - [Core Functions](https://portal.sandgrain.eu/knowledge-base/sdk?hsLang=en#core-functions)
    - [SandGrain SDK](https://portal.sandgrain.eu/knowledge-base/sdk?hsLang=en#sandgrain-sdk)

[![SandGrain\_Logo\_RGB\_white-bijgesneden (1)-1](https://portal.sandgrain.eu/hs-fs/hubfs/SandGrain_Logo_RGB_white-bijgesneden%20(1)-1.png?width=427&height=83&name=SandGrain_Logo_RGB_white-bijgesneden%20(1)-1.png "SandGrain_Logo_RGB_white-bijgesneden (1)-1")](https://portal.sandgrain.eu/?hsLang=en)

<https://www.facebook.com/> <https://www.twitter.com/> <https://www.instagram.com/> <https://podcasts.apple.com/> [mailto:email@email.com](mailto:email@email.com)

Copyright © 2026, sandgrain.eu