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

package/docs/development.zh.md

@@ -19,7 +19,8 @@ SPDX-License-Identifier: MIT
 
 ## 构建
 
-前置要求：Go 1.27、Node ≥ 22、pnpm 12，以及（浏览器端所需的）发布在 npm 上的
+前置要求：Go 1.27、Node ≥ 22、pnpm 12、Deno ≥
+2.9（用于格式化），以及（浏览器端所需的）发布在 npm 上的
 `@deepseek-ai/dsh-client-*` 包。
 
 ```sh
@@ -35,19 +36,22 @@ Go 构建标签会跳过 btrfs 和 devicemapper 存储驱动，它们需要宿
 ```sh
 make build-go       # build both Go binaries into bin/<os>-<arch>/
 make build          # build-go + pnpm-build
-make vet            # go vet with the build tags
+make vet            # gofmt -s check + go vet with the build tags
 make test-go        # go test with the build tags
 make test           # test-go + pnpm test (JS tests, which run against dist/)
-make download-licenses  # generate LICENSE.pkg from the project and third-party Go licenses
-make image          # build the orchestrator and guest-agent container images
+make fmt            # gofmt -s + deno fmt (TypeScript and Markdown)
+make fmt-check      # verify the formatting without rewriting anything
+make download-licenses  # generate third-party-licenses.pkg from the project and third-party Go licenses
+make image          # build the orchestrator, guest-agent and dsh container images
 ```
 
-`make image` 依赖 `LICENSE.pkg`：`download-licenses` 目标会运行
+`make image` 依赖 `third-party-licenses.pkg`：`download-licenses` 目标会运行
 `scripts/download-licenses` 中的 Go 收集器，它调用 `go-licenses save` 并将项目的
-MIT 许可证以及所有第三方 Go 许可证和 Apache `NOTICE` 汇总到 `LICENSE.pkg`
-中。该文件被 gitignore （从不提交），并被烘焙进 orchestrator 和 guest-agent
-镜像，位于 `/usr/share/licenses/dsh-podman/LICENSE`；由于工作区容器会挂载
-guest-agent 镜像，因此它也会随之进入每个工作区容器。
+MIT 许可证以及所有第三方 Go 许可证和 Apache `NOTICE` 汇总到
+`third-party-licenses.pkg` 中。该文件被 gitignore （从不提交），并被烘焙进
+orchestrator 和 guest-agent 镜像，位于
+`/usr/share/licenses/dsh-podman/LICENSE`；由于工作区容器会挂载 guest-agent
+镜像，因此它也会随之进入每个工作区容器。
 
 `pnpm test` 运行 `node --test dist/*.test.js`，因此它要求先运行 `pnpm build`
 （`test` 目标会处理这一点）。
@@ -64,6 +68,17 @@ JS 端在运行时通过 `@grpc/proto-loader` 加载原始 `.proto` 文件（构
 `dist/grpc/proto/`）；不生成 TypeScript 绑定。也可以使用 `buf lint` 和
 `buf breaking` 校验 schema。
 
+## 命名
+
+`.proto` 字段名为 `lower_snake_case`（Buf 的 `BASIC` lint 会强制检查），JS
+端通过 proto-loader 的 camelCase 投影读取，因此 `secret_env` 变为
+`secretEnv`、`image_id` 变为 `imageId`。切勿在 TypeScript 中使用下划线形式的
+proto 字段名：proto-loader 会忽略未知属性，该值会被静默丢弃。
+
+工具参数使用 camelCase，只有刻意与 harness
+内置工具保持一致的名字除外（`file_path`、`old_string`、`new_string`、`replace_all`）。设置项使用
+camelCase；持久化的 TOML 状态使用下划线标签。
+
 ## 安装开发构建
 
 ### 构建
@@ -73,16 +88,109 @@ make  # builds plugin and go binaries
 make image  # build images
 ```
 
-### 重建容器
+### 运行本地镜像（Quadlet）
+
+随附的单元会拉取发布镜像。把它们指向 `make image`
+构建的镜像，就能把本地构建当作正式服务来运行；把原来的行注释掉，切回时只需改一行。
+
+在 `~/.config/containers/systemd/dsh.container` 中：
+
+```ini
+#Image=ghcr.io/exagone313/dsh-podman/dsh:1
+Image=localhost/dsh-podman-dsh:latest
+Environment=DSH_PODMAN_PLUGIN_SOURCE=%h/project/dsh-podman
+```
+
+该单元已经把 `%h/project` 以只读方式挂载，因此检出在 `~/project`
+下的仓库无需额外的 `Volume=`。`npm pack` 会把入口脚本要安装的归档放在
+`package.json` 旁边（见[安装本地插件构建](#安装本地插件构建)）。
+
+在 `~/.config/containers/systemd/dsh-podman-orchestrator.container` 中：
+
+```ini
+#Image=ghcr.io/exagone313/dsh-podman/orchestrator:1
+Image=localhost/dsh-podman-orchestrator:latest
+#Environment=DSH_PODMAN_GUEST_AGENT_IMAGE=ghcr.io/exagone313/dsh-podman/guest-agent
+#Environment=DSH_PODMAN_GUEST_AGENT_IMAGE_USE_VERSION_TAG=true
+Environment=DSH_PODMAN_GUEST_AGENT_IMAGE=localhost/dsh-podman-guest-agent:latest
+```
+
+发布引用带有版本标签，因此每个发布版本都有各自不同的镜像引用。本地构建则复用同一个
+`:latest` 标签；orchestrator 因此无法察觉 guest agent
+已被重建，详见[更新工作区容器](#更新工作区容器)。
+
+编辑单元后重新加载 systemd：
 
 ```bash
+systemctl --user daemon-reload
+```
+
+### 部署改动
+
+```bash
+make            # Go binaries + the plugin bundle
+make image      # orchestrator, guest-agent and dsh images
+npm pack        # the plugin archive the dsh entrypoint installs
 systemctl --user restart dsh dsh-podman-orchestrator
 ```
 
+dsh 镜像会在容器启动时安装插件，因此重启 dsh 才会重新安装刚打包的归档；重启
+orchestrator 则会采用新的 orchestrator 与 guest-agent 镜像。
+
+### 更新工作区容器
+
+guest-agent 镜像会在容器创建时挂载进去，因此正在运行的容器仍使用它启动时的那份
+agent。只有当容器的 guest-agent 镜像引用与当前配置不一致时，orchestrator
+才会自行重建该容器——带版本标签的发布引用会如此，本地 `:latest` 标签则不会。重建
+guest agent 之后，请自行重建容器：
+
+- 在 Podman 页面（侧边栏 **插件** 面板 → **已安装** →
+  **dsh-podman**）中按容器操作：**Recreate**（沿用当前镜像）或 **Recreate with
+  image**；
+- 或使用 `container_recreate`，作用于命名容器或默认容器。
+
+若要重建整个工作区，可在其行上使用 **Remove pod**（或 `RemoveWorkspace`）：pod
+及其所有容器都会被移除，下次接入时会重新创建 pod
+与默认容器。重启这两个服务绝不会触及工作区容器，上述两种操作也都不会删除卷、机密或项目数据。
+
+仍在运行旧镜像中 guest agent 的容器会让 dsh 为其 guest 套接字记录
+`rejected by server because of excess pings`。该消息无害（grpc-js
+会退避并重连），重建该容器后即消失；若同样的消息出现在 `orchestrator.sock`
+上，则说明 orchestrator 服务仍在运行上一个镜像。
+
+### 开发容器工具链
+
+工作区容器的根文件系统是只读且一次性的，因此贡献者构建所用的工具链需要工作区的一个卷。项目并不分发开发镜像：请自行构建一个自定义镜像——[设置提示词](development-prompt.zh.md)
+会以 `archlinux` 为父镜像构建 `dsh-podman-tooling`，包含
+`go`、`nodejs-lts-jod`、`npm`、`deno`、`reuse` 和
+`python-chardet`——并为镜像无法保存的状态创建工作区卷：Go 与 npm 缓存、含
+`go install` 工具的 `gopath`， 以及 `package.json` 固定版本、Arch 仓库没有的
+pnpm。
+
+提示词会把该卷以 `dsh-podman-toolchain` 挂载到
+`/opt/toolchain`（读写），并让容器的缓存都指向它，因此无需 source
+任何脚本即可使用：
+
+| 容器设置    | 值                                                                                                                                                                                                                                                                                                                         |
+| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| PATH 追加项 | `/opt/toolchain/gopath/bin`、`/opt/toolchain/npm-global/bin`、`/opt/toolchain/pnpm-home`                                                                                                                                                                                                                                   |
+| 环境变量    | `GOCACHE=/opt/toolchain/gocache`、`GOMODCACHE=/opt/toolchain/gomodcache`、`GOPATH=/opt/toolchain/gopath`、`npm_config_cache=/opt/toolchain/npm-cache`、`npm_config_prefix=/opt/toolchain/npm-global`、`PNPM_HOME=/opt/toolchain/pnpm-home`、`DENO_DIR=/opt/toolchain/deno-dir`、`GOENV=/opt/toolchain/home/.config/go/env` |
+
+在 Podman 页面（侧边栏 **插件** 面板 → **已安装** →
+**dsh-podman**）的[默认环境变量](configuration.zh.md#默认环境变量) → **Git
+身份** 中设置一次提交身份，容器便无需 `~/.gitconfig` 即可获得
+`GIT_AUTHOR_*`/`GIT_COMMITTER_*`。
+
+提示词会在 dsh 内完成上述全部配置，并且可以反复粘贴以修复工作区。Podman
+存储受管卷时会加上 `DSH_PODMAN_VOLUME_PREFIX` 前缀，因此该卷显示为
+`dsh-podman-dsh-podman-toolchain`。
+
 ### 安装本地插件构建
 
 dsh 镜像会在容器启动时自行安装插件，因此本地开发构建通过将安装源指向 bind mount
-的包来使用。先构建并打包插件：
+的包来使用。上面的 Quadlet 配置就是下面第一种形式，仓库目录本身
+（`%h/project/dsh-podman`）已经通过单元的只读 `%h/project`
+挂载可见。先构建并打包插件：
 
 ```bash
 pnpm build
@@ -99,7 +207,7 @@ Environment=DSH_PODMAN_PLUGIN_SOURCE=/mnt/dsh-podman
 
 ```
 # 或者归档本身
-Volume=/path/to/exagone313-dsh-podman-0.2.0-rc.3.tgz:/mnt/dsh-podman.tgz:ro
+Volume=/path/to/exagone313-dsh-podman-x.y.z.tgz:/mnt/dsh-podman.tgz:ro
 Environment=DSH_PODMAN_PLUGIN_SOURCE=/mnt/dsh-podman.tgz
 ```
 
@@ -119,10 +227,10 @@ zizmor）、`ci-code.yml`（Go、JS、镜像、Trivy）、`ci-docs.yml`（Deno f
 
 - **actions-lint** — zizmor 扫描工作流是否存在不安全实践。
 - **reuse** — REUSE 许可证合规检查。
-- **go** — 构建、vet、测试和 govulncheck（Go 漏洞）。未修复的
+- **go** — 构建、`gofmt -s` 检查、vet、测试和 govulncheck（Go 漏洞）。未修复的
   发现不会导致任务失败；可修复的会导致失败。
-- **js** — 安装、类型检查、构建、测试和 `pnpm audit`。
-- **docs** — 对 Markdown 运行 `deno fmt --check`。
+- **js** — TypeScript 格式检查、安装、类型检查、构建、测试和 `pnpm audit`。
+- **docs** — Markdown 格式检查（通过 `make fmt-check-md` 运行 `deno fmt`）。
 - **images** — 构建 orchestrator 和 guest-agent
   镜像（仅在测试任务通过后运行）；**dsh image** 构建 `Containerfile.dsh`。
 - **trivy** — 文件系统漏洞扫描（未修复的被忽略）和容器 错误配置扫描（DS-0002
@@ -148,8 +256,8 @@ zizmor）、`ci-code.yml`（Go、JS、镜像、Trivy）、`ci-docs.yml`（Deno f
 中的版本一致——否则工作流会失败——因此请用版本脚本同时更新两者：
 
 ```sh
-pnpm bump-version 0.1.1            # 加上 --dry-run 则仅校验
-git push origin master 0.1.1
+pnpm bump-version x.y.z            # 加上 --dry-run 则仅校验
+git push origin master x.y.z
 ```
 
 `scripts/bump-version.mjs` 会检查版本是否为递增的 Semver

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

@@ -10,11 +10,14 @@ SPDX-License-Identifier: MIT
 
 The goal of this guide is to install:
 
-- [DeepSeek Harness](https://deepseek.com/harness), referred to later as _dsh_
+- [DeepSeek Harness](https://deepseek.com/harness), referred to later as _dsh_,
+  in its own Podman container
 - the dsh-podman plugin in dsh, which replaces host filesystem and shell access
 - the dsh-podman orchestrator, a separate Podman container that integrates with
   Podman
 
+Note that if there is existing installation data at `~/.dsh`, it will be reused.
+
 Having the dsh plugin and the orchestrator running as separate containers is an
 important part of the security design of dsh-podman: dsh itself doesn't have
 direct access to Podman, only the orchestrator does, with limitations. dsh
@@ -109,6 +112,9 @@ which requires online access.
 2. Copy the files [dsh.container](../quadlet/dsh.container) and
    [dsh-podman-orchestrator.container](../quadlet/dsh-podman-orchestrator.container)
    to `~/.config/containers/systemd/`.
+   ```bash
+   cp quadlet/* ~/.config/containers/systemd/
+   ```
    - Adapt the files to your desired project directory if you wish to change it.
 3. Reload systemd session configuration:
    ```bash
@@ -140,16 +146,23 @@ which requires online access.
 
 ## Verification
 
-- Open **Settings → Plugins → dsh-podman**: the card should list the base images
-  and, for a workspace, offer to create its default container.
+- Open the sidebar's **Plugins** panel → **Installed** → **dsh-podman**: the
+  page should list the base images and, for a workspace, offer to create its
+  default container.
 - In a dsh session, run a shell command. It should execute inside a Podman
   container for the current workspace (the plugin auto-creates the workspace's
   default container on first use).
 
-## Enable daily auto-updates (optional)
+## Set Git identity (recommended)
+
+- Open settings from the sidebar's **Plugins** panel → **Installed** →
+  **dsh-podman**
+- Scroll down to **Default environment**
+- Click on **Git identity**
+- Enter the name and email to use for Git and click on **Apply**
+- Click on **Apply default environment variables** and then **Confirm**
 
-This requires enabling lingering for your user.
+## Updating dsh & dsh-podman
 
-```bash
-systemctl --user enable --now podman-auto-update.timer
-```
+Read the [update documentation](./update.md) to know how to manually update or
+set up auto-updates.

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 的权限能力是受限的：
@@ -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
@@ -120,15 +126,19 @@ SPDX-License-Identifier: MIT
 
 ## 验证
 
-- 打开 **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
+```