External Binaries (Sidecars)

Not every piece of functionality fits neatly inside a Rust command or a JavaScript module. You might need to ship a small CLI tool, a compiled Python script, or a lightweight server binary alongside your application. Tauri calls these bundled executables sidecars, and they run as separate processes managed by your app.

The term comes from motorcycle sidecars — the binary sits alongside your main application, attached but independent. Sidecars let you include tools written in any language without forcing users to install them separately. Common use cases include bundling FFmpeg for media processing, shipping a Python backend as a standalone executable, or embedding a small database engine.

This guide covers the full lifecycle: understanding what sidecars are, adding them to your configuration, handling cross-platform naming, running them from Rust and JavaScript, passing arguments, and following best practices to avoid common pitfalls.

What a Sidecar Actually Is

A sidecar is an external executable file bundled inside your Tauri application package. When your app launches, the binary sits in the installation directory. Your code can spawn it as a child process, communicate with it via standard input/output, and terminate it when needed.

The binary is not linked into your Rust code. It runs as a completely separate operating system process with its own memory space. This means it can be written in any language — Python compiled with PyInstaller, a Go CLI, a C++ tool, or even another Rust binary that you want to keep separate from the main Tauri core.

From the operating system's perspective, the sidecar is just another program that happens to live inside your application's bundle. On macOS, it ends up inside the .app/Contents/MacOS/ directory. On Windows, it's in the same folder as the .exe. On Linux, it sits next to the main binary.

Adding an External Binary to Your Project

The setup has three sequential parts: preparing the binary file, telling Tauri about it in the configuration, and granting the shell plugin permission to execute it. Each step depends on the previous one completing correctly.

rustc --print host-tuple

import { execSync } from 'child_process';
import fs from 'fs';
const extension = process.platform === 'win32' ? '.exe' : '';
const targetTriple = execSync('rustc --print host-tuple').toString().trim();
if (!targetTriple) {
  console.error('Failed to determine platform target triple');
  process.exit(1);
}
fs.renameSync(
  `src-tauri/binaries/my-tool${extension}`,
  `src-tauri/binaries/my-tool-${targetTriple}${extension}`
);

{
  "bundle": {
    "externalBin": [
      "binaries/my-tool"
    ]
  }
}

{
  "permissions": [
    "core:default",
    {
      "identifier": "shell:allow-execute",
      "allow": [
        {
          "name": "binaries/my-tool",
          "sidecar": true
        }
      ]
    }
  ]
}

Adding the Shell Plugin Dependency

The sidecar functionality lives inside the tauri-plugin-shell plugin. If you have not added it yet, install it in both the Rust backend and the frontend:

Rust (src-tauri/Cargo.toml):

[dependencies]
tauri-plugin-shell = "2"

JavaScript/React (terminal):

npm install @tauri-apps/plugin-shell

Then register the plugin in your main.rs or lib.rs:

use tauri_plugin_shell::ShellExt;
#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .plugin(tauri_plugin_shell::init())
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

Running a Sidecar from Your Code

Once the binary is bundled and permissions are set, you can spawn it. The approach differs between Rust and JavaScript, but both use the same underlying mechanism.

use tauri_plugin_shell::ShellExt;
use tauri_plugin_shell::process::CommandEvent;
use tauri::Emitter;
#[tauri::command]
async fn run_my_sidecar(app: tauri::AppHandle) -> Result<(), String> {
    let sidecar_command = app
        .shell()
        .sidecar("my-tool")
        .map_err(|e| format!("Failed to create sidecar command: {}", e))?;
    let (mut rx, mut child) = sidecar_command
        .spawn()
        .map_err(|e| format!("Failed to spawn sidecar: {}", e))?;
    // Read output from the sidecar and emit it to the frontend
    tauri::async_runtime::spawn(async move {
        while let Some(event) = rx.recv().await {
            match event {
                CommandEvent::Stdout(line_bytes) => {
                    let line = String::from_utf8_lossy(&line_bytes);
                    app.emit("sidecar-output", line.to_string())
                        .expect("failed to emit event");
                }
                CommandEvent::Stderr(line_bytes) => {
                    let line = String::from_utf8_lossy(&line_bytes);
                    app.emit("sidecar-error", line.to_string())
                        .expect("failed to emit event");
                }
                CommandEvent::Terminated(payload) => {
                    app.emit("sidecar-terminated", payload.code)
                        .expect("failed to emit event");
                }
                _ => {}
            }
        }
    });
    // Optionally write data to the sidecar's stdin
    child
        .write("input data\n".as_bytes())
        .map_err(|e| format!("Failed to write to stdin: {}", e))?;
    Ok(())
}

Passing Arguments to a Sidecar

Most real-world tools need arguments — a file path to process, a port to listen on, a verbosity flag. Tauri requires you to declare allowed arguments in the capability file before passing them, preventing unexpected argument injection.

Arguments come in two forms: static arguments (fixed strings like --verbose or serve) and dynamic arguments (variable values like file paths, which you validate with a regex). You must list them in the exact order the sidecar expects.

First, define the allowed arguments in your capability file:

{
  "permissions": [
    "core:default",
    {
      "identifier": "shell:allow-execute",
      "allow": [
        {
          "name": "binaries/my-tool",
          "sidecar": true,
          "args": [
            "process",
            "--output",
            {
              "validator": "\\S+"
            }
          ]
        }
      ]
    }
  ]
}

This configuration allows exactly three arguments in order: the static string process, the static flag --output, and a dynamic argument that matches the regex \S+ (any non-whitespace string). The sidecar will be called as my-tool process --output <value>.

Then, pass the arguments when creating the command. They must match the declared list exactly.

In Rust:

let sidecar_command = app
    .shell()
    .sidecar("my-tool")
    .unwrap()
    .args(["process", "--output", "/path/to/output"]);
let (mut rx, mut child) = sidecar_command.spawn().unwrap();

In JavaScript:

const command = Command.sidecar('binaries/my-tool', [
  'process',
  '--output',
  '/path/to/output',
]);
const result = await command.execute();

If the argument list does not exactly match what is declared in the capability file — in count, order, or content — the shell plugin will reject the command with a permission error.

A Practical End-to-End Example

Suppose you have a small Python script that generates QR codes, compiled into a standalone binary called qr-gen. The practical examples page walks through more complete sidecar setups. You want to bundle it, call it from your React frontend, and display the result.

The binary is placed in src-tauri/binaries/qr-gen-x86_64-unknown-linux-gnu (and equivalents for other platforms). The configuration:

{
  "bundle": {
    "externalBin": ["binaries/qr-gen"]
  }
}

The capability file allows one dynamic argument — the text to encode:

{
  "permissions": [
    "core:default",
    {
      "identifier": "shell:allow-execute",
      "allow": [
        {
          "name": "binaries/qr-gen",
          "sidecar": true,
          "args": [
            {
              "validator": ".+"
            }
          ]
        }
      ]
    }
  ]
}

The Rust backend exposes a Tauri command that spawns the sidecar and returns the output:

use tauri_plugin_shell::ShellExt;
use tauri_plugin_shell::process::CommandEvent;
#[tauri::command]
async fn generate_qr(app: tauri::AppHandle, text: String) -> Result<String, String> {
    let sidecar_command = app
        .shell()
        .sidecar("qr-gen")
        .map_err(|e| e.to_string())?
        .args([&text]);
    let (mut rx, _child) = sidecar_command
        .spawn()
        .map_err(|e| e.to_string())?;
    let mut output = String::new();
    while let Some(event) = rx.recv().await {
        if let CommandEvent::Stdout(bytes) = event {
            output.push_str(&String::from_utf8_lossy(&bytes));
        }
    }
    Ok(output)
}

The React component calls the command:

import { useState } from 'react';
import { invoke } from '@tauri-apps/api/core';
function App() {
  const [text, setText] = useState('');
  const [qrData, setQrData] = useState('');
  async function handleGenerate() {
    try {
      const result = await invoke<string>('generate_qr', { text });
      setQrData(result);
    } catch (error) {
      console.error('QR generation failed:', error);
    }
  }
  return (
    <div>
      <input
        type="text"
        value={text}
        onChange={(e) => setText(e.target.value)}
        placeholder="Enter text for QR code"
      />
      <button onClick={handleGenerate}>Generate QR</button>
      {qrData && <img src={`data:image/png;base64,${qrData}`} />}
    </div>
  );
}
export default App;

This pattern works for any binary that takes input and returns output. The Rust layer acts as a thin bridge between the frontend and the sidecar, handling process lifecycle and argument validation.

Best Practices for Sidecars

The flexibility of external binaries comes with responsibility. A badly managed sidecar can leave zombie processes, leak resources, or create security holes. Follow these sidecar best practices as a checklist.

Always clean up child processes

A sidecar that continues running after the main application closes is a resource leak. Store the child process handle and call kill() when the app is shutting down. In Rust, you can use the Drop implementation of a wrapper struct. In JavaScript, listen for the window's beforeunload event or use a cleanup function in React's useEffect.

struct SidecarGuard(tauri_plugin_shell::process::CommandChild);
impl Drop for SidecarGuard {
    fn drop(&mut self) {
        let _ = self.0.kill();
    }
}

Handle errors at every stage

The sidecar binary might be missing, fail to start, return a non-zero exit code, or produce malformed output. Never assume the happy path. Check exit codes, log stderr, and surface meaningful error messages to the user instead of silently failing.

Restrict arguments tightly

Declare only the arguments your binary actually needs. Avoid broad validators like .* unless absolutely necessary. Each static argument should be a literal string, and each dynamic argument should have a regex that rejects unexpected input. This prevents a compromised frontend (via XSS, for example) from passing arbitrary commands to your sidecar.

Test on every target platform

A sidecar compiled for Linux will not run on Windows. You need a separate build for each target triple your application supports. Test the binary on each platform early. A common mistake is developing only on one OS and discovering at release time that the sidecar crashes on another.

Keep binary size in mind

Sidecars are included in the final installer, so their size adds directly to the download. A 200 MB binary bloats the app. Consider compressing with UPX or choosing a language that produces small binaries (Go, Rust) for sidecars that will be bundled.

Use the shell plugin's built-in spawning

Avoid using std::process::Command directly to run bundled binaries. Tauri's shell plugin handles target triple resolution, permission checks, and platform-specific quirks. Using raw OS process spawning bypasses these safeguards and makes cross-platform support harder.

Watch for macOS code signing issues

On macOS, sidecars bundled inside the .app must be code-signed. If you encounter "cannot be opened because the developer cannot be verified" errors, ensure your sidecar is signed along with the rest of the bundle. For universal macOS builds (targeting both Intel and Apple Silicon), you may need to combine architecture-specific sidecars into a single universal binary using lipo. Tauri's bundler expects a single binary with the target triple, so for universal-apple-darwin, you must create that combined binary yourself before bundling.

lipo -create my-tool-x86_64-apple-darwin my-tool-aarch64-apple-darwin -output my-tool-universal-apple-darwin

Summary

Sidecars give your Tauri application a practical escape hatch: any tool that can be compiled into a standalone executable can be bundled and controlled from your app. The three-step setup — place the binary with the target triple suffix, declare it in externalBin, and grant shell permissions — is the gate you must pass through once per binary. After that, Rust and JavaScript both offer clean, event-driven APIs for spawning, communicating with, and terminating sidecar processes.

The most common failure point is forgetting the target triple suffix. The second is mismatched paths between the configuration, capability file, and the sidecar() call. If nothing happens when you try to spawn the sidecar, check those three strings first.

With sidecars working, you can now bundle tools written in any language, call them from a React frontend via Tauri commands, and manage their entire lifecycle.