dsh-fingerprint-relay

Readme

# DSH Fingerprint Relay

Lets DSH reach providers that **gate on the client's TLS fingerprint** (for example agentrouter.org).

The plugin runs a local Python egress process that the upstream allow-lists, and forwards DSH's requests through it.

[中文说明](README.zh.md)

## When you need it

The provider works in a browser or its official CLI, but DSH gets `unauthorized client detected` or a 403.

## Requirements

- DSH Desktop (framework `0.1.0-rc.8`)
- Python 3.11+

## Install

```powershell
git clone https://github.com/Wilfred-wei/dsh-fingerprint-relay.git
cd dsh-fingerprint-relay
.\scripts\install.ps1
```

The script installs the plugin, creates a Python venv, installs its dependencies, writes the interpreter path into your profile, and verifies the result.

Then **restart DSH Desktop**.

<details>
<summary>Without the script: two manual steps</summary>

```powershell
# 1. install the plugin
dsh plugin --profile web add dsh-fingerprint-relay

# 2. create the Python environment
$relay = "$env:USERPROFILE\.dsh\profiles\node_modules\dsh-fingerprint-relay"
python -m venv "$env:USERPROFILE\.dsh\fingerprint-relay-venv"
& "$env:USERPROFILE\.dsh\fingerprint-relay-venv\Scripts\python.exe" -m pip install -r "$relay\resources\requirements.txt"
```

Then point the plugin at that interpreter in `%USERPROFILE%\.dsh\profiles\web\cordis.patch.yml`:

```yaml
- id: fingerprint-relay-host
  config:
    pythonPath: C:\Users\<you>\.dsh\fingerprint-relay-venv\Scripts\python.exe
```

</details>

## Usage

1. Settings -> **Fingerprint relay** -> **Add relay**
   - Upstream URL: `https://agentrouter.org`
   - Local port: `7187`
2. Press **Start**; the status becomes `running / healthy`
3. Under **Providers through a relay**, point an Anthropic provider (such as `agent-claude`) at it
4. Chat as usual

The API key stays where it already is — in the provider's own configuration. The relay stores no keys.

## Limitations

- Anthropic Messages channel only; on new-api style gateways set the provider's protocol to `anthropic-messages` even for GPT models (the gateway converts them). Native OpenAI endpoints are not supported.
- The egress process listens on `127.0.0.1` only
- Accepted on Windows

## Troubleshooting

| Symptom | Fix |
| --- | --- |
| No "Fingerprint relay" section in Settings | Restart DSH Desktop; `dsh --profile web --dump-config` should list `fingerprint-relay-host` |
| Start fails: missing Python packages | Re-run `.\scripts\install.ps1`, or `pip install fastapi uvicorn httpx anthropic` for that interpreter |
| Start fails: port in use | Pick another local port |
| Requests return 401 | That provider has no API key configured |
| Long stall, then `no stream data for 120s` | The upstream stalled; the relay already retried once — send again |
| Config change had no effect | Press **Stop** then **Start** in Settings |

## Building from source

```bash
npm install --legacy-peer-deps
npm run build
npm test
npm pack --ignore-scripts
```

Architecture and behaviour specs live in `docs/`.

## License

MIT