ZPad / User Guide
User Guide · v1.0

Everything ZPad can do,
in one page.

ZPad keeps a real multi-tab browser, a real terminal and a CodeMirror editor one hotkey away — ⌘⌥P from anywhere. This guide covers install, every feature, licensing, and fixes for anything that can go wrong.

1 · Install & first run

From download to first summon in about a minute.

Requirements

  • macOS 15.1 (Sequoia) or later
  • Apple Silicon (M1/M2/M3/M4) — current release builds are arm64; Intel Macs are not supported
  • Internet connection for browsing (the app itself works offline)

Install

  1. Download the .dmg from the official Releases page. Every release build is Developer ID–signed, Apple-notarized, and stapled.

  2. Open the disk image and drag ZPad into Applications.

  3. Launch ZPad. macOS may ask you to confirm opening an app downloaded from the internet — this is normal Gatekeeper behavior for notarized apps. Click Open.

  4. First-run onboarding walks you through the hotkey and the trial: 30 days, fully functional, no credit card. The trial starts when you accept the offer — launching alone never consumes a trial day.

  5. Press ⌘⌥P. The panel slides out. That's it.

Security tip

If macOS ever says the app is “damaged” or refuses to open it: do not bypass Gatekeeper. Delete the download, confirm you are on the official Releases page, and re-download. A genuine notarized build opens cleanly.

Where things live

DataLocation
App support (chats, workspace data)~/Library/Application Support/ZPad/
Preferences & trial state~/Library/Preferences/ (standard defaults storage)
API keys (AI chat)macOS Keychain — never plaintext files
Browser data (cookies, cache)App-managed WebKit data store, clearable from Settings

2 · The panel & display modes

Four ways to summon ZPad — pick the one that fits your muscle memory.

Side panel (right)

⌘⌥2

Default. Slides from the right edge — ideal next to your editor.

Side panel (left)

Settings → Display

Mirror layout for dock-right users.

Centered modal

⌘⌥1

Big, focused, spotlight-style. Great for heavy browsing sessions.

Navbar anchor

⌘⌥3

Drops down under the menu-bar icon — classic dropdown feel.

Summon & dismiss

  • Hotkey: ⌘⌥P toggles the panel from any app, fullscreen included.
  • Hot zone: move the mouse to your screen edge and the panel slides out automatically. Can be disabled in Settings → Behavior if it triggers accidentally.
  • Menu-bar icon: click it for the classic menu (modes, workspaces, settings, quit).
  • Dismissing keeps everything alive — tabs, terminal scrollback, and per-workspace state are preserved exactly as you left them.

Made for multi-screen

On multi-monitor setups the panel can follow the screen your mouse is on (Settings → Behavior → Multi-screen mouse following), and window geometry is remembered per mode.

3 · Browser

A real WebKit (WKWebView) browser — not an embedded teaser. Sign in, watch, download, develop.

Everyday use

  • New tab: ⌘T, or the + in the sidebar. Tabs are typed — web, terminal, or chat — living in one sidebar.
  • Unified URL bar: type a URL or a search query; ZPad routes it for you.
  • Find in page: ⌘F (when a web view is focused).
  • Zoom: ⌘+ / ⌘− / ⌘0 to reset.
  • Jump to tab: ⌘1…9. Reopen closed: ⌘⇧T.
  • Right-click tabs for rename, pin, duplicate, and close-others.

Favicons

Site icons are fetched via DuckDuckGo's icon service on first hit and cached locally afterward. Prefer zero favicon network traffic? Turn it off in Settings → Privacy → Favicon network fetch.

Bookmarks & history

Save pages as favorites (with folders) for instant access from the homepage, and revisit recent URLs via browsing history. Everything is stored locally — see Privacy.

4 · Terminal

A real terminal emulator (SwiftTerm) with a full PTY — your shell, your tools, your themes.

Terminal tabs

  • Create terminal tabs from the sidebar + menu — each gets an independent session.
  • Scrollback is preserved even after you dismiss the panel: terminal views are kept alive, not torn down.
  • Your default shell is auto-detected from /etc/shells — zsh, fish, whatever you've set.

Works with your CLI stack

Anything that runs in a terminal runs here: git, npm, docker, ssh, vim — and agentic CLIs like Claude Code:

$ claude
# → reads your repo, edits files, runs commands
# → all inside the same panel you summon with ⌘⌥P

Themes & fonts

Built-in terminal palettes plus custom theming, adjustable font size, and a working directory shown per tab. Colors follow the system appearance.

Tip

Keep one terminal tab per project and put them in a workspace — switching workspaces restores each project's shell state instantly.

5 · Workspaces & favorites

Workspaces are saved, switchable sets of tabs — think browser profiles for projects.

  • Create workspaces like “Frontend”, “Infra”, “Research” — each keeps its own tabs, terminal sessions, and layout.
  • Switch instantly from the workspace menu in the panel header; nothing is closed or lost.
  • Favorites are bookmarked sites organized into folders, available from the homepage of any workspace.
  • Workspace automation (Settings → Behavior) can re-evaluate and switch workspaces based on your active context.

6 · Command palette

Everything is one fuzzy-search away — even while the panel is hidden.

  • ⌘K — open the palette from anywhere (works when the panel is hidden too).
  • ⌘⇧A — palette scoped to tabs: fuzzy-jump between web, terminal, and chat tabs.
  • Actions include new tab / terminal / chat, workspace switching, settings, and more.

7 · AI chat Beta

Bring your own model: any OpenAI-compatible API — including local Ollama.

Set up a provider

  1. Open Settings → Chat and enter your provider's Base URL (e.g. https://api.openai.com/v1 or http://localhost:11434 for Ollama).

  2. Paste your API key — it's stored in the macOS Keychain, never in plaintext. Local providers like Ollama need no key.

  3. Click Test connection, then Fetch models to list what your provider offers.

  4. Create a chat from the sidebar + menu and start talking.

What you get

  • Streaming replies (SSE) with automatic non-streaming fallback
  • Markdown rendering with copyable code blocks
  • Per-chat model override, temperature, context window, and system prompt
  • Send with ⌘↩ or ↩ — your choice
  • Auto-titled conversations; pin / rename / clear / close from the context menu
  • History stored locally as JSON under ~/Library/Application Support/ZPad/Chats/ — one file per conversation, yours to back up or delete
Privacy

Chats are sent only to the provider you configure, with the key you provide. ZPad adds no middleman, no telemetry on message content, and no cloud storage.

8 · Keyboard shortcuts

The full list. Global shortcuts work from any app; panel shortcuts when the panel is visible.

ShortcutScopeAction
⌘⌥PGlobalSummon / dismiss the panel
⌘⌥1GlobalToggle panel in centered mode
⌘⌥2GlobalToggle panel in side-panel mode
⌘⌥3GlobalToggle panel in navbar mode
⌘KGlobalCommand palette (all actions)
⌘⇧AGlobalCommand palette (tab switcher)
⌘TPanelNew tab
⌘⇧TPanelReopen last closed tab
⌘WPanelClose current tab
⌘1…9PanelSwitch to tab N
⌘FPanel (web)Find in page
⌘+ / ⌘− / ⌘0Panel (web)Zoom in / out / reset
⌘,PanelOpen Settings

Terminal tabs keep their native key handling (shell history, copy/paste, Ctrl-C…); browser shortcuts only intercept when a web view owns the surface.

9 · Settings reference

Open with the menu-bar icon, the gear in the panel, or ⌘,.

SectionWhat's inside
PrimaryLanguage (follow system / English / 简体中文) · Display mode
Homepage bannerBanner style for the panel homepage — animated scenes (aurora, clock, coast, dolphin, fireworks, fish tank, sunset), random, custom image / video, or custom HTML (script recipes included)
BehaviorHot-zone (edge) trigger on/off · Auto-close panel · Multi-screen mouse following · Workspace automation
PrivacyAnalytics opt-in (off by default) · Favicon network fetch · Automatic update checks · Clear browser data
ChatProvider Base URL · API key (Keychain) · Connection test · Model list · Temperature · Context window · System prompt · Streaming · Send-key mode · Font size · Starter prompts · Delete all chats
AdvancedUser scripts — run your own scripts from the panel
SystemCheck for updates · Privacy policy · EULA · Acknowledgments

10 · License & activation

30-day trial → one-time $69 founding lifetime license (first 500, then $99) · 3 Macs · offline-friendly · 14-day refund.

The trial

  • 30 days, fully functional — every feature, no watermarks, no credit card.
  • The trial starts only when you accept it during onboarding; merely launching never burns a day.
  • Rolling the system clock back doesn't extend it (tamper detection).

Buy & activate

  1. Buy inside ZPad — open the license screen in Settings and pick a plan (card or Apple Pay). The website only serves downloads.

  2. Your license key arrives by email within minutes (via Resend). Keep it — it's your proof of purchase.

  3. In ZPad, open the license screen from the menu-bar icon or the trial banner, paste the key, activate. Verification is signed (Ed25519) and can be validated locally.

Devices, offline & transfers

  • 3 Macs per license — your MacBook, iMac, and work machine can all be active.
  • Offline grace: an activated license works offline for up to 14 consecutive days (flights, cabins, outages). Reconnecting re-confirms automatically.
  • Device management is self-serve: deactivate an old Mac from the app's license screen, or recover a license via email if you lose the key.
  • Getting a new Mac? Deactivate the old one first if you're at the 3-device limit; otherwise just activate the new one.

Refunds

Full refund within 14 days of purchase, no questions asked. Email [email protected] with your order details. Details in the Refund Policy.

11 · Updates

Signed update metadata served over HTTPS — no silent binaries.

  • Automatic checks can be enabled or disabled in Settings → Privacy. Disabled means ZPad only checks when you ask.
  • Check manually: Settings → System → Check for updates.
  • Update metadata is signed; the app verifies it before offering anything.
  • Prefer manual installs? Grab the latest .dmg from Releases and drag over the old app — your settings and license carry over.

See what shipped in each version on the changelog.

12 · Privacy & security

Local-first by design. Every network call is listed, scoped, and (mostly) optional.

ServicePurposeWhenCan disable?
DuckDuckGoFavicon lookupFirst visit to a hostname, if enabledYes — Settings → Privacy
StripeCheckoutOnly when you buyn/a (hosted page)
ResendLicense email deliveryOnly after purchasen/a
ZPad license APIActivation, device limits, recoveryLicensing actions; installed licenses re-report on launch (14-day offline grace)Inherent to licensing
Update serviceSigned update metadataManual checks, or automatic if enabledYes — Settings → Privacy
AnalyticsProduct usage statsNever, unless you opt inOff by default
Your AI providerChat completionsOnly when you send a chat messageDon't configure a provider

Full disclosure — what's sent, why, and how to switch each integration off — lives in PRIVACY.md. Release builds are Developer ID–signed and Apple-notarized.

13 · Troubleshooting

The fixes for 95% of support questions. Still stuck? Contact support.

macOS says ZPad is “damaged” or won't open+

This happens with corrupted or unofficial downloads. Do not bypass Gatekeeper (no xattr tricks). Delete the copy, download again from the official Releases page, and confirm the download completes fully before opening.

The panel doesn't appear when I press ⌘⌥P+

Another app may own that shortcut (check tools like Raycast, BetterTouchTool, or IME switchers). Try the mode-specific shortcuts (⌘⌥1/2/3) or the menu-bar icon. If it persists, quit and relaunch ZPad.

The panel appears when I don't want it (edge triggers)+

That's the hot-zone feature. Turn it off in Settings → Behavior → hot-zone trigger and rely on the hotkey instead.

License activation fails+
  • Check you're online and pasted the entire key from the email.
  • At the 3-device limit? Deactivate an old device first (license screen → device management).
  • Still failing? Email support with your order ID — we'll fix it.
Terminal tab shows no prompt / wrong shell+

ZPad reads valid shells from /etc/shells. If your custom shell isn't listed there, add its path and relaunch. A stuck session can be closed and reopened from the tab context menu.

Website X doesn't work in the browser+

ZPad uses Apple WebKit, same engine as Safari. Sites that block Safari may also block embedded WebKit. Try lowering tracking protection for that site in Settings, or use “Open in default browser” from the tab context menu.

AI chat errors: connection / 401 / no models+
  • 401 → wrong API key (re-paste it; it lives in Keychain).
  • Connection refused → for Ollama make sure it's running and the Base URL is right (http://localhost:11434).
  • No models listed → click Fetch models again after a successful connection test.
ZPad feels slow or battery-hungry+

ZPad is native Swift and idles quietly. Heavy pages (dozens of tabs, video) use real memory — close what you don't need. Terminal and chat tabs are lightweight. Auto-mute audio in Settings to stop background tabs from playing sound.

14 · Uninstall

No uninstaller needed — and no data left behind if you don't want it.

  1. Quit ZPad from the menu-bar icon.
  2. Delete /Applications/ZPad.app.
  3. (Optional) remove remaining data:
    rm -rf ~/Library/Application\ Support/ZPad
    rm -rf ~/Library/Caches/com.zpad.* 2>/dev/null
    defaults delete com.zpad.app 2>/dev/null
  4. (Optional) remove the ZPad entry from Keychain Access if you stored an AI provider key.

License refunds within 14 days: see the Refund Policy.