189 lines
9.3 KiB
Markdown
189 lines
9.3 KiB
Markdown
# Installing Pebrel
|
|
|
|
Pebrel 1.6 uses the `pebrel` command, `pebrel.exe`, and Pebrel package names.
|
|
Older releases keep their original filenames. Use the new installer to migrate
|
|
an existing Nebula installation; configuration migration is handled by the
|
|
application at startup.
|
|
|
|
## Linux Preview
|
|
|
|
The 1.6.0 release provides three Linux x64 Preview packages.
|
|
|
|
- Debian/Ubuntu: install
|
|
`Pebrel-v<version>-linux-x64-preview.deb` with
|
|
`sudo apt install ./Pebrel-v<version>-linux-x64-preview.deb`.
|
|
Remove it with `sudo apt remove pebrel`.
|
|
- AppImage: make
|
|
`Pebrel-v<version>-linux-x64-preview.AppImage` executable and
|
|
run it directly. It does not register itself with the system package manager.
|
|
- Portable archive: extract the `tar.gz` and run its `AppRun` launcher. Keep
|
|
the AppDir layout intact so bundled libraries are found correctly.
|
|
|
|
The Linux target is x86_64 with glibc 2.35 or newer. The
|
|
release workflow builds on Ubuntu 22.04 and runs the same
|
|
Runtime API conformance suite against the final AppImage under X11 and
|
|
Wayland, and against the installed Debian package under X11.
|
|
|
|
SSH password login works without a keyring. Saving SSH passwords or encrypted-key
|
|
passphrases requires `libsecret-tools` and an unlocked Secret Service keyring
|
|
(for example GNOME Keyring or a compatible KWallet setup). The Debian package
|
|
recommends these dependencies. If storage is unavailable, enter the secret for
|
|
the current connection instead; Pebrel does not silently claim to save it.
|
|
|
|
## macOS Preview
|
|
|
|
Download the DMG matching the Mac architecture:
|
|
|
|
- `Pebrel-v<version>-macos-arm64-preview.dmg` for Apple Silicon Macs.
|
|
- `Pebrel-v<version>-macos-x64-preview.dmg` for Intel Macs.
|
|
|
|
Open the DMG and drag **Pebrel** into Applications. The 1.6.0
|
|
packages use ad-hoc signing, without Apple notarization. For a
|
|
download you have verified and trust, macOS may require **System Settings →
|
|
Privacy & Security → Open Anyway** after an initial launch is blocked. Do not
|
|
disable Gatekeeper globally. Developer ID/notarized builds are explicitly
|
|
identified in their release notes; that mode requires the maintainer's Apple
|
|
credentials and fails rather than falling back to ad-hoc signing.
|
|
|
|
The workflow builds both architectures on native macOS 15 runners. It checks
|
|
the final mounted DMG and launches a private installed copy through
|
|
LaunchServices with a minimal PATH and unset locale. The package deployment
|
|
target is macOS 14, but macOS 14 itself still needs separate runtime validation;
|
|
a deployment target is not a tested-OS guarantee.
|
|
|
|
SSH secrets are stored in macOS Keychain only when requested. A GUI launch uses
|
|
a UTF-8 locale and starts from the home directory when launched from `/`, while
|
|
an explicit working directory is preserved. Both platforms use the embedded
|
|
Maple Mono terminal font without requiring a system font installation.
|
|
|
|
Linux/macOS do not yet provide full Windows feature parity: tray/close-to-background residency,
|
|
global quick-terminal hotkeys, automatic update installation, and automatic
|
|
local AI-hook configuration are not enabled on Linux/macOS. Native IME, display
|
|
scaling, notification permissions, and interactive SSH/SFTP still need native
|
|
user testing. The release procedure and acceptance checklist are in
|
|
[`docs/preview-release-checklist.md`](docs/preview-release-checklist.md).
|
|
|
|
Earlier CI Preview archives may contain `-preview.<id>` and use `x86_64` /
|
|
`aarch64` filenames; those older builds use the Debian package name
|
|
`pebrel-preview` and the macOS bundle name **Pebrel Preview**. The 1.6.0 platform
|
|
Preview packages use `pebrel` and **Pebrel**, as described above.
|
|
|
|
## Windows installer (recommended)
|
|
|
|
1. Download `Pebrel-v<version>-windows-x64-setup.exe` from the
|
|
[Releases](https://github.com/Kuddev/pebrel/releases/latest) page.
|
|
2. Follow the wizard to choose the installation directory and optional desktop
|
|
or Windows sign-in shortcuts. The default per-user installation does not
|
|
require administrator rights.
|
|
3. The installer offers system installation of the bundled Maple Mono font and
|
|
can launch Pebrel on the final page. The application also embeds the font.
|
|
|
|
### Upgrade an existing Nebula installation
|
|
|
|
The installer keeps the existing application identity so Windows treats Pebrel
|
|
as an upgrade. A registered installation ending in `Nebula Terminal` moves to
|
|
the sibling `Pebrel` directory. For the old default installation, this changes
|
|
`%LOCALAPPDATA%\Programs\Nebula Terminal` to
|
|
`%LOCALAPPDATA%\Programs\Pebrel`. Other custom directory names are preserved,
|
|
and an explicitly chosen installer directory takes precedence.
|
|
|
|
Close the old application normally before installing. The installer updates its
|
|
managed shortcuts and PATH entry, installs `pebrel.exe` and
|
|
`runtime/pebrel-hook.exe`, and removes recognized old program files. Unknown
|
|
files and user configuration remain in place. If cleanup fails after the new
|
|
program is installed, the installer reports the failure and retains retry state.
|
|
|
|
On startup, Pebrel copies old application data into `%APPDATA%\Pebrel` without
|
|
overwriting newer files. The old data directory remains available for recovery
|
|
and existing absolute configuration imports. See
|
|
[Lua configuration and migration](docs/lua-configuration.md#existing-nebula-data)
|
|
for discovery order and the `PEBREL_*` environment variables.
|
|
|
|
Uninstalling closes Pebrel, runs `pebrel setup-ai --remove` before deleting the
|
|
program files, and removes Pebrel's Claude, Codex, opencode, and Pi integration.
|
|
Other user-owned hook and notifier entries are preserved.
|
|
|
|
## Portable archive
|
|
|
|
1. Download `Pebrel-v<version>-windows-x64.zip` from the Releases page.
|
|
2. Unzip it anywhere.
|
|
3. Run `pebrel.exe`. The portable application includes its terminal font, so
|
|
no separate font installation is required. The installer offers optional
|
|
system font installation for use in other applications.
|
|
|
|
Keep the extracted directory structure intact:
|
|
|
|
| Path | Purpose |
|
|
| --- | --- |
|
|
| `pebrel.exe` | the terminal |
|
|
| `README.md` | overview and usage |
|
|
| `runtime/pebrel-hook.exe` | AI turn-notification bridge (Claude Code / Codex) |
|
|
| `runtime/conpty.dll` + `runtime/OpenConsole.exe` | modern ConPTY host (correct resize, fast tab spawn) |
|
|
| `docs/CHANGELOG.md` + `docs/INSTALL.md` + `docs/lua-configuration.md` | release changes, installation, and Lua configuration |
|
|
| `skills/pebrel-runtime/` | instructions for controlling Pebrel through its Runtime API |
|
|
| `licenses/` | Pebrel and third-party license notices |
|
|
|
|
## Build from source
|
|
|
|
Install [rustup](https://rustup.rs) and the build dependencies for your platform.
|
|
The repository pins Rust 1.97.1 in `rust-toolchain.toml`. Linux dependency packages
|
|
are listed in `.github/workflows/release.yml`; macOS requires Xcode command-line
|
|
tools with macOS SDK 26 or newer (`xcrun --sdk macosx --show-sdk-version`) for
|
|
the native Liquid Glass window controls. This build requirement does not raise
|
|
the macOS 14 minimum runtime version. Windows requires Windows 10 1809+ / 11
|
|
and a supported Rust linker toolchain.
|
|
|
|
The matching server compatibility target is **Windows Server 2019 Desktop
|
|
Experience (build 17763)**. The desktop renderer requires Direct3D feature level
|
|
10.1 or later. Server Core and releases before Server 2019 are outside this target.
|
|
The installer retains the 17763 minimum; newer window effects are optional and
|
|
the console transport can fall back to the older ConPTY input mode. Hosted CI
|
|
runs on newer Windows versions, so it does not replace runtime acceptance on a
|
|
Server 2019 desktop or the intended Remote Desktop/graphics configuration.
|
|
|
|
```powershell
|
|
git clone https://github.com/Kuddev/pebrel
|
|
cd pebrel
|
|
cargo build --release --locked -p nebula --bin pebrel --features gpui-shell
|
|
```
|
|
|
|
Build and assemble the portable archive with:
|
|
|
|
```powershell
|
|
powershell -ExecutionPolicy Bypass -File scripts/package-release.ps1 `
|
|
-Version unreleased -Force
|
|
```
|
|
|
|
The script builds the release workspace, verifies every required input, stages
|
|
the directory layout above, creates the ZIP, and prints its file count, packed
|
|
and unpacked sizes, and SHA-256. Final releases must use a fresh build;
|
|
`-SkipBuild` and `-AllowStale` are reserved for packaging-script tests.
|
|
|
|
Build the wizard-based installer with Inno Setup 6.7.3:
|
|
|
|
```powershell
|
|
powershell -ExecutionPolicy Bypass -File scripts/build-installer.ps1 -Force
|
|
```
|
|
|
|
The installer build validates the same runtime inputs, pins and verifies the
|
|
UTF-8 Simplified Chinese wizard translation, and prints the setup executable's
|
|
size and SHA-256. Pass `-InnoCompiler` when `ISCC.exe` is installed in a custom
|
|
directory.
|
|
|
|
## First run
|
|
|
|
- Toast notifications register under the `Pebrel` app identity automatically.
|
|
- Claude Code / Codex turn notifications are wired on first boot
|
|
(`pebrel setup-ai --remove` to undo; `pebrel notify-test` to verify the
|
|
toast pipeline).
|
|
- New configuration uses `%APPDATA%\Pebrel\pebrel.lua`. Run
|
|
`pebrel config init --language system` to create an annotated template and
|
|
`pebrel config check` to validate it. Legacy Nebula configuration is supported
|
|
when no Pebrel configuration is present; see the discovery order in the
|
|
[Lua guide](docs/lua-configuration.md#discovery-order).
|
|
- Linux uses `$XDG_CONFIG_HOME/pebrel/pebrel.lua` (normally
|
|
`~/.config/pebrel/pebrel.lua`); macOS uses
|
|
`~/Library/Application Support/Pebrel/pebrel.lua`. Native package and runtime
|
|
acceptance requirements are described in the Preview sections above.
|
|
- Visual settings remain available in the in-app settings panel.
|