Settings Reference

Use this reference to understand every PocketHook setting and how each option changes server communication or automation behavior.

Manage servers

#

Open Settings → Manage servers to add, rename, edit or remove profiles. Connection, OpenClaw mode, timeouts, health checks, pending jobs and Personal UI belong to each server. Give each profile an optional emoji, or leave it empty for the standard icon. One server is free, including QR setup; multiple servers require Pro. See setup, migration and storage details.

Sync

#

Choose Sync this server with iCloud to share its name, emoji, chat wallpaper, bubble colors and opacity, connection settings, delivered messages and saved links. Other devices list it under Available in iCloud; you choose where to add it, and its history downloads only after you do. Keep sync off for a device-only server. The selected server, drafts and pending sends remain independent on every device. Authentication tokens sync securely through iCloud Keychain when server sync is enabled. Enable iCloud Keychain on both devices using the same Apple Account; credentials may arrive separately from the profile. You do not need to copy the token obtained by QR. The original conversation retains its existing iCloud synchronization.

Manage servers checks iCloud when opened. Refresh iCloud lets you check again and shows progress and the last check. Profile, history and credential delivery can take time; a profile without credentials shows that it is waiting for Keychain before allowing a send.

Appearance and navigation

#

Open Settings → Manage servers → your server → Appearance → Styles. Choose an image from Photos or Files, remove it, set colors for your messages and replies, and adjust bubble opacity. The preview shows the result. Text and images do not lose opacity. Reset bubble colors restores the automatic colors.

Apply background to all servers is available with multiple profiles and copies only the image to servers added on this device. It preserves their colors, opacity and individual sync choices. Wallpapers and colors are never sent to the server; they sync through iCloud only for profiles with sync enabled. These options are free.

Mac and wide iPad windows support top or sidebar navigation; iPhone keeps bottom tabs. Liquid Glass controls follow system settings. Reduce Transparency takes precedence over your bubble opacity choice. Reply options appear as a card with one row per option, using the server’s reply color.

Photos

#

Photo-library links are free. Enable them on this device to open photo queries from chat. iOS still asks for the required library permission; opening a photo link does not upload images. Sending an attached image sends it to the selected server.

Server Configuration

#

The core connection settings for your PocketHook server.

Server URL

#

The HTTPS endpoint where PocketHook sends your chat messages. Only HTTPS URLs are accepted — HTTP is rejected for security. This is the primary endpoint your server listens on.

Authentication Token

#

Bearer token sent in the Authorization header with every request. Your server can use this to verify that requests come from your device. Stored securely in the iOS Keychain — never in plain text.

OpenClaw Compatible

#

Enable if your server uses the OpenClaw platform or any OpenAI-compatible Chat Completions API. When enabled, PocketHook sends messages in the OpenAI chat format and parses inline shortcut markers ([SHORTCUT:name], [DATA:{...}], [URL:...]) from the response. An x-openclaw-agent-id header is included with requests.

Test Connection

#

Button that sends a test request to your configured server. Displays:

• Response time in milliseconds
• Health check result (if enabled)
• Error details if the connection fails

Use this after changing your Server URL or Auth Token to verify everything works.

Network

#

Fine-tune timeout behavior for different types of operations.

Request Timeout

#

How long PocketHook waits for the server to start responding to a request. If your server does heavy processing (like calling an AI model), increase this value. The default is 60 seconds.

Resource Timeout

#

Maximum time for the entire response to complete, including data transfer. This should be higher than the Request Timeout. Increase if your server returns large payloads or has slow upload speeds.

Health Check

#

Enable server health monitoring. When active, PocketHook sends a GET request to the Health Check URL during connection tests and displays whether your server reports healthy.

Health Check URL

#

A separate HTTPS endpoint that returns plain text true or false. This URL is pinged during connection tests to verify your server is operational. Useful when your main API endpoint is behind authentication but you want a simple status check.

Automation

#

Control how PocketHook executes iOS Shortcuts triggered by server responses.

iOS Shortcuts

#

Master toggle for Shortcut execution. When OFF, PocketHook still displays messages from the server but ignores any shortcut fields in responses. Useful for debugging or temporarily disabling automations.

Delay Between Shortcuts

#

Wait time between executing consecutive shortcuts when the server returns multiple automations in a single response. Increase this if your shortcuts depend on each other (e.g., the first shortcut creates a file that the second one reads).

Shortcut Timeout

#

Maximum time to wait for each individual shortcut to finish before PocketHook considers it timed out. Long-running shortcuts (like ones that process media or make multiple API calls) may need the full 5 minutes.

Personal UI

#

Embed a custom web interface directly in PocketHook.

Personal UI

#

Show a dedicated tab with an embedded web view. When enabled, a new tab appears in the main navigation where your custom web page is displayed. The page is preloaded for instant display and supports pull-to-refresh.

Personal UI URL

#

The URL to display in the Personal UI tab. Both HTTP and HTTPS are accepted (HTTPS recommended). This could be a dashboard, admin panel, or any web page you want quick access to alongside your chat.

Links

#

Configure how PocketHook handles URLs from server responses.

Links Tab

#

Show or hide the Links tab in the main navigation. When enabled, all URLs received from server responses are saved and displayed in a dedicated tab with rich link previews, search, and delete functionality.

Auto-open URLs

#

When enabled, PocketHook automatically opens URLs from server responses in your default browser. When disabled, URLs are still saved to the Links tab (if enabled) but won’t open automatically.

This setting is per-device on purpose: you might want links to open automatically on your iPhone but not on your Mac. Tapping the link pill under a message always opens it, regardless of this setting.

Language

#

Customize the app and dictation language.

App Language

#

Override the app’s display language independently of your device language. When set to “System Default”, PocketHook follows your iOS language setting.

Dictation Language

#

Language used for voice dictation (speech-to-text) in the chat input. Available languages:

Background Tasks

#

Periodically check for pending tasks even when the app is in the background.

Background Tasks

#

Enable background polling. When active, PocketHook periodically sends a GET request to the Polling URL. If the response is true, it sends the Fetch Message to your main server when the app opens. Requires notification permission to alert you of pending tasks.

Check Interval

#

How often PocketHook checks the Polling URL in the background. Shorter intervals mean faster detection of pending tasks but use more battery. iOS may adjust the actual frequency based on device usage patterns.

Polling URL

#

HTTPS endpoint that PocketHook polls at the configured interval. Must return plain text true (tasks pending) or false (no tasks). This is a lightweight check — your server should respond quickly without heavy processing.

Agent Server: Use https://your-host/jobs (adjust host and port to match your setup).

Fetch Message

#

The message sent to your main server when a background check finds pending tasks and the app opens. The server response appears in chat like any other message. Customize this to trigger specific server-side behavior.

Data Management

#

Monitor and manage your stored messages.

Messages Stored

#

Shows how many messages are currently stored. The indicator is color-coded:

• Green — Under 70% capacity
• Orange — 70–90% capacity
• Red — Over 90% capacity

When the 500-message limit is reached, the oldest messages are automatically deleted to make room for new ones.

Export Conversation

#

Button that exports all stored messages as a JSON file via the iOS share sheet. You can save the file, AirDrop it, or share it with any app. Useful for backing up conversations or analyzing message history.

Delete All Messages

#

Destructive button that permanently removes all stored messages. Requires confirmation before executing. This action cannot be undone.

About

#

Read-only information about your PocketHook installation.