dsh-ankh-guard DSH plugin

dsh-ankh-guard is a guard plugin for DSH that enforces a credential-based gate before agent-initiated restarts. It requires the agent to first prove that code changes pass build and tests, then records a credential tied to the current git commit. The plugin also provides a watchdog system for supervised restarts with checkpoint/rollback, canary checks, and automatic restart context reporting to the agent.

developer-tools security-policy

How to install the dsh-ankh-guard DSH plugin

dsh plugin --profile web add @khorsheed/dsh-ankh-guard

Copying does not run this command. Review the repository and version before installing the dsh-ankh-guard DSH plugin.

dsh-ankh-guard DSH plugin data source

dsh-ankh-guard DSH plugin snapshot date: Aug 16, 2026

discovered

What the dsh-ankh-guard DSH plugin can do

Verifies build and test credentials before allowing restart; rejects if missing, expired, or HEAD mismatch
Records a credential after successful build and tests, bound to current git commit with configurable maxAgeMinutes
Provides checkpoint and rollback to snapshots of the entire working tree
Canary checks after restart to confirm the new instance is healthy
Watchdog supervision: detached process that monitors port, automatically restarts instance, and rolls back on failure
Restart context reporting via agent.followup or step, ensuring the agent knows the restart outcome
Supports both manual restart and schedule-exit with detached watchdog for unsupervised recovery
Configurable state directory, repo directory, credential freshness window, reporting mode, and fallback grace period

Where the dsh-ankh-guard DSH plugin fits

Agent modifies its own code and wants to restart the host; the plugin ensures the modifications are safe before restart
Developer wants to enable self-healing agents that can fix bugs and restart without manual intervention
Deploying a DSH-based service that needs crash-proof self-modification with rollback on failure
Running canary tests after restart to catch regression early
Integrating with systemd/launchd for layered supervision: watchdog supervises instance, external supervisor supervises watchdog

Who the dsh-ankh-guard DSH plugin is for

DSH users who develop agents that modify their own code at runtime
Operators of DSH web instances that want to allow self-modifying restarts with safety guarantees

dsh-ankh-guard DSH plugin limitations

Gate is only enforced in the restart/supervise commands, not in the launcher; manual kill/start can bypass
Watchdog requires a supervisor that outlives the instance; detached mode must be adopted before exit
Checkpoint commits include the entire working tree, potentially including unrelated uncommitted changes
restart/supervise uses lsof to discover listeners (macOS/Linux with lsof); other platforms need --pid
A/B partition switching is not in scope; production slot switching is separate

dsh-ankh-guard DSH plugin: from the repository README

Quoted from the Khorsheed/dsh-ankh-guard README, the upstream source of the dsh-ankh-guard DSH plugin. Copyright remains with the original authors.

让 agent 自己改代码、自己重启，还不把服务搞挂。 agent 改完代码想重启的时候，这个插件会先问一句：这次改动，构建和测试都过了吗？过了才放行，没过就拦下来——免得改坏的代码把整个服务、连同正在进行的对话一起带走。 ![重启闭环演示](assets/restart-loop-demo.png) 一次真实的自我重启：agent 重启前先告知验证计划（1)；宿主退出，进行中的 tool call 被安全中断并落盘（2);watchdog 在 10 秒内拉回实例，ankh-guard 把重启上下文注入原会话（3)——agent 醒来后继续执行重启前宣布的验证，用户全程无感知。 ## 工作原理核心就一条规则：**先证明代码是好的，才允许重启。** 构建和测试全绿后，插件记录一个凭证，绑定当时的 git commit，并带 10 分钟有效期（`maxAgeMinutes`）。要重启时检查三点： 1. 有没有凭证； 2. 凭证超没超过 `maxAgeMinutes`； 3. 当前 HEAD 和记录凭证时的 commit 一不一致——记录之后任何改动都会让凭证失效。这条规则能拦住一整类事故：改坏了构建、漏注册配置、导错模块——这些全都会让构建/类型检查失败，于是没有凭证，重启在造成伤害之前就被拒绝。重启本身交给 watchdog 托管：独立的监督进程，宿主死了自动拉起来，起不来就回滚到检查点，连续四次失败停在崩溃页等人工处理。`checkpoint` 在批次前把整个工作树提交为回滚点，`reset` 硬重置回该点，`canary` 在重启后复检。检查点与凭证存在状态文件里，重启后依然存活，所以 canary 可以在新实例起来之后运行。 ## 安装与加载本包是 dsh 插件：守护运行中的 dsh web 实例，防止坏掉的自我修改重启。不自带宿主——先准备 dsh 宿主（`npx @deepseek-ai/dsh web`)。宿主兼容性：dsh `0.0.1-rc.5+` 或 `0.1.0-rc.5+`(npm 上任何当前版本均可）。一条命令安装到 profile 并作为补丁层激活（本包声明了 `dsh.bundle`,add 会同时写入依赖并挂载插件；重复执行安全，按包名去重）: ```sh dsh plugin --profile web add @khorsheed/dsh-ankh-guard ``` 或从 GitHub 安装（安装时经 `prepare` 自动构建）: ```sh dsh plugin --profile web add github:Khorsheed/dsh-ankh-guard ``` 装完重启宿主。注意：如果你的 profile 已经通过其他 bundle 组合了 ankh-guard，请不要

Read the full READMERepository license: MIT

dsh-ankh-guard DSH plugin questions

How do I install dsh-ankh-guard?

Install it with the DSH plugin command: `dsh plugin --profile web add @khorsheed/dsh-ankh-guard`. You can also install from GitHub: `dsh plugin --profile web add github:Khorsheed/dsh-ankh-guard`. Make sure you have a DSH host running (e.g., `npx @deepseek-ai/dsh web`). The plugin requires dsh `0.0.1-rc.5+` or `0.1.0-rc.5+`.

What happens if the build or tests fail?

The plugin will not record a credential. When the agent tries to restart, the `verify` command will fail because there is no valid credential. The restart is rejected, preventing the broken code from taking down the service. The agent must fix the build or tests, re-record, and then can restart.

Does the plugin work on Windows?

The plugin depends on `lsof` for discovering listeners on macOS and Linux. For other platforms, you need to specify the PID explicitly with `--pid` when using `restart` or `supervise`. The core functionality should work on any platform that supports Node.js and bash, but Windows is not officially tested.

How do I configure the credential freshness window?

Set `maxAgeMinutes` in the plugin configuration. The default is 10 minutes. For example, in a custom profile YAML: `- id: ankh-guard name: '@khorsheed/dsh-ankh-guard' config: maxAgeMinutes: 30`. This determines how long a recorded credential remains valid before it expires.

What is the difference between restart and schedule-exit?

`restart` runs the full restart cycle within a single CLI process (kill, start, probe, canary). It's suitable when you don't need a detached watchdog. `schedule-exit` writes a restart marker and spawns a detached exit agent, which triggers the watchdog to restart the instance. Use `schedule-exit` when you want unsupervised recovery and the watchdog to handle the restart, including canary checks and rollback on failure.