Before you start
- A machine inside the network — Linux (x86_64 or ARM64), macOS on Apple silicon or Windows (x64) — that can reach the systems you want to sync.
- Outbound HTTPS (port 443) from that machine to
bridgestick.com(the downloads) andapi.bridgestick.com(where agents dial). Behind a proxy, setHTTPS_PROXY. - Administrator rights to install the service (
sudoon Linux and macOS, an administrator PowerShell on Windows). - A BridgeStick account: start free or sign in.
1. Create an auth key
In BridgeStick, open Links, create a link for the network (or open it), and add an auth key. Choose whether it is one-off or reusable, when it expires, and whether agents that join with it are pre-approved or wait for your approval. The key (bslk_…) is shown once, with the install command for each system already filled in: copy it now.
2. Install and join
Run one of these on the machine. Replace bslk_… with your auth key. --server defaults to https://api.bridgestick.com; the commands BridgeStick shows you include it.
Linux and macOS
Downloads the agent, verifies it, installs it as a service and joins it.
curl -fsSL https://assets.bridgestick.com/downloads/install.sh | sh -s -- --auth-key bslk_…Debian and Ubuntu (apt)
Adds BridgeStick's signed apt repository, installs the package and joins it.
curl -fsSL https://assets.bridgestick.com/downloads/apt/bridgestick.gpg | sudo tee /usr/share/keyrings/bridgestick.gpg >/dev/nullecho 'deb [signed-by=/usr/share/keyrings/bridgestick.gpg] https://assets.bridgestick.com/downloads/apt stable main' | sudo tee /etc/apt/sources.list.d/bridgestick.listsudo apt-get update && sudo apt-get install -y bridgesticksudo bridgestick up --auth-key bslk_…Windows
In PowerShell, as an administrator.
$env:BRIDGESTICK_AUTH_KEY='bslk_…'; iwr https://assets.bridgestick.com/downloads/install.ps1 -UseBasicParsing | iexAlready installed
On a machine where the bridgestick command is installed.
bridgestick up --auth-key bslk_… --server https://api.bridgestick.comIf bridgestick status says the agent is not running, start its service with sudo bridgestick install-service (an administrator prompt on Windows).
3. Approve the agent
An agent that joined with a key that is not pre-approved shows waiting for approval, in its status and on the link's page. Approve it there; from then on it takes calls. A pre-approved key skips this step.
4. Allow what it may reach
The agent starts with an empty allow list: it reaches nothing until you add rules. Before a connector opens, every host and port it will connect to is resolved and checked against the list, and every file against its folders; anything else is refused. Only the agent enforces the list, so a compromised cloud cannot use it to reach what you did not allow.
| Rule | What it lets through |
|---|---|
internet | Any public address, on any port |
10.0.0.0/8 | A network, on any port |
10.0.0.0/8:5432 | A network, on one port |
10.1.2.3:1433-1434 | An address, on a range of ports |
sap.corp.local:44300 | A host name, and every address it has |
*.corp.local:* | Host names by pattern, on any port |
[fd00::5]:5432 | An IPv6 address, on one port |
path:/srv/exports | Files under a folder (SQLite), by absolute path |
Examples
sudo bridgestick allow add sap.corp.local:44300sudo bridgestick allow add 10.20.0.0/16:1433sudo bridgestick allow add path:/srv/exportssudo bridgestick allow list- A host name is judged by every address it resolves to: a name that leads somewhere else is judged by where it leads. A host-name rule matches by the name itself.
internetadmits public addresses only — never a private, loopback or link-local one.- Give every agent of a link the same rules: each one enforces its own list.
- When the agent runs as a service, run these commands with
sudo(an administrator prompt on Windows): its folder belongs to the service.
5. Use the link
In BridgeStick, set a source's or a destination's Network to the link. Its hosts may be private (10.0.0.5, sap.corp.local), and its files are on the agent's machine. A connection with a private end runs in the link's agents: the rows never cross BridgeStick.
Commands
| Command | What it does |
|---|---|
bridgestick up --auth-key bslk_… [--server URL] [--hostname NAME] [--force] | Join the link (once) and keep it up. --server names BridgeStick's address, --hostname the name the agent shows, --force leaves the current link first. |
bridgestick down | Take the link down. The daemon stays; bridgestick up brings the link back. |
bridgestick status [--json] | What the agent is doing: its link, state, server, allow list and version — and whether a newer release is out. --json for scripts. |
bridgestick allow list | add RULE | remove RULE | List, add or remove allow-list rules. Nothing is allowed by default. |
bridgestick logout | Leave the link: forget the agent's key and its join. |
bridgestick daemon | Run the daemon (bridgestickd) in the foreground, to watch it work. |
bridgestick install-service [--user NAME] | Run the daemon at boot: systemd, launchd or a Windows scheduled task. --user sets the Linux account (default bridgestick). |
bridgestick uninstall-service | Stop running the daemon at boot. |
bridgestick update [--check] [--version X.Y.Z] | Install the latest release (or --version that one) the way the agent was installed — apt, or the installer, checked against the release's signature — keeping its link and allow list. --check only says whether one is out. With sudo (an administrator prompt on Windows) when it is installed for the machine. |
bridgestick version | -v | --version | The agent's version. |
bridgestick --home FOLDER … | Use another folder for the agent's state (any command). |
Files and service
The agent keeps its configuration, its key (readable by its owner only) and its status in one folder. BRIDGESTICK_AGENT_HOME overrides it.
| System | Folder |
|---|---|
| Linux, as root (the service) | /var/lib/bridgestick |
| Linux, as a user | ~/.local/state/bridgestick |
| macOS, as root (the service) | /Library/Application Support/BridgeStick |
| macOS, as a user | ~/Library/Application Support/BridgeStick |
| Windows | C:\ProgramData\BridgeStick |
- Linux: a systemd unit,
bridgestickd.service, run as the unprivileged userbridgestick, restarted always and hardened (no new privileges, a read-only system, its folder writable). Logs:journalctl -u bridgestickd. - macOS: a launch daemon,
com.bridgestick.agent, kept alive. Logs:/Library/Logs/bridgestickd.log. - Windows: a scheduled task,
BridgeStick Agent, run at start-up as SYSTEM.
High availability
- Install the agent on two or more machines of the network and join each to the same link (a reusable key, or one key each).
- The agent connected longest is the primary. When it disconnects or misses three heartbeats (15 seconds apart), the next one takes over and new calls go there.
- A call in flight on a lost agent fails as a transient error: a read is tried again, and a sync continues from its last checkpoint on its next run.
- Agents reconnect by themselves, waiting 1 second and doubling up to 60, with jitter, so agents cut off together do not come back together.
- Give every agent the same allow list: whichever is primary must reach every end.
Revoke or remove
- Revoke an agent on the link's page: its session closes at once, and it stays out.
- Revoke an auth key to stop new agents joining with it; agents that already joined stay.
- On the machine,
bridgestick logoutforgets the agent's key and its join, andbridgestick uninstall-servicestops the daemon. - Ephemeral agents are removed when they go offline.
Troubleshooting
| You see | What to do |
|---|---|
… cannot be reached: … | Allow outbound HTTPS (443) from the machine to api.bridgestick.com. Behind a proxy, set HTTPS_PROXY for the command and for the service. |
… refused to join: … | The auth key is spent, expired or revoked: create a new one on the link's page. |
This agent is on the link … already | Run bridgestick logout first, or bridgestick up --auth-key bslk_… --force. |
State: waiting for approval | Approve the agent on the link's page, or join with a pre-approved key. |
State: refused | BridgeStick revoked or removed this agent: join again with a new key and --force. |
State: reconnecting | The channel dropped and the agent is retrying by itself; the Error line says why. Check the network or the proxy if it lasts. |
State: not running | The daemon is not running: sudo bridgestick install-service, or bridgestick daemon to run it in the foreground. |
… is not in this agent's allow list | Add a rule for that host and port — bridgestick allow add host:port — on every agent of the link. |
… is not under a folder of this agent's allow list | Add the folder: bridgestick allow add path:/folder. |
… the host name does not resolve | Fix name resolution on the agent's machine, or name the host by its address. |
… (run it as the agent's user, or with sudo) | The agent's folder belongs to the service: run the command with sudo. |
| The link shows offline in BridgeStick | No agent is connected: run bridgestick status on each machine. Runs are refused and scheduled turns missed until one connects; they do not count as failures of its sources. |
| Anything else | Write to team@davait.com with what bridgestick status prints and the agent's last log lines. |