Documentation
Quick Start
ZenithDock is a native macOS, iOS, and iPadOS client that connects to a self-hosted agent server running Claude or Codex. Here's the minimum to get a conversation going:
- Claude: Install Claude Code CLI and run
claude loginto authenticate. - Codex: Install Codex CLI and set your
OPENAI_API_KEY.
- Install and authenticate Claude CLI and/or Codex CLI on your agent machine.
- Clone and start ZenithBotServer (see Server Setup below).
- Open ZenithDock and point it at your server (Inspector → Security → server URL → Apply & Reconnect).
- Click New Chat in the sidebar.
- Type a message and press ⌘ Return (Mac) or the send button (iOS).
Server Setup & Connecting
ZenithDock requires ZenithBotServer — a self-hosted FastAPI server that runs Claude/Codex agents and streams events back to the app.
Install the server
Run this on any Linux or macOS machine where you want agents to execute:
git clone https://github.com/ZhengyiLuo/ZenithBotServer
cd ZenithBotServer
uv venv && source .venv/bin/activate
uv pip install fastapi "uvicorn[standard]" python-multipart pydantic
curl -LsSf https://astral.sh/uv/install.sh | sh
Start the server
uv run python agent_server.py serve --bind 0.0.0.0 --port 7850
Verify it's running:
curl http://localhost:7850/api/health
# → {"ok": true, ...}
Keep it running — systemd (Linux)
cp systemd/zenithbot-agent.service ~/.config/systemd/user/
systemctl --user enable --now zenithbot-agent.service
Connect the app
- Open ZenithDock on your Mac or iPhone.
- Open the Inspector panel (right side on Mac, swipe from right on iOS).
- Under Security, enter your server URL:
http://<server-ip>:7850 - Click Apply & Reconnect.
The status dot turns green (Online) when connected.
Creating a Chat
Each chat is an independent conversation thread on the server. Chats are grouped into folders and persist across sessions.
- Mac: Click + New Chat in the sidebar. The chat appears in the General folder by default.
- iOS: Tap the compose icon or pull out the sidebar and tap New Chat.
To rename a chat, open the Inspector → Session section → edit the name field → click Save.
To move a chat to a different folder, right-click it in the sidebar → Move to Folder, or edit the Folder field in the Inspector.
Sending Messages
Type in the composer at the bottom of the chat window.
- ⌘ Return — send the message
- Shift Return — insert a newline without sending
- Tap the ↑ arrow button to send on iOS
The composer grows to fit multiple lines. Your unsent draft is saved automatically when you switch chats and restored when you return.
If the agent is already running when you send, the message enters the queue shelf and runs after the current turn finishes.
Backend & Model
Each chat uses either Claude or Codex as its backend. You can change the backend and model before sending the first message.
Switching backend
In the composer bar, click the Claude / Codex button to toggle. The backend locks after the first message — to switch, fork the chat or create a new one.
Selecting a model
Click the model button in the composer bar (shows the current model name) to pick from the server's catalog. You can also type a custom model ID in the Inspector under Custom model ID.
Claude models: Sonnet (default), Opus, Haiku, or any custom model ID.
Codex models: GPT-5.5 default, or a custom model ID.
Effort level
Click the effort button in the composer bar or use the Inspector Effort menu. Options: low, medium, high, xhigh, max. Higher effort uses more compute and may be slower but produces better reasoning on complex tasks.
Drafts
ZenithDock saves your unsent text per chat. When you switch to another chat and come back, your draft is exactly where you left it. Drafts are scoped to the server — the same chat on a different server endpoint has its own draft.
Forking a Chat
Forking creates a new independent chat that inherits the source chat's backend, model, and working directory. It does not copy the message history — it is a clean starting point with the same configuration.
- Right-click a chat in the sidebar → Fork Chat
- Or use the fork button in the chat header
The forked chat appears directly below the source in the same folder. Use forking to experiment with a different prompt or backend without losing the original conversation.
Resume by ID
If you have an existing Claude or Codex conversation ID from outside ZenithDock, you can resume it directly:
- Click Resume ID in the sidebar.
- Select the backend (Claude or Codex).
- Paste the provider session or thread ID.
- Optionally set a title, folder, and working directory.
- Confirm — the full history loads from the provider.
Folders
Chats are organized into folders in the sidebar. There are three special sections:
- Pinned — chats you pin; always at the top, never collapses.
- Folders — your custom folders; collapsible.
- Archived — archived chats; collapsed by default.
Creating a folder
Click Create Folder in the sidebar and enter a name.
Moving a chat
Right-click the chat → Move to Folder. You can also drag within the same section in Reorder mode.
Reordering folders
Click Reorder in the sidebar to enter reorder mode, drag folder headers or chat rows, then click Done.
Search
There are two ways to find chats:
- Sidebar search: Type in the search field at the top of the chat list. Results filter in place. Press X to clear.
- Quick Open (⌘ P): Opens a floating palette. Type to fuzzy-search all chats, use arrow keys to navigate, press Return to open. (Mac only)
Pin & Archive
Pinning a chat
Pinned chats stay at the top of the sidebar across all folders. To pin: open the Inspector → Run section → toggle Pin Chat. To unpin, toggle it off.
Archiving a chat
Archived chats are hidden in a collapsed section. To archive: Inspector → Run → Archive Chat. To unarchive, expand the Archived section in the sidebar and unarchive from there.
Marking as unread
Right-click any chat in the sidebar → Mark as Unread. The unread indicator reappears until you scroll to the bottom of that chat.
Reorder Mode
Click Reorder in the sidebar to enable drag-reordering for chats and folders. Drag rows to change their order, then click Done.
Live Streaming
ZenithDock connects to the server over WebSocket and streams every event in real time as the agent works. You see text appear word by word, tool calls as they happen, and artifacts as soon as files stabilize.
The timeline auto-scrolls to the latest message while you're at the bottom. If you scroll up to read earlier messages, a ↓ New button appears — click it to jump back to the latest and mark messages as read.
Loading Older Messages
Long chats are paginated. When older messages exist above the visible timeline, a Show Older banner appears at the top (Mac) or a Load Older button (iOS). Tap it to load the previous page of messages. You can page back as many times as needed.
Unread Tracking
When a chat receives new messages while you're elsewhere, it shows an unread indicator in the sidebar. Switching to the chat and scrolling to the bottom marks it as read and syncs the read cursor to the server.
A visual separator line in the timeline marks where unread messages begin.
File Uploads
You can send files to the agent server alongside your message.
- Click + (attach): Opens a file picker in the composer bar.
- Drag & drop: Drag files onto the composer — the border highlights to confirm the drop zone is active.
- Paste: ⌘ V a file copied from Finder.
Selected files appear as chips below the text field. Click ✕ on a chip to remove it before sending. All attached files are uploaded when you send the message.
Uploaded files appear in the timeline as an attachment grid and are listed in the Inspector's Files section. Use the download button to save them locally.
Artifacts & Media
When the agent produces output files — images, videos, code — they appear as artifact cards in the timeline, often before the turn finishes (as soon as the file is stable on the server).
- Images: Shown as thumbnails; click to open a full-size preview.
- Videos: Shown with a poster frame; click to play inline with native controls.
- Other files: Shown as a downloadable link with file name and type.
All artifacts are also listed in the Inspector's Files & Videos section for the current chat. On Mac, click Download to save a file via the system save dialog. On iOS, use the share button to save or share.
Pinned Items
Any message, artifact, or file in the timeline can be pinned to the Inspector's Pinned shelf for quick reference.
- Pin: Hover over a message (Mac) or long-press (iOS) → click the pin icon.
- Find in timeline: Click a pinned item in the Inspector to scroll to it in the timeline.
- Copy: Copy the full text of a pinned message.
- Unpin: Click Unpin on any pinned item.
Pinned items are stored per chat and persist across app launches.
Message Queue
If you send a message while the agent is running, it enters the queue shelf — a row below the composer showing all pending messages.
From the queue shelf you can:
- Send Now: Interrupt the current run and start this message immediately.
- Edit: Modify the queued text before it runs.
- Move Up / Down: Reorder queued messages.
- Remove: Delete a queued message.
Scheduled Jobs
Schedule a recurring prompt to run automatically in a chat at a set interval.
Creating a job
- Open the Inspector → scroll to the Jobs section → click Schedule Job…
- Fill in the title, prompt text, and interval.
- Choose a first-run time: Now, After interval, In N minutes, or a custom date/time.
- Set the run mode: Loop forever or Run N times.
- Save.
Interval presets
30 seconds · 1 min · 5 min · 15 min · 1 hour · 6 hours · 12 hours · 24 hours — or enter a custom value in seconds.
Job status in the timeline
- Yellow card: Job created.
- Orange card: Job ran — shows duration and result summary.
- Orange "Deferred" card: Server was busy; the job will retry later. This is not an error.
- Red card: Job failed with an error.
Editing a job
Open the Inspector → click the job → modify fields → save. Changing the interval or prompt does not reset the next run time unless you explicitly reschedule it.
Handoff Digest
A handoff digest summarizes one chat and sends that context to another chat — useful for passing context between different agents or starting a focused follow-up conversation.
Creating a digest
- Open the Inspector → Run section → click Create Digest.
- Pick the target chat that should receive the context.
- Choose a detail level: Short, Normal, or Deep.
- Optionally add a prompt to guide the summary.
- Click Preview to see the digest before sending, or Send to deliver it directly.
The digest runs as a visible turn in the source chat (using its backend and model), then the result is forwarded to the target chat as a new turn.
Security & Access Tokens
By default the server accepts connections from anyone on the network. To restrict access, set the ZENITHDOCK_AGENT_TOKEN environment variable on the server:
# systemd override
[Service]
Environment=ZENITHDOCK_AGENT_TOKEN=your-long-random-token
Then enter the same token in the app: Inspector → Security → Agent access token → Apply & Reconnect.
When a token is set, all API calls, file uploads, WebSocket streams, and file/video previews require it. The token is stored in the system Keychain on Mac and iOS.
Keyboard Shortcuts (Mac)
| Action | Shortcut |
|---|---|
| Send message | ⌘ Return |
| New line in composer | Shift Return |
| Quick Open (find chat) | ⌘ P |
Common Issues
Can't type in the message input
The composer is disabled until a chat is selected. Click New Chat in the sidebar first, then click the chat to select it. The input should become active automatically.
Server shows "Offline" / red dot
- Make sure the server is running:
curl http://<server-ip>:7850/api/healthshould return{"ok": true}. - Double-check the URL in the Inspector — it should be
http://<ip>:7850, nothttps://. - If connecting over the internet, use Tailscale instead of exposing the port directly.
Messages send but get no response / spinner never stops
This usually means WebSocket streaming is broken. On the server, check that uvicorn[standard] is installed (not bare uvicorn) — it includes the websockets library required for live streaming:
uv pip install "uvicorn[standard]"
Then restart the server. You should not see No supported WebSocket library detected in the server logs.
Old chats return 404 after server restart
The server stores session state on disk under ~/.zenithbot-agent/. If you restarted the server and a session disappears, it may have been created while using a different state directory. Create a new chat — existing sessions that are on disk will reload on next access.
iOS can't reach the server on local network
Go to Settings → Privacy & Security → Local Network and make sure ZenithDock has permission. If that doesn't help, check that your Mac/server and iPhone are on the same Wi-Fi network and that the firewall isn't blocking port 7850.
Backend locked — can't switch from Claude to Codex
The backend locks after the first message is sent in a chat. To use a different backend, either fork the chat (Inspector → Run → Fork Chat) or create a new chat and switch before sending anything.
uv command not found
Install uv and add it to your PATH:
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.local/bin/env # or restart your terminal