Quick Start & Installation
Relevant source files
The following files were used as context for generating this wiki page:
Termul Manager is a modern, project-aware terminal manager built with Tauri, React, and Rust. It organizes terminals into project-specific workspaces with persistent sessions and snapshots.
This guide details the steps to install pre-built binaries, set up a local development environment, and configure the standalone headless server. For architectural details, refer to the Architecture Overview or Agent Policies.
Installation Methods
Desktop Application
You can install the Termul Manager desktop application using platform-specific package managers or manual downloads.
| Platform | Method | Command / Action |
|---|---|---|
| macOS | Homebrew | brew tap gnoviawan/termul brew install --cask termul |
| macOS/Linux | curl | curl -fsSL https://raw.githubusercontent.com/gnoviawan/termul/main/scripts/install.sh | bash |
| Windows | Manual | Download .exe or .msi from GitHub Releases |
| Arch Linux | AUR | Install via AUR (package termul) |
Sources: README.md:162-178, CHANGELOG.md:126
Standalone Server (termul-server)
The standalone headless server supports remote access and browser-based clients. It includes a guided setup wizard for deployment.
# Guided interactive setup and background launch
termul-server onboard
# One-shot self-update check
termul-server --check-update
Sources: src-tauri/src/server_main.rs:36-45, src-tauri/src/server_main.rs:604-610
Development Setup
To build Termul from source, you must install the required runtimes and toolchains.
Prerequisites
| Dependency | Version | Purpose |
|---|---|---|
| Bun | 1.3+ | JavaScript runtime and package manager |
| Rust | Latest stable | Required for Tauri backend and compilation |
| Git | - | Version control |
Sources: README.md:182-190, CONTRIBUTING.md:144-147
Platform-Specific Requirements
Before running the development server, install these OS dependencies:
- Windows: Microsoft Visual C++ Build Tools and WebView2 Runtime.
- macOS:
xcode-select --install. - Linux (Ubuntu):
libwebkit2gtk-4.1-dev,build-essential,libxdo-dev,libssl-dev,libayatana-appindicator3-dev,librsvg2-dev,patchelf.
Sources: README.md:192-218
Getting Started Steps
- Clone the Repository:
git clone https://github.com/gnoviawan/termul.git cd termul - Install Dependencies:
bun install - Launch Development Mode:
This starts the Tauri development window with hot-reloading for the React renderer.bun run dev
Sources: README.md:225-236, CONTRIBUTING.md:154-165
Project Architecture & Data Flow
Termul uses a multi-layered architecture where the React renderer communicates with a Rust backend via Tauri IPC or WebSocket (for the standalone server).
The following diagram illustrates the lifecycle from launching the application to project creation:
The diagram shows the initialization flow from the CLI to the active workspace components.
Sources: README.md:288-305, src/renderer/lib/project-templates.ts:251-285
Configuration & Commands
Build Commands
Termul provides specific scripts in package.json for building production artifacts.
| Target | Command |
|---|---|
| Current Platform | bun run build |
| Windows (x64) | bun run build:tauri:win |
| macOS (Apple Silicon) | bun run build:tauri:mac-arm |
| macOS (Intel) | bun run build:tauri:mac-x64 |
| Linux (x64) | bun run build:tauri:linux |
Sources: package.json:80-84, README.md:255-266
Server Environment Variables
The standalone server behavior is modified through environment variables.
| Variable | Description | Default |
|---|---|---|
TERMUL_PROJECT_ROOT | Boundary for Git/Search routes | $HOME |
TERMUL_WEB_AUTH_TOKEN | Bearer token for API/WS access | Generated if public |
TERMUL_SERVER_UPDATE_ENABLED | Enables periodic self-update loop | false |
TERMUL_SESSIONS_DIR | Path to durable sessions root | Platform state dir |
Sources: src-tauri/src/server_main.rs:612-638
Scaffolding a New Project
Termul supports rapid project initialization through built-in templates. When you create a new project, the scaffoldProject function automates directory creation and file generation.
Available Templates
- Empty Project: Basic directory structure.
- Node.js Project: Includes
package.jsonand a basic HTTP server insrc/index.js. - Rust Project: standard
Cargo.tomlandsrc/main.rs. - React App (Vite): Full Vite + TypeScript scaffold.
- Python Project: Includes
main.pyandrequirements.txt.
Sources: src/renderer/lib/project-templates.ts:5-242
Summary
Termul Manager provides flexible installation options ranging from Homebrew casks for end-users to a comprehensive Bun-based development environment for contributors. By adhering to the project-aware workspace model, the system ensures that terminal sessions, editors, and browser tabs remain persistent across restarts, whether running as a desktop app or a headless server.
Sources: README.md:24-30, AGENTS.md:12-18