Archived legacy documentation. These historical setup instructions are not current. See the current setup guide.

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:

Prerequisites: You need at least one AI CLI installed and authenticated on your server machine before the agent can run:
  • Claude: Install Claude Code CLI and run claude login to authenticate.
  • Codex: Install Codex CLI and set your OPENAI_API_KEY.
  1. Install and authenticate Claude CLI and/or Codex CLI on your agent machine.
  2. Clone and start ZenithBotServer (see Server Setup below).
  3. Open ZenithDock and point it at your server (Inspector → Security → server URL → Apply & Reconnect).
  4. Click New Chat in the sidebar.
  5. Type a message and press ⌘ Return (Mac) or the send button (iOS).
Tip: The input field is disabled until a chat is selected. Always click New Chat first.

Server Setup & Connecting

ZenithDock requires ZenithBotServer — a self-hosted FastAPI server that runs Claude/Codex agents and streams events back to the app.

1

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
uv not installed? Run: curl -LsSf https://astral.sh/uv/install.sh | sh
2

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, ...}
3

Keep it running — systemd (Linux)

cp systemd/zenithbot-agent.service ~/.config/systemd/user/
systemctl --user enable --now zenithbot-agent.service
4

Connect the app

  1. Open ZenithDock on your Mac or iPhone.
  2. Open the Inspector panel (right side on Mac, swipe from right on iOS).
  3. Under Security, enter your server URL: http://<server-ip>:7850
  4. Click Apply & Reconnect.

The status dot turns green (Online) when connected.

Remote access: Use Tailscale to reach the server outside your local network instead of exposing port 7850 publicly.
iOS local network: Grant Local Network permission in System Settings → Privacy & Security → Local Network.

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:

  1. Click Resume ID in the sidebar.
  2. Select the backend (Claude or Codex).
  3. Paste the provider session or thread ID.
  4. Optionally set a title, folder, and working directory.
  5. 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.

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.

Chats can only be dragged within their own section (pinned ↔ pinned, folder ↔ same folder, archived ↔ archived). To move a chat between folders, use Move to Folder instead.

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.
Stop vs Send Now: The Stop button halts the current run but leaves the queue intact. Send Now interrupts the current run and immediately starts the selected queued item.

Scheduled Jobs

Schedule a recurring prompt to run automatically in a chat at a set interval.

Creating a job

  1. Open the Inspector → scroll to the Jobs section → click Schedule Job…
  2. Fill in the title, prompt text, and interval.
  3. Choose a first-run time: Now, After interval, In N minutes, or a custom date/time.
  4. Set the run mode: Loop forever or Run N times.
  5. 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

  1. Open the Inspector → Run section → click Create Digest.
  2. Pick the target chat that should receive the context.
  3. Choose a detail level: Short, Normal, or Deep.
  4. Optionally add a prompt to guide the summary.
  5. 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)

ActionShortcut
Send message⌘ Return
New line in composerShift 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/health should return {"ok": true}.
  • Double-check the URL in the Inspector — it should be http://<ip>:7850, not https://.
  • 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