dsh-vpn-ops
简体中文
Safety-gated WireGuard and VLESS Reality operations for
DeepSeek Harness (DSH).
dsh-vpn-ops is a real DSH bundle: it ships cordis.patch.yml, exports a Cordis
apply(ctx, config) lifecycle entry point, and registers eight typed tools. It
turns a reviewed, allowlisted server definition into repeatable preflight,
plan, apply, status, verification, rollback, and client-export operations.
Status: 0.1.0 initial public release. The bundle load path is verified against
DSH 0.1.1-rc.2; production network rollout still requires an operator-owned
staging server and acceptance test. See Compatibility and
Limitations.
Why this is not “SSH from the model”
The model can choose only a configured targetId and clientId. It cannot
supply a host, credential, remote path, package URL, or shell command.
- Strict host-key checking and public-key-only SSH are mandatory.
- Every process is spawned with an argv array; no local shell is used.
- Remote work runs a fixed helper shipped in the reviewed package.
- Remote mutation defaults to off.
vpn_apply requires a fresh, persisted plan, an unchanged remote baseline,
and the exact confirmation string returned by vpn_plan.- Apply writes backups before the first managed-file change and automatically
restores them if the transaction fails.
- Client secrets are never returned as tool values. Explicit export streams
them into new local mode-
0600 files and returns only paths, sizes, and
SHA-256 evidence.
- The npm package has no
preinstall, install, postinstall, prepare, or
prepack lifecycle script.
Read the complete threat model before enabling changes.
Tools
| Tool | Changes state | Gate |
|---|
vpn_targets | No | None |
vpn_preflight | No | Allowlisted target |
vpn_status | No | Allowlisted target |
vpn_plan | Local non-secret plan file | Preflight must pass |
vpn_apply | Yes, remote | allowMutations, fresh plan, exact confirmation |
vpn_verify | No | Allowlisted target |
vpn_rollback | Yes, remote | allowMutations, backup id, exact confirmation |
vpn_export_client | Yes, local secret files | allowSecretExport, exact confirmation |
Target prerequisites
The first release intentionally does not install operating-system packages or
download Xray. Supply-chain policy remains with the server operator.
The target must be Debian or Ubuntu with systemd and these commands already
available:
base64 flock install ip iptables jq mktemp openssl sha256sum ss sysctl systemctl
uuidgen wg wg-quick xray
The configured xrayBinary may point to a non-PATH installation. The SSH user
must be root, or sudo: true must provide non-interactive root authority.
Treat either credential as root-equivalent and keep it dedicated.
Before deployment, verify that:
- UDP
wireguardListenPort and TCP vlessPort are allowed by the provider and
host firewalls.
publicInterface is the actual egress interface.- The REALITY
realityDestination and realityServerName are suitable and
under an acceptable abuse policy. Unauthenticated REALITY traffic is
forwarded to the target; see the Xray documentation warning.
- Xray accepts
network: "raw", the target REALITY field, and
xtls-rprx-vision in a dry-run configuration test.
- The operator has an independent recovery channel such as a cloud serial
console.
Install
GitHub release
Install a tagged release into an existing DSH profile:
dsh plugin --profile my-profile add github:zootguru/dsh-vpn-ops#v0.1.0
The repository commits built lib/ artifacts, so a Git install does not run a
build lifecycle hook.
Local, reproducible tarball
pnpm install --frozen-lockfile
pnpm verify
pnpm pack --pack-destination ./artifacts
dsh plugin --profile my-profile add ./artifacts/dsh-vpn-ops-0.1.0.tgz
Configure
The bundle installs a disabled vpn-ops row. Override that row in the profile's
user cordis.patch.yml:
- id: vpn-ops
config:
# Keep false until a reviewed vpn_plan is ready to execute.
allowMutations: false
# Enable only for an operator-approved client export session.
allowSecretExport: false
stateDirectory: /Users/operator/.local/state/dsh-vpn-ops
connectTimeoutSeconds: 10
commandTimeoutMs: 120000
maxOutputBytes: 65536
planTtlSeconds: 900
targets:
- id: la-edge
host: vpn.example.net
user: root
sshPort: 22
identityFile: /Users/operator/.ssh/dsh-vpn-ops_ed25519
knownHostsFile: /Users/operator/.ssh/dsh-vpn-ops_known_hosts
sudo: false
publicEndpoint: vpn.example.net
publicInterface: eth0
remoteStateDirectory: /var/lib/dsh-vpn-ops
wireguardInterface: wg0
wireguardAddress: 10.66.66.1/24
wireguardListenPort: 51820
wireguardConfigPath: /etc/wireguard/wg0.conf
wireguardService: wg-quick@wg0
clientDns: 1.1.1.1
clientMtu: 1420
vlessListenAddress: 0.0.0.0
vlessPort: 443
realityServerName: www.example.com
realityDestination: www.example.com:443
xrayBinary: /usr/local/bin/xray
xrayConfigPath: /usr/local/etc/xray/config.json
xrayService: xray
sysctlConfigPath: /etc/sysctl.d/99-dsh-vpn-ops.conf
clients:
- id: laptop
wireguardAddress: 10.66.66.2/32
- id: phone
wireguardAddress: 10.66.66.3/32
identityFile must be a regular file inaccessible to group and others.
knownHostsFile must be non-empty. Obtain the host key through the provider or
another authenticated channel; do not trust an unverified ssh-keyscan result.
No example contains a real server address, UUID, private key, or client config.
Operate
Use this order:
vpn_targetsvpn_preflight({ targetId: "la-edge" })vpn_status({ targetId: "la-edge" })vpn_plan({ targetId: "la-edge" })- Review every change, the baseline deployment id, and the managed-state
fingerprint. Any managed-file or service-state drift invalidates the plan.
- Set
allowMutations: true, let DSH reload the plugin, and call vpn_apply
with the exact plan id and confirmation returned in step 4.
- Read the returned backup id and verification result. A missing first
handshake is informational; invalid configuration, inactive services, or
closed listeners makes verification fail.
- Set
allowMutations: false again.
To export a configured client, temporarily enable allowSecretExport, obtain
explicit operator approval for EXPORT <targetId> <clientId>, call
vpn_export_client, move the generated files into an approved secret channel,
then disable export and remove the local copies when no longer needed.
Rollback requires the exact backupId and confirmation
ROLLBACK <targetId> <backupId>.
What apply manages
- WireGuard server and per-client X25519 keys.
- VLESS UUIDs and REALITY key material.
- WireGuard server configuration and client profiles.
- Xray VLESS + REALITY inbound configuration.
- IPv4 forwarding sysctl configuration.
- Service enable/restart for the configured WireGuard and Xray units.
- Per-apply backups and a current deployment marker under
remoteStateDirectory.
Keys are generated on the target and remain under
remoteStateDirectory/secrets with restrictive permissions. Existing managed
keys are reused so repeated applies do not silently invalidate clients.
Compatibility
| Component | Verified contract |
|---|
| DeepSeek Harness | 0.1.1-rc.2 |
@deepseek-ai/dsh-tools | 0.1.1-rc.2 exact peer |
@deepseek-ai/cordis | 4.0.1 exact peer |
| Node.js | ^22.19.0 or >=24.0.0 |
| Remote OS | Debian / Ubuntu with systemd |
| Xray configuration | Current target, password, and raw terminology; runtime preflight and dry-run required |
DSH is a developer preview and may make breaking changes. Compatibility is an
evidence statement, not a broad semver promise. The exact clean-profile
procedure and results live in Verification.
Limitations
- No package installation, firewall-provider API, DNS update, cloud console, or
certificate management.
- IPv4 WireGuard topology only; no IPv6 forwarding.
- Full-tunnel clients only (
AllowedIPs = 0.0.0.0/0).
- One WireGuard interface and one VLESS Reality inbound per target.
- Service health and local listeners are verified; an end-to-end test from an
independent external network remains the operator's responsibility.
- Client export writes secret material to the DSH host. The plugin does not send
it to email, chat, cloud storage, or the model.
- Rollback covers managed configuration, client artifacts, sysctl, and prior
service activity. It cannot reverse external firewall, provider, DNS, or
routing changes because it never performs them.
Uninstall
Disable mutations, remove the bundle, and inspect the target manually before
deleting remote state:
dsh plugin --profile my-profile remove dsh-vpn-ops
Uninstall intentionally does not delete remote configuration, keys, backups, or
client files.
Development and evidence
pnpm install --frozen-lockfile
pnpm test:coverage
pnpm verify
The repository publishes:
License
MIT
