dsh-deeppilot

Readme

# dsh-deeppilot

**English** | [简体中文](./README.zh-CN.md)

[![npm](https://img.shields.io/npm/v/dsh-deeppilot?style=flat-square)](https://www.npmjs.com/package/dsh-deeppilot)
[![DeepSeek Harness](https://img.shields.io/badge/DeepSeek%20Harness-plugin-4D6BFE?style=flat-square)](https://github.com/deepseek-ai/deepseek-harness)
[![CI](https://github.com/Mars-Sea/dsh-deeppilot/actions/workflows/ci.yml/badge.svg)](https://github.com/Mars-Sea/dsh-deeppilot/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

The open-source DSH companion plugin for **DeepPilot**, a native iPhone client
for using DeepSeek Harness remotely. It connects the app directly to the DSH
Host on your own Mac and does not replace or modify the DSH Web UI.

> DeepPilot is currently in TestFlight review. The invitation link will accept
> testers after Apple approves the build.

[Join the DeepPilot TestFlight](https://testflight.apple.com/join/JHb4j5DV)

## What you get

- Browse projects, sessions, history, and live agent output from iPhone.
- Send prompts, switch models, create sessions, and answer approvals/questions.
- Pair with a five-minute single-use code and a per-device P-256 key; physical
  iPhones keep the private key in Secure Enclave.
- Connect over a trusted LAN or the optional embedded Tailscale Funnel.
- Receive live notifications and optional APNs notifications while offline.
- Self-update hint: the settings page footer shows the installed plugin
  version, with an inline "new version" link to the matching GitHub
  release when one exists (background check, stable releases only, no
  third-party dependency).

## Install from npm

Requirements: Node.js 22+ and DSH with a `web` profile. The package includes
Funnel helpers for macOS, Linux, and Windows on amd64/arm64; trusted-LAN mode
does not require the helper.

| Plugin version | Required DSH | How to install |
|---|---|---|
| `0.6.x` (current stable, `latest`) | DSH `0.1.2-rc.1` or newer | `dsh plugin --profile web add dsh-deeppilot` |
| `0.5.x` (previous stable) | DSH `0.1.1-rc.2`–`0.1.2-alpha.1` | `dsh plugin --profile web add dsh-deeppilot@0.5.0` |

`0.6.x` is built and typechecked against the DSH
[0.1.2-rc.1](https://www.npmjs.com/package/@deepseek-ai/dsh/v/0.1.2-rc.1)
Host and client package family. It uses the Gateway multi-client Remote Events
routing that keeps Web and DeepPilot independently answerable. Earlier plugin
alphas remain historical artifacts; users installing the `alpha` tag for
pre-release testing should update DSH to `0.1.2-rc.1` or newer.

```sh
# DSH 0.1.2-rc.1 or newer (recommended):
dsh plugin --profile web add dsh-deeppilot
# DSH 0.1.1-rc.2 through 0.1.2-alpha.1 (previous stable):
dsh plugin --profile web add dsh-deeppilot@0.5.0
dsh web
```

After DSH restarts, open **Settings → DeepPilot**, enable the connection, show
the pairing QR code, and scan it in the DeepPilot app. The same panel also
shows a copyable pairing code for Simulator or manual entry.

LAN access is enabled by default on the plugin's independent TCP port `3098`.
DSH may continue listening only on `127.0.0.1:3080`; do not expose the full DSH
web server. If a firewall is enabled, allow inbound TCP `3098` on trusted
private networks. The port can be changed under **Advanced settings**.

Package: [npmjs.com/package/dsh-deeppilot](https://www.npmjs.com/package/dsh-deeppilot)

## Update or uninstall

```sh
dsh plugin --profile web update dsh-deeppilot
dsh plugin --profile web remove dsh-deeppilot
```

Restart DSH after updating. Uninstalling the package does not delete the local
DeepPilot state under `$DSH_HOME/deeppilot/`.

## Publishing (maintainers)

`0.6.x` targets DSH `0.1.2-rc.1`+; `0.5.x` stays compatible with
DSH `0.1.1-rc.2`–`0.1.2-alpha.1`. Keep both published:

1. Bump `version` in `package.json` and in the root `""` entry of
   `package-lock.json`, then run `npm test && npm run typecheck && npm run build`
   and inspect `npm pack --dry-run --json` (the check
   `tests/compatibility-metadata.test.ts` enforces the `^0.1.2-rc.1` peer
   ranges).
2. Commit the release and push it. `npm publish` runs `prepack` (build) and
   `prepublishOnly` (test + typecheck) automatically.
3. Publish pre-releases without touching `latest`:

   ```sh
   npm publish --tag alpha
   ```

   After a successful publish, `npm view dsh-deeppilot dist-tags --json` shows
   `"latest": "0.6.x"` and `"alpha": "0.6.x-alpha.y"`. Verify the published
   package by installing it into a DSH `0.1.2-rc.1` profile before pointing
   users at it.
4. Tag the release commit `vX.Y.Z` and prepare a GitHub Release
   (English + 简体中文 notes) that links this README section.
5. Publish stable releases with `npm publish --tag latest`, which moves
   `latest` to the new version. Stable releases must never be published
   with `--tag alpha`.

Never run `npm publish` from a copy that still has an older version.


## Connection and privacy

Conversation traffic travels directly between the iPhone and your DSH Host.
Trusted-LAN `ws://` traffic on the independent plugin port `3098` is
unencrypted, so use it only on a network you trust. Both the LAN listener and
optional Funnel mode expose only the DeepPilot connection, one-time pairing,
and health endpoints, not the complete DSH Web UI.

The DeepPilot settings page exposes **Connections per public source** under
the collapsed **Advanced settings** section. It defaults to `8`, accepts
`1`–`16`, and briefly restarts the Funnel helper when changed, so connected
remote clients reconnect once.

Offline push is optional. Relay mode sends only the target APNs device token
and a limited notification payload; full conversation history and live output
do not pass through the relay. Read [PRIVACY.md](./PRIVACY.md) and
[SECURITY.md](./SECURITY.md) before enabling remote access or push. Protocol-v2
implementation status and remaining release validation are tracked in
[docs/SECURITY_ROADMAP.md](./docs/SECURITY_ROADMAP.md).

## Screenshots

| Home | Sidebar | Chat | Settings |
| --- | --- | --- | --- |
| <img src="./assets/screenshots/home.png" alt="DeepPilot home screen" width="220"> | <img src="./assets/screenshots/sidebar.png" alt="DeepPilot sidebar" width="220"> | <img src="./assets/screenshots/chat.png" alt="DeepPilot chat screen" width="220"> | <img src="./assets/screenshots/settings.png" alt="DeepPilot settings screen" width="220"> |

## Compatibility

See [COMPATIBILITY.md](./COMPATIBILITY.md) for the tested baseline and current
limitations. DSH is still evolving; include exact DSH and plugin versions when
reporting an issue.

## Protocol

[PROTOCOL.md](./PROTOCOL.md) is the normative DeepPilot bridge protocol. Any
wire change must update that document and `src/protocol.ts` together and be
coordinated with the private iOS client. Protocol v2 is the only supported wire
version; upgrades from v1 require re-pairing.

## Development

```sh
npm ci
npm test
npm run typecheck
npm run build
cd helper && go test ./...
```

## Community and feedback

- [GitHub Issues](https://github.com/Mars-Sea/dsh-deeppilot/issues)
- [GitHub Releases](https://github.com/Mars-Sea/dsh-deeppilot/releases)
- [npm package](https://www.npmjs.com/package/dsh-deeppilot)
- [Linux.do 社区](https://linux.do/)

DeepPilot is an independent community project and is not affiliated with or
endorsed by DeepSeek.

## License

MIT — see [LICENSE](./LICENSE).