@exagone313/dsh-podman 0.2.0-rc.3 → 0.2.0

package/docs/install-dsh-and-dsh-podman.zh.md

@@ -10,10 +10,13 @@ SPDX-License-Identifier: MIT
 
 本指南的目标是安装：
 
-- [DeepSeek Harness](https://deepseek.com/harness)，下文简称 _dsh_
+- [DeepSeek Harness](https://deepseek.com/harness)，下文简称 _dsh_，在它自己的
+  Podman 容器中运行
 - dsh 中的 dsh-podman 插件，它取代了宿主的文件系统和 shell 访问
 - dsh-podman 编排器，一个与 Podman 集成的独立 Podman 容器
 
+请注意，如果 `~/.dsh` 中已有安装数据，它将被复用。
+
 将 dsh 插件和编排器作为独立的容器运行，是 dsh-podman 安全设计的重要一环： dsh
 本身不能直接访问 Podman，只有编排器可以，并且受到限制。dsh
 不应能通过这条路径提权，因为提供给 dsh 的权限能力是受限的：
@@ -77,12 +80,12 @@ SPDX-License-Identifier: MIT
 
 ## 安装
 
-### dsh 配置
-
 本次安装使用
 [Podman Quadlet](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html)，
 它为 systemd 增加了 Podman 集成。
 
+注意，dsh-podman 插件会在 dsh 容器启动时安装，这需要联网。
+
 1. 为你的用户创建 Quadlet 目录：
    ```bash
    mkdir -p ~/.config/containers/systemd
@@ -90,6 +93,9 @@ SPDX-License-Identifier: MIT
 2. 将文件 [dsh.container](../quadlet/dsh.container) 和
    [dsh-podman-orchestrator.container](../quadlet/dsh-podman-orchestrator.container)
    复制到 `~/.config/containers/systemd/`。
+   ```bash
+   cp quadlet/* ~/.config/containers/systemd/
+   ```
    - 如果你希望更改项目目录，可相应调整这些文件。
 3. 重新加载 systemd 会话配置：
    ```bash
@@ -118,28 +124,21 @@ SPDX-License-Identifier: MIT
 9. 浏览器保存该令牌后，即可通过 [http://127.0.0.1:3080/](http://127.0.0.1:3080/)
    访问 dsh。
 
-### dsh-podman 插件安装
-
-1. 运行以下命令安装 dsh-podman 插件：
-   ```bash
-   podman exec dsh dsh plugin --profile web add @exagone313/dsh-podman --allow-build=protobufjs
-   ```
-2. 重启 dsh 以完成安装：
-   ```bash
-   systemctl --user restart dsh
-   ```
-
 ## 验证
 
-- 打开 **Settings → Plugins →
-  dsh-podman**：卡片应列出基础镜像，并针对工作区提供创建其默认容器的选项。
+- 打开侧边栏的 **插件** 面板 → **已安装** →
+  **dsh-podman**：页面应列出基础镜像，并针对工作区提供创建其默认容器的选项。
 - 在 dsh 会话中运行一条 shell 命令。它应在当前工作区的 Podman
   容器内执行（插件会在首次使用时自动创建工作区的默认容器）。
 
-## 启用每日自动更新（可选）
+## 配置 Git 身份（推荐）
+
+- 打开侧边栏的 **插件** 面板 → **已安装** → **dsh-podman**
+- 向下滚动到 **默认环境**
+- 点击 **Git 身份**
+- 输入用于 Git 的名称和邮箱，然后点击 **应用**
+- 点击 **应用默认环境变量**，然后点击 **确认**
 
-这需要为你的用户启用 lingering。
+## 更新 dsh 与 dsh-podman
 
-```bash
-systemctl --user enable --now podman-auto-update.timer
-```
+请阅读[更新文档](./update.zh.md)，了解如何手动更新或设置自动更新。

package/docs/uninstall.md

@@ -0,0 +1,83 @@
+<!--
+SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+
+SPDX-License-Identifier: MIT
+-->
+
+# Uninstall
+
+This page undoes the [installation guide](install-dsh-and-dsh-podman.md): it
+assumes dsh runs from the dsh-podman image with the orchestrator, both started
+from Quadlet units.
+
+The dsh image installs the dsh-podman plugin at container start, and the
+plugin's bundle layer is what disables dsh's own `subprocess`, `fs-sandbox`,
+`spill-local` and built-in Terminal UI (`ui-sidebar-terminal`) plugins.
+Uninstalling therefore also means running dsh without dsh-podman: its built-in
+shell and filesystem tools are active again, and they run **on the host** as the
+dsh user, with no container isolation.
+
+## Stop the containers and remove the Quadlet units
+
+```bash
+systemctl --user stop dsh dsh-podman-orchestrator
+rm ~/.config/containers/systemd/dsh.container
+rm ~/.config/containers/systemd/dsh-podman-orchestrator.container
+systemctl --user daemon-reload
+```
+
+## Then choose one of the two following options
+
+These are alternatives, not steps: pick the one that matches what you want to
+keep.
+
+### Remove dsh entirely
+
+```bash
+podman unshare rm -rf ~/.dsh
+```
+
+`~/.dsh` is the whole harness home: the profiles (including the installed
+plugin), the settings, and the orchestrator's state and package caches. The
+orchestrator runs as root, so parts of that directory belong to the container's
+root and only `podman unshare` can remove them, from the user namespace.
+
+### Keep dsh without dsh-podman
+
+Run dsh directly instead of from the image — as the harness documents, with
+`npx @deepseek-ai/dsh web` — after removing the plugin from the profile, so dsh
+stops loading it and its built-in plugins are active again:
+
+```bash
+npx @deepseek-ai/dsh plugin --profile web remove @exagone313/dsh-podman
+npx @deepseek-ai/dsh web
+```
+
+Then archive the sessions that used the podman tools, from the session's menu
+(**Archive session**): those tools no longer exist without dsh-podman, so
+resuming such a session would leave the model calling tools that are gone.
+
+The orchestrator's leftover state and package caches can be removed too. They
+belong to the container's root, so remove them from the user namespace:
+
+```bash
+podman unshare rm -rf ~/.dsh/dsh-podman
+```
+
+## Remove the Podman resources (optional)
+
+The orchestrator creates one pod per dsh workspace, plus named volumes and
+secrets, and builds images. Removing them only reclaims disk space; project
+directories are bind mounts and are never touched.
+
+```bash
+# Workspace pods and their containers, one per dsh workspace
+podman pod ls --format '{{.Name}}' | grep '^dsh-podman-' | xargs -r podman pod rm -f
+
+# Named volumes and secrets the orchestrator created
+podman volume ls --format '{{.Name}}' | grep '^dsh-podman-' | xargs -r podman volume rm
+podman secret ls --format '{{.Name}}' | grep '^dsh-podman-' | xargs -r podman secret rm
+
+# Built workspace images, the base images, and the dsh-podman images themselves
+podman images --format '{{.Repository}}:{{.Tag}}' | grep 'dsh-podman/' | xargs -r podman rmi
+```

package/docs/uninstall.zh.md

@@ -0,0 +1,79 @@
+<!--
+SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+
+SPDX-License-Identifier: MIT
+-->
+
+# 卸载
+
+本页用于撤销[安装指南](install-dsh-and-dsh-podman.zh.md)中的操作：其中假设 dsh
+运行在 dsh-podman 镜像中，并与编排器一同由 Quadlet 单元启动。
+
+dsh 镜像会在容器启动时安装 dsh-podman 插件，而该插件的 bundle 层正是禁用 dsh
+自带的 `subprocess`、`fs-sandbox`、`spill-local`
+与内置终端界面（`ui-sidebar-terminal`） 插件的原因。因此，卸载也意味着不再使用
+dsh-podman 运行 dsh：其内置的 shell 与文件系统工具会重新启用，并以 dsh
+用户的身份**在主机上**运行，不再有容器隔离。
+
+## 停止容器并移除 Quadlet 单元
+
+```bash
+systemctl --user stop dsh dsh-podman-orchestrator
+rm ~/.config/containers/systemd/dsh.container
+rm ~/.config/containers/systemd/dsh-podman-orchestrator.container
+systemctl --user daemon-reload
+```
+
+## 然后在以下两个选项中选择一个
+
+这两个选项是并列的，而不是先后步骤：请根据你想保留的内容选择其一。
+
+### 完全删除 dsh
+
+```bash
+podman unshare rm -rf ~/.dsh
+```
+
+`~/.dsh` 是整个 harness 主目录：包含各个
+profile（其中有已安装的插件）、设置，以及编排器的状态与软件包缓存。编排器以 root
+运行，因此该目录中部分文件属于容器内的 root，只能在用户命名空间（user
+namespace）中用 `podman unshare` 删除。
+
+### 保留 dsh 但不使用 dsh-podman
+
+改为直接运行 dsh，而不是从镜像运行——如 harness 文档所述，使用
+`npx @deepseek-ai/dsh web`——在此之前先从 profile 中移除插件，这样 dsh
+便不再加载它，其内置插件也会重新启用：
+
+```bash
+npx @deepseek-ai/dsh plugin --profile web remove @exagone313/dsh-podman
+npx @deepseek-ai/dsh web
+```
+
+然后归档曾使用 podman 工具的会话，从会话菜单中选择**归档会话**（Archive
+session）：没有 dsh-podman
+之后这些工具已不存在，继续恢复此类会话会让模型调用已消失的工具。
+
+编排器残留的状态与软件包缓存也可以删除。它们属于容器内的
+root，因此请在用户命名空间中删除：
+
+```bash
+podman unshare rm -rf ~/.dsh/dsh-podman
+```
+
+## 删除 Podman 资源（可选）
+
+编排器会为每个 dsh 工作区创建一个
+pod，并创建命名卷与机密，还会构建镜像。删除它们只是回收磁盘空间；项目目录是绑定挂载，绝不会被改动。
+
+```bash
+# 工作区 pod 及其容器，每个 dsh 工作区一个
+podman pod ls --format '{{.Name}}' | grep '^dsh-podman-' | xargs -r podman pod rm -f
+
+# 编排器创建的命名卷与机密
+podman volume ls --format '{{.Name}}' | grep '^dsh-podman-' | xargs -r podman volume rm
+podman secret ls --format '{{.Name}}' | grep '^dsh-podman-' | xargs -r podman secret rm
+
+# 构建的工作区镜像、基础镜像，以及 dsh-podman 自身的镜像
+podman images --format '{{.Repository}}:{{.Tag}}' | grep 'dsh-podman/' | xargs -r podman rmi
+```

package/docs/update.md

@@ -0,0 +1,120 @@
+<!--
+SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+
+SPDX-License-Identifier: MIT
+-->
+
+# Update
+
+You should run updates only when no agents are running.
+
+Existing guest containers will be recreated afterwards, so running processes and
+daemons will be killed.
+
+Note that the corresponding dsh-podman plugin will be installed from npm at
+startup.
+
+When enabling auto-updates, it is possible to skip updates while an agent is
+running. Read further to set this up.
+
+## Update manually
+
+Pull the new images:
+
+```bash
+podman pull ghcr.io/exagone313/dsh-podman/dsh:1 ghcr.io/exagone313/dsh-podman/orchestrator:1
+```
+
+Restart dsh and dsh-podman-orchestrator:
+
+```bash
+systemctl --user restart dsh dsh-podman-orchestrator
+```
+
+## Upgrade to a new major version
+
+Currently, dsh-podman major version is 1. To upgrade to major version 2 and
+above, check the
+[release notes](https://github.com/Exagone313/dsh-podman/releases).
+
+## Enable auto-updates
+
+The quadlet configuration for dsh and dsh-podman-orchestrator enables
+auto-update of images (`AutoUpdate=registry`). The `podman-auto-update` systemd
+timer needs to be enabled for this to work:
+
+```bash
+systemctl --user enable --now podman-auto-update.timer
+```
+
+Also, make sure user lingering is enabled for your user (as root):
+
+```bash
+loginctl enable-linger your-username
+```
+
+Each time the timer runs, the Podman auto-update tool tries to pull newer
+versions of the images. If new versions are pulled, the corresponding containers
+will be recreated.
+
+By default, this timer runs once per day, around midnight.
+
+## Change when auto-updates happen
+
+You can override the time when the timer runs.
+
+Create the directory that contains user overrides for the `podman-auto-update`
+systemd timer:
+
+```bash
+mkdir -p ~/.config/systemd/user/podman-auto-update.timer.d
+```
+
+Copy the drop-in
+[`podman-auto-update.timer.conf`](../systemd-dropins/podman-auto-update.timer.conf)
+into the directory and edit its content according to your needs.
+
+```bash
+cp systemd-dropins/podman-auto-update.timer.conf ~/.config/systemd/user/podman-auto-update.timer.d/
+```
+
+Reload systemd configuration and restart the timer:
+
+```bash
+systemctl --user daemon-reload
+systemctl --user restart podman-auto-update.timer
+```
+
+You can verify when the timer will run next with:
+
+```bash
+systemctl --user list-timers
+```
+
+The same drop-in file can be edited to run updates multiple times a day.
+
+## Skip updates while an agent is running
+
+An update restarts the dsh container, which interrupts any agent turn in flight.
+It is possible to skip updates when an agent is running.
+
+Create the directory that contains user overrides for the `podman-auto-update`
+systemd service (it is not the same directory as the timer):
+
+```bash
+mkdir -p ~/.config/systemd/user/podman-auto-update.service.d
+```
+
+Copy the drop-in
+[`podman-auto-update-skip-when-busy.conf`](../systemd-dropins/podman-auto-update-skip-when-busy.conf)
+into the directory.
+
+```bash
+cp systemd-dropins/podman-auto-update-skip-when-busy.conf ~/.config/systemd/user/podman-auto-update.service.d/
+```
+
+Reload systemd configuration:
+
+```bash
+systemctl --user daemon-reload
+```

package/docs/update.zh.md

@@ -0,0 +1,114 @@
+<!--
+SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+
+SPDX-License-Identifier: MIT
+-->
+
+# 更新
+
+只应在没有 agent 运行时进行更新。
+
+现有的 guest 容器随后会被重建，因此运行中的进程和守护进程会被终止。
+
+请注意，对应的 dsh-podman 插件会在启动时从 npm 安装。
+
+启用自动更新后，也可以在 agent 运行时跳过更新。请继续阅读以了解如何设置。
+
+## 手动更新
+
+拉取新镜像：
+
+```bash
+podman pull ghcr.io/exagone313/dsh-podman/dsh:1 ghcr.io/exagone313/dsh-podman/orchestrator:1
+```
+
+重启 dsh 和 dsh-podman-orchestrator：
+
+```bash
+systemctl --user restart dsh dsh-podman-orchestrator
+```
+
+## 升级到新的主版本
+
+目前，dsh-podman 的主版本是 1。要升级到主版本 2 及以上，请查看
+[发布说明](https://github.com/Exagone313/dsh-podman/releases)。
+
+## 启用自动更新
+
+dsh 和 dsh-podman-orchestrator 的 quadlet 配置启用了镜像自动更新
+（`AutoUpdate=registry`）。要使其生效，需要启用 `podman-auto-update` systemd
+计时器：
+
+```bash
+systemctl --user enable --now podman-auto-update.timer
+```
+
+另外，请确保已为你的用户启用 user lingering（常驻）（以 root 身份）：
+
+```bash
+loginctl enable-linger your-username
+```
+
+每次计时器运行时，Podman 自动更新工具都会尝试拉取镜像的新版本。如果拉取到了
+新版本，相应的容器将被重建。
+
+默认情况下，该计时器每天运行一次，大约在午夜。
+
+## 更改自动更新的时间
+
+你可以覆盖计时器的运行时间。
+
+创建包含 `podman-auto-update` systemd 计时器用户覆盖文件的目录：
+
+```bash
+mkdir -p ~/.config/systemd/user/podman-auto-update.timer.d
+```
+
+把
+[`podman-auto-update.timer.conf`](../systemd-dropins/podman-auto-update.timer.conf)
+这个 drop-in（覆盖）文件复制到该目录中，并根据需要编辑其内容。
+
+```bash
+cp systemd-dropins/podman-auto-update.timer.conf ~/.config/systemd/user/podman-auto-update.timer.d/
+```
+
+重新加载 systemd 配置并重启计时器：
+
+```bash
+systemctl --user daemon-reload
+systemctl --user restart podman-auto-update.timer
+```
+
+你可以用以下命令验证计时器下次运行的时间：
+
+```bash
+systemctl --user list-timers
+```
+
+同一个 drop-in 文件也可以编辑成每天多次运行更新。
+
+## 在 agent 运行时跳过更新
+
+更新会重启 dsh 容器，这会中断任何正在进行的 agent 回合。可以在 agent 运行时
+跳过更新。
+
+创建包含 `podman-auto-update` systemd 服务用户覆盖文件的目录（注意：它和
+计时器的目录不是同一个）：
+
+```bash
+mkdir -p ~/.config/systemd/user/podman-auto-update.service.d
+```
+
+把
+[`podman-auto-update-skip-when-busy.conf`](../systemd-dropins/podman-auto-update-skip-when-busy.conf)
+这个 drop-in（覆盖）文件复制到该目录中。
+
+```bash
+cp systemd-dropins/podman-auto-update-skip-when-busy.conf ~/.config/systemd/user/podman-auto-update.service.d/
+```
+
+重新加载 systemd 配置：
+
+```bash
+systemctl --user daemon-reload
+```