# Enveigh on Linux Enveigh stores credentials in a dedicated pass/GPG vault and provides a terminal UI, a local broker, and scoped MCP connections. It needs no Swift installation at runtime. Download packages and checksums from https://enveigh.com/linux. This release targets Ubuntu 24.04 or newer and current Arch Linux. Omarchy uses the Arch package. Its Omarchy 4.0.4 SDDM/UWSM/Quickshell session stack is tested in an isolated software-rendered guest; hardware performance and unrelated bundled apps are outside that fixture. See the repository’s Linux release evidence for details. ## Install and start Choose the package matching your CPU: `arm64` for ARM64 or `amd64` / `x86_64` for Intel and AMD. Verify the accompanying SHA-256 manifest before installing. A checksum checks integrity; it is not a publisher signature. On Ubuntu, install the downloaded `.deb` with `sudo apt install ./enveigh__.deb`. On Arch, install the `.pkg.tar.zst` with `sudo pacman -U ./enveigh--1-x86_64.pkg.tar.zst`. Install commands require administrator access; run Enveigh itself as your normal user. Then run one command as your normal user: ```sh enveigh ``` On first run Enveigh picks your GPG encryption key (or lets you choose if you have several, or creates a passphrase-protected key if you have none). It then starts the `enveigh` user service, enables it for future logins, and opens pinentry to unlock. GPG handles the passphrase; Enveigh receives proof that your key decrypted its temporary challenge. GPG may reuse its existing cache. This is not a fresh biometric check. Later runs go straight to your vault. Keep a separate backup of your GPG key and its revocation certificate. Enveigh will not replace an existing store's key. Without systemd, Enveigh starts a background `enveigh serve` for you (log: `~/.local/share/enveigh/service.log`). `enveigh tui`, `enveigh setup [fingerprint]` and `enveigh serve` remain available for scripted or manual setups. You can also unlock with `enveigh unlock` from an interactive terminal. For a custom `GNUPGHOME` or `XDG_DATA_HOME`, set the same value in the service's systemd override and in the terminal. Enveigh does not rewrite GPG configuration. ## Use the terminal UI The sidebar follows the Mac app: Secrets, Favorites, Scan, Audit, and environments. Use arrows to select, Tab to move to the sidebar, Enter to open, `/` to search, and `n` to create a secret. Narrow terminals use a compact navigation page. Escape or Control-C goes back. Forms preserve defaults; `-` clears an optional field. The More menu contains backups, vault health, commands, service controls, settings, and clipboard capture. Shortcuts: `t` settings, `c` capture clipboard, `s` service, `l` lock. The TUI can approve a pending agent request while you are filling a form; your draft resumes after the decision. Press `y` to allow; Enter denies access. Unlocking is the permission step. After that, changes you make in the TUI save without further approval prompts. Destructive actions (delete, restore, purge, rotate, lock, stop) ask once for `y`. Requests from agents, the CLI, and other processes still need approval under your approval policy. Settings control approval policy, access notifications, clipboard watching, and the default duration for new task sessions. Changing approval policy clears remembered environment approvals. Explicitly approved task sessions keep their scope and expiry. Appearance follows your terminal theme. ## Long builds and agent runs Connect agents from Agent connections. Review each client's environment scope and raw-reveal setting before connecting it. Existing agents need a coordinated helper upgrade and restart to refresh tool declarations; don't replace them during active work. If an agent reports `no enveigh client token (ENVEIGH_MCP_TOKEN)`, its MCP entry was not created by Enveigh (for example, it was added with `claude mcp add`). Choose Agent connections, then that client. Enveigh replaces the entry with a scoped token and removes project-scoped Claude Code `enveigh` entries that would override it. Restart the agent client afterward. Approve a finite task session before a long task. Each session caches the selected credentials and audit key in service memory. Rebuilds and reconnects can reuse it without reopening GPG. The initial default is 12 hours; settings can select 1–24 hours. MCP can request an explicit duration of 60–86400 seconds. Screen locking and closing the TUI do not end a task session. Expiry continues during sleep, and Enveigh does not keep the computer awake. Expiry, explicit vault lock, revocation, and service stop/restart end future access. Running commands retain credentials they already received; exported files remain on disk. ```sh enveigh session start --env web --hours 12 enveigh session list enveigh run --env web --session SESSION_ID -- npm run build enveigh session end SESSION_ID ``` Agents should use their MCP task-session tools and stop after denial or expiry. Skills guide agent behavior; they cannot isolate secrets from arbitrary software already running as your OS user. ## Clipboard and notifications Wayland needs `wl-clipboard`; X11 needs `xclip`. Clipboard access uses the TUI's current session. SSH and headless terminals can paste into the hidden New secret field. Clipboard watching is off by default. When enabled, it runs only while the unlocked TUI is open. Detection stays local. A matching credential must be reviewed and saved by you. Ordinary clipboard text is not saved. Capturing leaves the clipboard unchanged. Dismissing a candidate keeps it from being offered repeatedly during that run. The secret details screen can copy a value without printing it. Enveigh releases its clipboard ownership after 45 seconds, on vault lock, or on TUI exit. It does not erase another application's newer selection. Clipboard managers may retain their own copies. Access notifications require `notify-send` and a desktop notification service. They contain no credential names or values. Audit remains the record of access even when the desktop has no notification service. ## Lock, backup, and recovery `enveigh lock` or **l Lock** blocks broker access and clears task sessions, remembered approvals, pending approvals, and scan-review values. A controller already editing a form returns to the locked screen. The service keeps running so it can accept a new unlock. Lock does not change the cache of a GPG key shared with other applications. Use Backups to export an encrypted portable backup. Store its passphrase or recovery key separately and test restoring it in an isolated vault. Restore replaces the vault and ends sessions; the UI offers undo for the last restore. Back up before upgrades. Data defaults to `~/.local/share/enveigh`, or `$XDG_DATA_HOME/enveigh`. The password store is dedicated to Enveigh. Do not edit its hashed entries manually. `settings.json` is private configuration, not a credential store. Agent tokens must also stay private. ## Upgrade and uninstall Finish active runs and export a backup. Stop the user service, install the new package, reload systemd, then start the service and unlock it. Package installation does not restart the broker, enable startup, connect agents, or replace agent declarations. Reconnect/update helpers only when their running clients are ready for the change. To uninstall, disconnect agents through Enveigh first, then run `systemctl --user disable --now enveigh` and remove the package using your distro's package manager. Package removal leaves vault data and your GPG key intact. Delete those separately only after verifying your backup and deciding they are no longer needed. ## Troubleshooting - **Vault locked:** choose Unlock. The broker will not open pinentry unexpectedly. - **GPG cannot open the store:** run `enveigh unlock` in the current terminal; check the selected key, passphrase, pinentry installation, and matching `GNUPGHOME`. - **No desktop clipboard:** install the appropriate clipboard tool or use New secret. - **Service unavailable:** use Service & startup, or run `systemctl --user status enveigh`. In a headless session without a user manager, run `enveigh serve` directly. - **Settings unreadable:** preserve the damaged `settings.json`, then restore a known backup or move it aside to return to safe defaults. Do not edit approval policy to bypass a denied agent operation. - **Expired session:** preserve work and request a new explicit approval. Do not silently fall back to ordinary credential access.