Bun runtime
Ssscript does not rely on a system-wide Bun or Node installation. The desktop app downloads, verifies, and caches a pinned Bun version used for project dev servers, builds, and the local agent runtime.
Why app-managed Bun
Section titled “Why app-managed Bun”- Consistent versions — every user runs the same Bun release the app was tested against.
- Zero setup — create a project and click Run without installing runtimes.
- Isolated from PATH — project scripts use the app-provided binary, not whatever is on your machine.
Where Bun is used
Section titled “Where Bun is used”| Use | Description |
|---|---|
| Dev server | bin/dev.ts serves src/ with live reload on port 6454 |
| Production build | bin/build.ts outputs to dist/ |
| Agent runtime | Bundled @repo/agent-runtime starts under Bun when AI is active |
| Biome format | Save-time formatting via bunx biome from the project root |
Version and cache
Section titled “Version and cache”The pinned version is defined in the Tauri layer (BUN_VERSION, currently 1.3.14). On first use, the app downloads the platform-matching archive from Bun releases, verifies SHA256 when known, and extracts it to the app data cache:
- macOS:
~/Library/Application Support/com.federicovalla.ssscript/bun-cache/ - Windows:
%APPDATA%\com.federicovalla.ssscript\bun-cache\
Subsequent launches reuse the cached binary. Downloads retry with exponential backoff on failure.
Project scripts
Section titled “Project scripts”Starters ship bin/dev.ts and bin/build.ts (copied from packages/starter-template/shared/bin/). In the app:
- Open the terminal panel (⌘J / Ctrl+J).
- Install runs
bun installin the project. - Run starts the dev server.
- Build runs the production build before publish.
You can also run these from an external terminal if you point PATH at the app-managed Bun (advanced — normally unnecessary).
Agent runtime
Section titled “Agent runtime”The AI loop runs a local HTTP server (default http://127.0.0.1:4096) started by the desktop app with the same Bun binary. Override with VITE_AGENT_RUNTIME_BASE_URL when developing the runtime itself.
Runtime config merges:
- Global:
~/.config/ssscript/agent-runtime.json - Project:
.ssscript/agent.json
See Agent runtime integration for plan-mode output, auth sync, parallel slots, and diff streaming.
Troubleshooting
Section titled “Troubleshooting”Dev server won’t start
Section titled “Dev server won’t start”- Run Install first in the terminal panel.
- Check the log for Bun download errors (network, disk space).
- Restart the app to retry Bun delivery.
”Unsupported platform”
Section titled “”Unsupported platform””The app supports macOS (Intel and Apple Silicon), Windows (x64), and Linux (x64/aarch64) for Bun delivery. Other platforms may not receive a managed binary.
Wrong Bun version in external terminal
Section titled “Wrong Bun version in external terminal”External shells do not automatically use the app cache. Use the in-app terminal or Troubleshooting for in-app workflows.