Rust backend (truedeck-backend)

Part of TrueDeck 0.3.x docs. See the documentation home and Architecture. PTY-only experiment: FAST-PTY.md.

TrueDeck’s native backend runs as a sidecar process. Electron keeps the window + React UI; the Rust service owns PTY, projects, settings, layout, and memory inject.

Step	Component
1	Renderer (React + xterm)
2	IPC via preload
3	Electron main (thin bridge)
4	stdio JSON-RPC
5	truedeck-backend (primary)

Build

1. Free disk space (toolchain needs several GB).
2. Install rustup + MSVC Build Tools (Windows).
3. From repo root:

npm run build:backend
# → resources/bin/truedeck-backend.exe
npm start

Log line when active:

[backend] rust truedeck-backend 0.1.0

If the binary is missing, TrueDeck falls back to TypeScript + node-pty.

Override path

$env:TRUEDECK_BACKEND_BIN = "C:\path\to\truedeck-backend.exe"
$env:TRUEDECK_DATA_DIR = "C:\path\to\TrueDeck\data" # default = app userData/data

Protocol

Newline-delimited JSON:

{"id":1,"method":"sessions.spawn","params":{"projectRoot":"C:/repo","agentId":"shell"}}
{"id":1,"ok":true,"result":{"id":"...","agentName":"Shell",...}}
{"event":"pty.data","params":{"id":"...","data_b64":"..."}}
{"event":"pty.exit","params":{"id":"...","exitCode":0}}

Methods: sessions.*, projects.*, agents.*, settings.*, layout.*, memory.*, onboarding.*, ping, shutdown, backend.info.

Crate layout

crates/truedeck-backend/
 src/
 main.rs # RPC loop
 sessions.rs # portable-pty
 projects.rs
 agents.rs
 settings.rs
 memory/
 resolve.rs
 protocol.rs

Use truedeck-backend only. The old truedeck-pty sidecar is no longer used at runtime.