App

The Happier app is the interactive client for people using Happier on desktop, web, and mobile.

Relay selection

The app can use Happier Cloud, or you can add one or more custom self-hosted Relays.

Saved Relays + switching

You can save multiple Relay profiles and switch between them.
Credentials are stored per Relay, so a hosted account and a self-hosted account won’t overwrite each other.
On different Relays, accounts are independent even if you use the same login provider.
On web, you can switch the Relay for this tab or make it the device default.
Web tabs that use the same browser profile and origin share the same browser storage substrate. Happier separates local records by Relay and account inside that storage, but separate browser profiles are the isolation boundary when you need fully separate local storage.

Configure-server links (1-click)

Some installers (for example hstack setup-from-source and Proxmox) print one-click links/QRs that open the app/web UI with the correct Relay URL prefilled.

Desktop control panel

On desktop, the app is intended to be the main control panel for your Happier setup:

start from the in-app /setup flow (desktop-only)
choose your Relay before signing in
sign in on that Relay
set up this computer
add a remote machine over SSH
repair Relay drift when the daemon is pointed at a different Relay
manage the local self-hosted Relay runtime
enable private access for a local/self-hosted Relay

This keeps Relay choice, account context, daemon state, and machine setup visible in one place instead of spreading the flow across separate CLI steps.

Multi-server workflows

For detailed Relay profile, switching, and multi-daemon guidance, see Features → Multi-server.

Notifications

Happier supports push notifications for:

turn completion (Ready)
permission requests
action requests that need a human answer

On iOS and Android, permission/action-request notifications can also expose action buttons and route you back into the correct session, including multi-server flows.

See Notifications for setup/self-hosting notes and Notification routing for the exact in-app behavior.

Session read and unread state

You can change read state from four places in the app: the session row's … menu, the row's long-press menu on mobile, the session header action menu, and Session info quick actions.

Marking a session unread while you are inside it sticks for that view rather than flipping straight back — closing and reopening counts as a new viewing intent.

Full guide: Session read and unread state.

Where the terminal appears depends on the room available. On larger layouts you choose the bottom panel, sidebar or details panel; phone layouts use a single focused presentation rather than juggling desktop-style panels.

It needs a connected daemon for that machine. If the daemon is attached to the wrong relay, the app says so and offers a repair rather than failing later in the flow.

Full guide: Embedded terminal.

Local memory search

Search runs against an index held by whichever daemon-connected machine you select, so with several machines you pick which one to search. Results open the matching session at the relevant point in the conversation.

Full guide: Local memory search.

Agent authentication in settings

The app can run a machine-local CLI login without you opening a terminal — through the shared bottom pane on larger layouts, or a focused presentation on smaller ones. The backend's settings page also shows auth status, method, and refresh actions where the agent supports them.

Full guide: Agent authentication.

Engine and model picker

The new-session picker offers built-in agents and any configured Custom ACP backends, with favourites pinned first. Whether you get a live model list, a fixed one, or a free-text field depends on the agent — see Agent capabilities.

Full guide: Model and engine selection.

Machine installables

Machine Details → Installables manages tools Happier can install and keep updated on that specific machine, with per-machine Auto-install when needed and Auto-update (off, notify, auto). Policies are per machine, so a laptop and a remote box can differ.

Full guide: Installables.

Session workspace surfaces

Sessions carry a repository-aware workspace. On larger layouts it splits into a right sidebar for Files and Git, and a details pane for previews, editors, review tabs, commit diffs and stashes. On phones the same surfaces become Cockpit tabs.

What you can do with them: Files and the editor, Diffs and review, Review comments and Git.

Mobile session cockpit

The cockpit is the default phone layout for sessions.

The bottom session tab bar can include:

the current agent tab, named after the backend such as Claude, Codex, or OpenCode
Files
Git
Navigation for jumping between earlier turns and pinned messages
Tabs for file previews, editors, Review, commit/stash details, and other detail surfaces
Terminal when the embedded terminal is enabled and available for that session

Switching cockpit tabs is treated as changing workspace surfaces, not as drilling deeper into browser/native history. Opening a file, Review, a commit, or a transcript file link opens the Tabs surface as a detail, so back can return to the list you came from.

You can switch back to the legacy phone layout from Settings → Session → Mobile session layout → Classic.

Swipe Teleport

In the cockpit, a horizontal swipe across the bottom band moves you to another session without going back to the list. Swipe left for the next session, right for the previous one.

Keep the gesture going and you keep travelling: one continuous swipe can cross several sessions rather than one, and each is named as you pass it so you can stop on the one you wanted. A single gesture reaches up to 19 sessions from where you started.

The order is the session list order you last saw, so it follows whatever sorting, grouping, and filtering the list is currently using. Swiping walks the same sequence you would get by returning to the list and tapping the row above or below.

Two things stay the same:

back still returns to the session list, not to the session you just came from, so swiping does not stack up history
the gesture only reacts to clearly horizontal movement, so scrolling vertically from the bottom band still scrolls

This is a mobile app gesture. The web and desktop clients keep using the list and their own navigation, and there is no on-screen control for it in the app — it is a shortcut for moving through a few sessions quickly, not a replacement for the session list.

You can turn it off from Settings → Session → Mobile session layout → Swipe between sessions.

Persistent tab/workspace state

The details pane is designed for multi-step work:

switching between details tabs keeps their local state
editor tabs preserve in-progress edits while you inspect other files
review/history tabs preserve scroll position when you come back
session workspace surfaces are intended to let you continue where you left off instead of rebuilding context each time

Focused details mode

When you need more room for a diff or file editor, the details surface can switch into a more focused layout instead of permanently compressing the main session area.

This is useful for:

reviewing large diffs
editing while keeping Git open
working on a smaller laptop/browser window

Session composer

The session composer is where you write the next prompt, add context, and choose how the next turn should be sent.

It supports:

plain text prompts and longer multi-line instructions
message attachments from your device
linked project files from the current workspace
included review-comment drafts when review comments are available
provider, permission, model, profile, machine, path, and resume controls when those options apply to the current session

The composer adapts to the available width. On roomy layouts, common controls can stay visible as chips near the text box. On narrower layouts, chip rows can scroll horizontally or collapse less-used actions into the action menu so the text box remains usable.

Keyboard behavior

By default, Enter inserts a new line and the send button sends the message.

If you enable Enter to Send in Session settings, Enter sends the current message when the composer has sendable content. On web, Shift+Enter inserts a new line. On iOS and iPadOS with a physical keyboard, Shift+Enter also continues to insert a new line while Enter sends.

This lets you choose between a chat-style flow and a writing flow:

use Enter to Send for short back-and-forth prompts
leave it off when you often write paragraphs, code blocks, logs, or step-by-step instructions

Messages can be sent with text, attachments, linked files, or included review comments. If the composer is empty or the current send action is disabled, pressing Enter does not send anything.

Composer actions

Use the composer action chips to add context before sending:

Attachments add files from your device, such as screenshots, logs, PDFs, and exported artifacts
Link file references files that already exist in the current workspace
Review comments includes selected review-comment drafts for the current workspace when that feature is available

Attachments and linked files solve different problems. Attachments bring external files into the session environment. Linked files point the agent at project files that are already in the workspace.

Review comments solve a more precise workflow: they attach your own line-specific instructions to file or diff lines, then send the selected comments with snippets and line anchors.

Linking project files into a prompt

The session composer includes file-linking helpers so you can send file context without manually typing paths.

Link file chip

Use Link file in the composer to open a project-file picker for the current workspace.

This is useful when you want to say things like:

“Explain this file”
“Refactor the two files I linked”
“Compare these configs”

`@`-style file search

Where supported, you can also use @-style file search from the composer to quickly reference workspace files.

The goal of both surfaces is the same:

quickly find a file
attach it to your next message
keep your session grounded in the real workspace instead of hand-written path references

The app also supports message attachments for local files that are not already in the workspace.

This is a separate workflow from Link file:

use Link file for files that already exist in the current workspace
use Attachments for files from your device, such as screenshots, exported logs, or documents

Current user-facing behavior:

images show as thumbnails in the composer
clicking a thumbnail opens a larger preview before send
sent image attachments render inline in the transcript
clicking a sent transcript image opens the same preview modal
per-file upload progress is shown while files are uploading
if Enter to Send is enabled, Enter can send an attachment-only message once the attachments are ready

Full guide: Attachments & image previews.

Updates

Hosted web app: updates land via deploys; refresh to pick up changes.
Mobile app: native updates come from the App Store / Play Store; OTA updates (when enabled) are fetched in-app and applied via an “Update available” banner (reload).
Self-hosted UI: if you’re serving the web UI from your own server (Docker/self-host runtime/runner), UI updates track your server/runtime update path.

Public release names stay stable, preview, and dev, but actual availability is artifact-dependent. Check Updates for the current desktop/mobile/web matrix instead of assuming every app shape ships every lane.

Full matrix (all apps/assets): Updates.

Authentication (keyed vs keyless)

Happier supports both:

Device-key accounts (default): end-to-end encrypted by default; users must restore access on new devices/browsers by using the account restore flow (for example Add your phone on a signed-in computer, or Restore with Secret Key Instead).
Keyless accounts (enterprise): no device keys; sign-in can be seamless across devices, typically paired with plaintext storage mode.

The app discovers available login and signup options from your server via GET /v1/features and renders what the server advertises.

Device linking, restore, and terminal QR flows

In the app, these are different flows:

Add your phone shows a QR code on a signed-in desktop/web app so a phone can join the same account
Restore account is the logged-out flow for joining an existing account on a new device
Scan QR to connect terminal approves a CLI/daemon connection and does not sign a new phone/browser into the UI
Enter URL manually is the fallback when you cannot scan

On phones and mobile-sized web browsers with camera support, Happier opens the account-restore scanner first. On larger web/desktop layouts, Happier shows a QR code that another signed-in device can scan instead.

If you self-host and your current server is localhost, Happier may intentionally omit the server URL from mobile QR/deep links. In that case, first configure the phone to a reachable server URL (LAN IP, Tailscale, or a public domain), then retry.

User guide: Features → Device linking & restore

For operator configuration, see: