BDB OS Remote – Documentation & User Manual

Einführung & Funktionsweise

Overview & Architecture

Stell dir vor, du hast zuhause einen sehr leistungsstarken Computer stehen, auf dem all deine Projekte, Dateien und dein digitaler Assistent ("Claude Desktop") liegen. Wenn du unterwegs bist – zum Beispiel im Zug oder im Café – möchtest du trotzdem so arbeiten können, als würdest du direkt vor diesem Computer sitzen.

Imagine you have a powerful workstation at home hosting your heavy projects, databases, and Claude Desktop with its MCP toolchain. When traveling, BDB OS Remote allows you to access this entire environment from your laptop seamlessly over an encrypted WireGuard mesh.

Plattform / RollePlatform / Role	Installation & BefehlSetup & Command
macOS (Apple Silicon & Intel)	Voraussetzung: Node.js >= 18, macOS 12+ (Monterey oder neuer), Tailscale Requirements: Node.js >= 18, macOS 12+ (Monterey or newer), Tailscale
Linux (x86_64 & ARM64)	Voraussetzung: glibc >= 2.28, systemd / POSIX shell, Tailscale Daemon Requirements: glibc >= 2.28, systemd / POSIX shell, Tailscale Daemon
Windows (x64)	Voraussetzung: Windows 10/11 (64-bit), PowerShell / Windows Terminal Requirements: Windows 10/11 (64-bit), PowerShell / Windows Terminal

ℹ️

Zero-Trust Tunnel: Alle Verbindungen laufen Ende-zu-Ende verschlüsselt über dein privates Tailscale-Netzwerk. Es müssen keine Router-Ports geöffnet werden. Zero-Trust Tunnel: All communication is encrypted end-to-end through your private Tailscale tailnet. No open router ports required.

Voraussetzungen

Prerequisites

Pre-Flight Checkliste Pre-Flight Checklist 0/5

Zwei Rechner: Ein leistungsstarker Arbeits-Computer (Host) und ein Laptop (Client). Two Machines: A stationary Workstation (Host) and a mobile Laptop (Client).
Tailscale Konto: Auf beiden Geräten mit demselben Konto angemeldet (tailscale.com). Tailscale Account: Logged into the same account on both machines (tailscale.com).
Claude Desktop: Auf beiden Geräten installiert. Claude Desktop: Installed on both devices.
Node.js: Version >= 18 auf beiden Systemen verfügbar. Node.js: Version >= 18 installed on both machines.
Gleiches Netzwerk: Beide Geräte zeigen in Tailscale einen grünen Verbindungsstatus. Tailnet Active: Both devices show a green active status in Tailscale.

Schritt 1: Arbeits-Computer einrichten

Step 1: Set Up Workstation

Führe diesen Schritt auf dem Computer aus, der zuhause / im Studio stehen bleibt:

Perform this step on the workstation that remains at home / in the office:

Öffne das Terminal und starte den interaktiven Setup-Assistenten: Open the terminal and run the interactive setup installer:

bash

$npx @hybridlabor-api/bdb-os-remote@latest installer
Wähle im Menü die Option [1] Workstation aus. Select option [1] Workstation in the interactive menu.
Der Dienst lauscht nun im Hintergrund auf Port 8000 über dein Tailscale-Netzwerk. The gateway service is now running and listening on port 8000 via your Tailscale mesh.

Schritt 2: Laptop verbinden

Step 2: Connect Laptop

Führe diese Schritte auf deinem mobilen Laptop aus:

Execute these steps on your mobile laptop:

Starte den Installer auf dem Laptop: Run the installer on your laptop:

bash

$npx @hybridlabor-api/bdb-os-remote@latest installer
Wähle Option [2] Laptop und gib den Tailscale-Namen deines Arbeits-PCs ein. Select option [2] Laptop and enter your Workstation's Tailscale host name.
Starte Claude Desktop komplett neu (Cmd+Q & neu öffnen). Restart Claude Desktop completely (Cmd+Q & relaunch).

Verbindungsarten im Vergleich

Connection Modes

ModusMode	EmpfehlungRecommendation	DetailsDetails
1 – Multiplexer (Standard)	Empfohlen / Recommended	Bündelt alle 100+ MCP-Server des Arbeits-PCs über eine einzige schlanke SSE-Verbindung.Multiplexes all 100+ remote MCP tools through a single low-bandwidth SSE stream.
2 – Config Injector	Nur für SpezialfälleAdvanced manual tuning	Trägt jeden entfernten MCP-Server als separaten Eintrag in die lokale Claude-Konfiguration ein.Injects each remote MCP server as an individual entry in the local Claude configuration.

Prompt-Beispiele für Claude Desktop

Claude Desktop Prompt Examples

Sobald verbunden, kannst du Claude Desktop auf dem Laptop ganz normal nutzen:

Once connected, use Claude Desktop on your laptop exactly as if you were local:

Claude Prompt

            „Öffne das Projekt 'frontend-v2' auf meinem Arbeits-Computer und zeig mir die letzten Änderungen.“
            “Open project 'frontend-v2' on my workstation and show me the latest commit diff.”
          

Claude Prompt

            „Durchsuche das memB Gedächtnis auf dem Arbeits-PC nach den Architektur-Regeln für das Event-Tech Modul.“
            “Search the remote memB memory on my workstation for the event-tech architecture decisions.”
          

Offline-Modus (BDB Pull)

Offline Mode (BDB Pull)

Für Situationen ganz ohne Empfang (Flugzeug, Funklöcher) lädst du ein Projekt vorab herunter:

For zero-connectivity situations (flights, tunnels), pull a local snapshot of your project:

bash

$npx @hybridlabor-api/bdb-os-remote pull mein-projekt

Das Projekt wird ohne schwere Ordner (wie node_modules) blitzschnell nach ~/bdb-dev-local/ geklont.

The project is cloned to ~/bdb-dev-local/ with heavy caches automatically excluded.

Software aktuell halten

Software Updates

Führe einfach denselben Installer-Befehl erneut aus und wähle „Update“:

Simply rerun the installer command and choose “Update”:

bash

$npx @hybridlabor-api/bdb-os-remote@latest installer

Fehlerbehebung

Troubleshooting

ProblemIssue Diagnose & LösungResolution

ProblemIssue	Diagnose & LösungResolution
Verbindung schlägt fehl	Prüfe den Tailscale-Status per Terminal-Ping: Test Tailscale mesh connectivity with a ping: `tailscale ping <host-name>`
Werkzeuge in Claude fehlen	Claude Desktop komplett beenden (Cmd+Q) und neu starten. Completely quit Claude Desktop (Cmd+Q) and restart it.
Server manuell starten	Auf dem Arbeits-PC ausführen: Run on the workstation: `npx @hybridlabor-api/bdb-os-remote server`

Verbindung schlägt fehl

Prüfe den Tailscale-Status per Terminal-Ping:

Test Tailscale mesh connectivity with a ping:

tailscale ping <host-name>

Werkzeuge in Claude fehlen

Claude Desktop komplett beenden (Cmd+Q) und neu starten.

Completely quit Claude Desktop (Cmd+Q) and restart it.

Server manuell starten

Auf dem Arbeits-PC ausführen:

Run on the workstation:

npx @hybridlabor-api/bdb-os-remote server

Häufig gestellte Fragen (FAQ)

Frequently Asked Questions (FAQ)

Passwort erforderlich?Password needed?	Nein. Die Authentifizierung erfolgt automatisch über dein Tailscale-Konto.No. Access is secured entirely through your Tailscale network identity.
Datenvolumen unterwegs?Data consumption?	Extrem gering (< 5 KB/s). Dank Heimdall Token Saver werden alle Ausgaben komprimiert.Minimal (< 5 KB/s) due to upstream Heimdall token compression.
Muss der PC anbleiben?Must host stay awake?	Ja, der Arbeits-PC muss eingeschaltet sein (Ruhezustand bei Netzbetrieb deaktivieren).Yes, the workstation must remain on and awake.

Wörterbuch der wichtigsten Begriffe

Glossary

BegriffTerm	BedeutungDescription
Workstation	Dein Haupt-Computer zuhause/im Studio mit allen Projekten und KI-Tools.Your primary compute workstation hosting tools, engines, and projects.
Tailscale	Sicheres Mesh-VPN, das deine Rechner weltweit verschlüsselt verbindet.Secure mesh VPN creating an encrypted WireGuard tunnel between devices.
BDB Pull	Funktion zum lokalen Offline-Klonen von Projekten auf den Laptop.Smart offline project snapshotting engine.
Heimdall	Kontext- und Token-Kompressionsfilter für sparsamen Datenverbrauch.Token compression filter saving up to 85% mobile bandwidth.

Getting Started mit BDB OS Remote

Getting Started with BDB OS Remote