Skill Issue Dev | Dax the Dev
search
Part of series: Vanta In Practice

Tauri 2.x sidecars in anger: the ergonomics paper-cuts I had to fix

14 min read verified human-written
Last updated:
Print view
Sections

The Vanta Desktop walkthrough is the architectural story: a Tauri 2.x wallet that ships its own full node, supervises three sidecar binaries, and exposes everything through #[tauri::command] IPC. That post is the what. This post is the how — the small, awkward, under-documented ergonomics details that took me a working week to figure out.

If you’re shipping a Tauri app with sidecar binaries in 2026 and you’re hitting walls, this post is the field notes I wish someone had written for me. If you’re not, skip it.

The target-triple suffix

The first wall is the one that’s most easily missed because it works fine in production and breaks subtly in dev. Tauri’s externalBin config in tauri.conf.json declares the sidecar binaries:

"externalBin": [
  "binaries/vantad",
  "binaries/vanta-node",
  "binaries/vanta-cli"
]

The bundler does not look for binaries/vantad literally. It looks for binaries/vantad-<rustc-host-target-triple> — that is, the file with the target-triple appended.

On Apple Silicon that’s binaries/vantad-aarch64-apple-darwin. On Intel macOS it’s binaries/vantad-x86_64-apple-darwin. On Linux it’s binaries/vantad-x86_64-unknown-linux-gnu. Windows is binaries/vantad-x86_64-pc-windows-msvc.

If the file is named just binaries/vantad, Tauri’s bundler emits a moderately cryptic error during tauri build. The fix is renaming the file. The discovery process for figuring this out is tauri build → fail → google → find a years-old GitHub issue → realise.

The setup script that handles this lives in setup-sidecars.sh and the load-bearing line is the very first one:

TRIPLE=$(rustc -vV | grep host | awk '{print $2}')

rustc -vV outputs Rust’s verbose version info, which includes a host: <triple> line. Awk picks the second field. The variable then suffixes every file copied into src-tauri/binaries/:

cp "$VANTAD" "$BINDIR/vantad-$TRIPLE"
cp "$ZERANODE" "$BINDIR/vanta-node-$TRIPLE"

That’s the canonical way to discover the host triple, and it’s what every Tauri tutorial buries five paragraphs in. Do not hardcode the triple. A Mac developer who switches between aarch64 and x86_64 (e.g., a Rosetta context for testing) will produce one set of binaries from one shell and another from another, and the bundler will pick whichever is on disk and matches the active build target — only one of which is correct on any given build.

The full search for vantad in setup-sidecars.sh walks well-known locations:

VANTAD="${ZERA_L1_BIN:-}"
if [ -z "$VANTAD" ]; then
  for candidate in \
    "../src/vantad" \
    "../../src/vantad" \
    "/usr/local/bin/vantad" \
    ; do
    if [ -x "$candidate" ]; then
      VANTAD="$candidate"
      break
    fi
  done
fi

The ../src/vantad and ../../src/vantad are relative paths from vanta-desktop/ and vanta-desktop/src-tauri/ respectively. The /usr/local/bin/vantad is the canonical install path on macOS. The ZERA_L1_BIN env var is the escape hatch for non-default layouts. (The variable name still reads ZERA_L1_BIN because of the zeracoin → vanta rebrand — pre-rebrand artefact, on the cleanup list.)

The dev-mode resolver

The bundler problem is solved at build time. There’s a different problem at dev time: when you cargo run the Tauri host directly (or pnpm tauri dev), the executable lives at src-tauri/target/debug/vanta-desktop, not in a .app bundle. The sidecars aren’t sitting next to the host executable; they’re at src-tauri/binaries/vanta*-<triple>.

The host has to discover them at runtime, in both production and dev. The function that does this is resolve_binary in src-tauri/src/node.rs:225:

pub fn resolve_binary(name: &str, config_path: &str) -> PathBuf {
    let triple = target_triple();
    let suffixed = format!("{name}-{triple}");

    if let Ok(exe) = std::env::current_exe() {
        if let Some(dir) = exe.parent() {
            // Production: sidecars are next to the exe with triple suffix
            for candidate in [
                dir.join(&suffixed),
                dir.join(name),
            ] {
                if candidate.exists() && candidate.metadata().map(|m| m.len() > 0).unwrap_or(false) {
                    tracing::info!("Found sidecar: {}", candidate.display());
                    return candidate;
                }
            }

            // Dev mode: the exe is at src-tauri/target/debug/vanta-desktop.
            // Walk up ancestors looking for a `binaries/` dir containing our binary.
            for ancestor in dir.ancestors().skip(1) {
                let candidate = ancestor.join("binaries").join(&suffixed);
                if candidate.exists() && candidate.metadata().map(|m| m.len() > 0).unwrap_or(false) {
                    tracing::info!("Found dev sidecar: {}", candidate.display());
                    return candidate;
                }
            }
        }
    }

    // Check explicit config path
    let config = PathBuf::from(config_path);
    if config.exists() && config.metadata().map(|m| m.len() > 0).unwrap_or(false) {
        return config;
    }

    // Fall back to PATH lookup
    PathBuf::from(name)
}

The five-tier resolution order is:

  1. Same directory as the host exe, with the triple suffix → production bundle.
  2. Same directory as the host exe, without suffix → also production, fallback for some bundlers.
  3. Walk up the parent chain looking for a binaries/ directory → dev mode.
  4. Explicit path from WalletConfig → user override.
  5. Bare name → PATH lookup.

The fallback to PATH is what lets a developer with vantad already installed at /usr/local/bin/vantad skip the setup-sidecars.sh step entirely if they want to. The metadata check for len() > 0 is paranoia — empty files passing existence checks have caused at least one wasted afternoon.

The target_triple() helper picks the right suffix based on cfg!:

pub fn target_triple() -> &'static str {
    if cfg!(target_os = "macos") {
        if cfg!(target_arch = "aarch64") {
            "aarch64-apple-darwin"
        } else {
            "x86_64-apple-darwin"
        }
    } else if cfg!(target_os = "linux") {
        "x86_64-unknown-linux-gnu"
    } else {
        "x86_64-pc-windows-msvc"
    }
}

This is intentionally a hardcoded match. We don’t support other target triples (yet — Linux ARM is an “if a user complains” item). Hardcoding means the build fails loudly if someone tries to compile for an unsupported target, instead of silently producing a binary that can’t find its sidecars.

The signing identity

Tauri 2.x’s macOS bundler signs every binary in the .app with the identity declared in tauri.conf.json:

"macOS": {
    "signingIdentity": "474F624D8F3783B4D607CFF2331AD4C6CC26A1B5",
    "providerShortName": "9HD4Q82U58",
    "entitlements": "entitlements.plist",
    "minimumSystemVersion": "10.15"
}

signingIdentity is the SHA1 fingerprint of an Apple Developer ID Application certificate. You can list yours with security find-identity -v -p codesigning. The format 474F62... is a hex fingerprint, not a CN string — Tauri specifically looks up by fingerprint to disambiguate when you have multiple Developer ID certs in keychain. This took me a few false starts to land on; the first version of this config used the human-readable CN (“Developer ID Application: Hayden Porter-Aylor (9HD4Q82U58)”) and broke when I had two certs from different teams.

providerShortName is the Apple Team ID, the same string that goes in the cert’s CN. It’s needed for notarisation — xcrun notarytool submit requires --team-id to match this value.

entitlements points at a separate plist file. Tauri’s default entitlements are too permissive for a wallet; ours pins network access (we need it for the L2 P2P), allows JIT (because the WebView needs it), and otherwise denies everything — including microphone, camera, location, and the raft of other Apple-managed entitlements that a finance app should not be requesting.

Sequenced startup, not parallel

The first version of the wallet started both nodes in parallel, hoping the L2 watcher would survive its first few RPC failures while the L1 came up. It didn’t. The L2 would crash on its first poll, the supervisor would log “L2 stopped,” the user would see “L2 disconnected,” and the eventual successful start (after vantad’s 30-second startup) would race the user’s first attempt to send a transaction.

The fix is in src-tauri/src/lib.rs and the structure is five sequenced stages:

Stage 1: Start L1 (may adopt)
Stage 2: Wait for L1 RPC up to 60s, exponential backoff
Stage 3: Create / load default wallet via RPC
Stage 4: Start L2 (now that L1 is confirmed reachable)
Stage 5: emit "ready" event to frontend

Each stage emits a Tauri event (startup-stage) the frontend subscribes to. The user-facing UX is a five-step progress meter that goes “spawning vantad… RPC ready… wallet loaded… spawning vanta-node… ready.” On a warm cache the whole flow takes about 4 seconds. On a cold first launch with chainstate to load, it’s closer to 12.

The stage-by-stage approach makes failures actionable. If stage 2 times out (L1 RPC didn’t come up), the error message points at L1; if stage 4 fails, it points at L2. The pre-stage version of this had a single start_nodes() command whose only failure mode was a generic “couldn’t start nodes,” which was useless for support.

The NodeManager struct

The supervisor is a single struct in src-tauri/src/node.rs:178:

pub struct NodeManager {
    l1_process: Option<Child>,
    l2_process: Option<Child>,
    /// When true, we detected a pre-existing L1 that we're reusing.
    l1_adopted: bool,
    /// When true, we detected a pre-existing L2 that we're reusing.
    l2_adopted: bool,
    /// Resolved path to vantad binary.
    l1_bin: Option<PathBuf>,
    /// Resolved path to vanta-node binary.
    l2_bin: Option<PathBuf>,
    /// Recent output from L1 process.
    pub l1_logs: LogBuffer,
    /// Recent output from L2 process.
    pub l2_logs: LogBuffer,
    /// Tauri app handle for emitting events.
    app_handle: Option<tauri::AppHandle>,
}

The fields tell the whole story:

  • Two Option<Child> — the live process handles, when we own them.
  • Two bools — adopted flags. When the desktop starts and finds an existing vantad already listening on 19332, it doesn’t kill it; it adopts it (PID 0 sentinel) and proceeds. The adoption logic exists because every quit-and-relaunch from a previous version of the app would otherwise produce a “port in use” error.
  • Two PathBufs — the resolved binary paths, useful for the diagnostic UI (“the wallet is using vantad at /Applications/Vanta Wallet.app/Contents/MacOS/vantad-aarch64-apple-darwin”).
  • Two LogBuffers — 200-line ring buffers per process, served to the frontend on demand for the live console view.
  • The AppHandle — used to emit Tauri events for log lines (so the frontend can render a rolling log view without polling).

Pipe draining as a load-bearing detail

A Bitcoin-Core C++ process logging to stdout will eventually fill the OS’s 64 KB pipe buffer if nobody reads it, and then block on its next write(). vantad with -printtoconsole is a heavy logger; without an active reader, it deadlocks within minutes.

The drain_pipe function in node.rs:64 is the safety net. Every line goes three places:

  1. tracing::debug! — the structured log file.
  2. LogBuffer::push — the in-memory ring buffer for the frontend.
  3. app.emit("node-log", …) — a Tauri event the frontend subscribes to for live rendering.

That last one is the path I want to underline. The first version of the wallet had no live log surface; debugging a “node won’t start” required tail -f on the log file. The Tauri event channel turned that into a frontend log component that streams stdout in real time, which by itself paid for the IPC complexity ten times over.

Auto-config for the L1

Before vantad starts, the host writes a vanta.conf into {home}/.vanta-desktop/l1/. The config is hardcoded for the desktop’s port plan, points at the seed nodes, and disables Bitcoin-style DNS seeding. Excerpt:

let conf = format!(
    "# Vanta Desktop Wallet — auto-generated config\n\
     server=1\n\
     daemon=0\n\
     txindex=1\n\
     listen=1\n\
     rpcport={DESKTOP_L1_RPC_PORT}\n\
     port={DESKTOP_L1_P2P_PORT}\n\
     rpcuser={}\n\
     rpcpassword={}\n\
     rpcallowip=127.0.0.1\n\
     rpcbind=127.0.0.1\n\
     dnsseed=0\n\
     addnode=64.34.82.145:9333\n\
     addnode=66.241.124.138:9333\n\
     wallet=default\n\
     fallbackfee=0.0001\n",
    config.rpc_user, config.rpc_pass,
);
std::fs::write(&conf_path, &conf)?;

Three things in here that are non-obvious:

txindex=1. The L2 watcher needs to look up arbitrary historic transactions to scan for OP_RETURN anchors. Without txindex, getrawtransaction only works for unspent outputs. With it, every transaction is indexed by txid forever. This costs ~10% extra disk vs a stock node; the L2 work flat-out doesn’t function without it.

dnsseed=0. Bitcoin Core auto-discovers peers from a hardcoded list of DNS seeds. Vanta’s a separate network with separate seeds; if dnsseed=1, vantad will spam seed.bitcoin.sipa.be looking for peers it’ll never find. Disabling it cuts the startup chatter and the wasted DNS queries.

addnode=64.34.82.145:9333. The Latitude bare-metal seed node, hardcoded into the desktop config. Until the chain has organic peer discovery, this is the bootstrap. (More on this in the fly+bare-metal post.)

The user never sees this file unless they go looking. Pinning the config to the desktop’s port plan also means the wallet never collides with a standalone vantad running on default ports — which matters because some users run both.

The Linux/NVIDIA cursed stanza

Two lines in lib.rs earned a comment longer than they are:

#[cfg(target_os = "linux")]
{
    if std::env::var("WEBKIT_DISABLE_DMABUF_RENDERER").is_err() {
        std::env::set_var("WEBKIT_DISABLE_DMABUF_RENDERER", "1");
    }
}

webkit2gtk on NVIDIA’s proprietary driver under Wayland tries to use a DMA-BUF renderer path that crashes with Error 71 (Protocol error) dispatching to Wayland display. Disabling it forces software compositing, which is fine.

This is the canonical example of “Tauri 2.x ergonomics” actually meaning “the OS will surprise you in ways the web never has.” Budget for it. Apps that ship to general users discover bugs that only happen on specific GPU + display server + driver combinations. The fix is usually environmental; the discovery is a weekend.

What I changed my mind about

The big one: Tauri’s sidecar story is the right way to ship a wallet that runs a node. The alternative — telling users to run vantad themselves and pointing the wallet at it — is a non-starter for everybody but engineers like me. The friction of the embedded full-node story turns out to be entirely inside the developer (the build process, the signing pipeline, the auto-update story). The user friction is zero. They double-click a DMG and they’re a node operator.

The smaller one: the build is more code than the app. build-release.sh is 200 lines, setup-sidecars.sh is 60. Combined that’s about as much shell as the rest of src-tauri/ is Rust outside commands.rs. The shell is load-bearing infrastructure, not glue. Treat it that way and the build is reproducible; treat it as glue and the build will surprise you on every fresh checkout.

Further reading

Related

Hire me — book a 30-min call $ book →