Depend on Another Service

When your service needs another StartOS service (e.g., a Bitcoin node for a wallet, or PostgreSQL from a shared instance), declare it as a dependency. You can require it to be installed, running, or healthy, and declare the versions it accepts.

Solution

In dependencies.ts, create a sdk.Dependency.required() or .optional() with a published versionRange, kind: 'running' or 'exists', and any required healthChecks. Add it to sdk.Dependencies.of() and pass that builder to both buildManifest and setupInit.

These declarations drive the warning UI StartOS shows the user when a dependency isn’t installed, isn’t running, or has a listed health check failing. They do not gate your service’s startup — your service starts whenever the user starts it, regardless of dependency state. If your service genuinely cannot operate before a dependency reaches a particular state, handle that at runtime in setupMain (poll, retry, or surface your own error); don’t expect the dependency declaration to block startup for you.

Read the dependency’s connection info in setupMain by resolving its bridge address with sdk.host.get(...).const() — see Service-to-Service Networking for the one correct way (and the two forbidden ones: .startos DNS names and cross-package container IPs).

Reference: Dependencies · Service-to-Service Networking

Examples

See startos/dependencies.ts in: electrs, fulcrum, jam, lightning-terminal, lnbits, lnd, mempool, open-webui, public-pool, robosats, bitcoin-explorer, helipad, cln, btcpayserver, albyhub, immich, jellyfin, start9-pages, ride-the-lightning