@loicngr/kobo 2.1.20 → 2.1.22

package/docs/deployment-vps.md

@@ -132,11 +132,34 @@ docker build -t kobo:local source
 
 Save [`docker-compose.vps.yml`](../docker-compose.vps.yml) as `/opt/kobo/compose.yaml`
 and [`scripts/kobo-update`](../scripts/kobo-update) as `/opt/kobo/kobo-update`.
+Also copy [`scripts/kobo-vps-entrypoint`](../scripts/kobo-vps-entrypoint) beside the updater as `/opt/kobo/kobo-vps-entrypoint`; the updater includes it in its compatibility image layer.
+
 These files may be newer than the example release above: obtain them from the
 checkout containing this guide, not an older tag that predates them.
 
 ```bash
-chmod 755 /opt/kobo/kobo-update
+chmod 755 /opt/kobo/kobo-update /opt/kobo/kobo-vps-entrypoint
+```
+
+For an older release image without the launcher, build this small compatibility
+layer before starting the current Compose template. Its build context contains
+only the launcher, never the deployment `.env`, projects or credentials:
+
+```bash
+mkdir -p runtime
+cp kobo-vps-entrypoint runtime/
+docker tag kobo:local kobo:release-base
+cat > runtime/Dockerfile <<'DOCKERFILE'
+FROM kobo:release-base
+USER root
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    util-linux netcat-openbsd docker-compose-plugin docker-buildx-plugin \
+    && rm -rf /var/lib/apt/lists/*
+COPY --chmod=755 kobo-vps-entrypoint /usr/local/bin/kobo-vps-entrypoint
+RUN chmod a+r /app/package.json /app/package-lock.json /app/CHANGELOG.md \
+    && chmod -R a+rX /app/dist /app/src/client/dist
+DOCKERFILE
+docker build -t kobo:local runtime
 ```
 
 Create `/opt/kobo/.env` with your deployment values:
@@ -147,8 +170,12 @@ KOBO_PROJECTS_DIR=/opt/kobo/projects
 TRAEFIK_NETWORK=web
 TRAEFIK_ENTRYPOINT=websecure
 TRAEFIK_CERTRESOLVER=letsencrypt
+KOBO_UID=1000
+KOBO_GID=1000
 ```
 
+Replace `KOBO_UID` and `KOBO_GID` with `id -u` and `id -g` from the host user who owns your projects. Both must be nonzero. The guided installer collects them automatically; `--uid` and `--gid` override them.
+
 The network, entrypoint and resolver names must match **your existing Traefik**;
 `web`, `websecure` and `letsencrypt` are examples. If Traefik uses a preloaded
 certificate rather than an ACME resolver, remove the `tls.certresolver` label.
@@ -173,8 +200,7 @@ remembers the token; treat both that URL and startup logs as credentials.
 the public hostname. Both network access and behind-proxy mode are enabled.
 
 This example publishes no HTTP or SSH ports. Use SSH to the VPS followed by
-`docker compose exec kobo bash` for a container shell. The Compose entrypoint
-starts Node directly, so it does not start the image's optional SSH daemon.
+`docker compose exec kobo kobo-vps-entrypoint --exec bash` for a container shell. The VPS launcher prepares the home permissions, then drops root before starting Node. It does not start the image's optional SSH daemon. `--exec` runs administrative shell/CLI commands as the same non-root user without repeating home migration.
 
 Check routing before starting a mission:
 
@@ -188,13 +214,85 @@ without a token. `/api/health` is intentionally public. Ordinary authenticated
 REST requests use `X-Kobo-Token`; the external MCP endpoint also supports Bearer
 authentication. No additional Traefik route is needed for WebSocket upgrades.
 
+Behind-proxy mode also protects loopback requests. Kōbō supplies the current
+network token to its internal workspace MCP process when launching Claude or
+Codex, so memory, progress bars and other backend calls can authenticate without
+manual MCP configuration. Memory and progress calls still require their separate
+per-launch capabilities. After rotating the network token, stop and resume active
+agent sessions so their MCP processes receive the new token.
+
 ## 3. Authenticate and choose a project
 
+### Runtime user and existing installations
+
+The VPS Compose example runs Kōbō and its agents as `KOBO_UID:KOBO_GID`, not
+root. Claude's bypass mode requires a non-root process; select that permission
+mode explicitly in Kōbō. The launcher's brief root bootstrap creates a matching
+user/group and assigns the dedicated home volume to them. Project directories
+are never recursively chowned. They must already be writable by the chosen UID.
+When the Docker socket is mounted, its numeric group is added to the agent's
+supplementary groups. That access still grants control over the host daemon.
+
+`HOME=/root` and `KOBO_HOME=/root/.config/kobo` deliberately remain unchanged:
+the directory name does not mean the process runs as root. Keeping it avoids
+losing existing sessions, logins, plugin paths and updater backups. Do not put
+additional bind mounts below `/root` in this standalone layout.
+
+Verify the effective identity, then use the same launcher for setup commands:
+
+```bash
+docker compose exec kobo kobo-vps-entrypoint --exec id
+docker compose exec kobo kobo-vps-entrypoint --exec bash
+```
+
+A plain `docker compose exec kobo ...` still defaults to the container's root
+bootstrap user. Installing skills or authenticating that way can create files
+the agent cannot update. Use `kobo-vps-entrypoint --exec` throughout this guide;
+reserve `--user 0` for deliberate OS maintenance. Do not add `user:` to the VPS
+Compose file: that would skip the permission bootstrap of an existing root home.
+
+For an **existing root deployment**, schedule an idle maintenance window and
+back up the full home volume plus the Compose file first. Build an image with
+the new launcher (the updated updater's `--prepare` does this), select your host
+UID/GID in `.env`, and update the service settings below (merge the environment
+with existing settings). `.env` alone does not pass variables into a container:
+
+```yaml
+entrypoint: ["kobo-vps-entrypoint"]
+command: ["node", "dist/server/index.js"]
+environment:
+  KOBO_UID: ${KOBO_UID:-1000}
+  KOBO_GID: ${KOBO_GID:-1000}
+  HOME: /root
+  NODE_ENV: development
+  NPM_CONFIG_INCLUDE: dev
+```
+
+Keep the same named home volume and project mount paths. Recreate the idle
+service, verify `id`, authenticated API access and one agent launch. The initial
+ownership scan takes longer for a large home. Read-only App keys/configuration
+must also be readable by the selected UID; changing the home owner cannot repair
+their host permissions.
+
+The updater preserves existing Compose settings: updating an image alone does
+**not** convert a legacy `entrypoint: ["node"]` deployment to non-root. The
+installer does not migrate completed managed stacks or rewrite their recorded
+fingerprints. Retain their manifest as history and manage an intentional Compose
+migration with the updater/manual procedure; do not rerun the installer to adopt
+the altered files. The other Compose examples retain their historical entrypoint.
+
+The current VPS template needs an image containing `kobo-vps-entrypoint`. For a
+fresh manual installation of an older release, build the compatibility layer in
+step 1. For an existing installation, the updated updater's `--prepare` includes
+it. Do not combine the new template with an unmodified old image.
+
+### Engine and Git login
+
 Authenticate **inside the container**, using the engine you intend to run:
 
 ```bash
-docker compose exec kobo claude auth login
-docker compose exec kobo codex login --device-auth
+docker compose exec kobo kobo-vps-entrypoint --exec claude auth login
+docker compose exec kobo kobo-vps-entrypoint --exec codex login --device-auth
 ```
 
 Follow the browser URL/code printed by your installed CLI. Provider availability
@@ -206,10 +304,10 @@ For a personal GitHub account, complete the CLI's browser login flow from your P
 then connect Git HTTPS credentials to it:
 
 ```bash
-docker compose exec kobo gh auth login --hostname github.com --git-protocol https --web
-docker compose exec kobo gh auth setup-git --hostname github.com
-docker compose exec kobo git config --global user.name "Your Name"
-docker compose exec kobo git config --global user.email "you@example.com"
+docker compose exec kobo kobo-vps-entrypoint --exec gh auth login --hostname github.com --git-protocol https --web
+docker compose exec kobo kobo-vps-entrypoint --exec gh auth setup-git --hostname github.com
+docker compose exec kobo kobo-vps-entrypoint --exec git config --global user.name "Your Name"
+docker compose exec kobo kobo-vps-entrypoint --exec git config --global user.email "you@example.com"
 ```
 
 Git commit identity and forge authentication are separate settings. For a GitHub
@@ -219,7 +317,7 @@ instead of an interactive account login.
 Clone your repository in the mounted project directory (replace the repository):
 
 ```bash
-docker compose exec kobo git clone https://github.com/YOUR-ORG/YOUR-REPO.git /opt/kobo/projects/my-project
+docker compose exec kobo kobo-vps-entrypoint --exec git clone https://github.com/YOUR-ORG/YOUR-REPO.git /opt/kobo/projects/my-project
 ```
 
 In the first-run form, **Local project directory** means
@@ -233,9 +331,9 @@ not automatically available inside a container. See [Docker volume persistence](
 
 ## Optional project Docker environments
 
-The image includes the Docker CLI and Compose plugin. Verify with
-`docker compose exec kobo docker compose version`; an older release image may
-need the plugin installed in a derived image. The updater below adds it when missing.
+The image includes the Docker CLI, Compose and Buildx plugins, and netcat (`nc`). Verify with
+`docker compose exec kobo kobo-vps-entrypoint --exec docker compose version`; an older release image may
+need these tools installed in a derived image. The updater below includes them in its compatibility layer.
 
 To let agents manage project containers, explicitly enable the commented
 `/var/run/docker.sock` mount in `compose.yaml` and recreate the service when idle.
@@ -253,6 +351,10 @@ An `npm` development process does not require the Docker socket. Development
 server URLs are separate from Kōbō's dashboard URL; configure their own reachable
 ports or proxy routes. See the [dev-server contract](../CONFIGURATION.md#dev-server).
 
+For project dependencies, private registry login, SSH tunnels, stop/cleanup commands,
+file-watcher troubleshooting and installing Claude/Codex extensions, follow
+[Projects, development servers and skills on a VPS](./vps-projects-and-skills.md).
+
 ## GitHub App bot authentication
 
 A GitHub App installation token expires after one hour. Putting one token in
@@ -348,12 +450,12 @@ Recreate the idle service to apply the mounts, then configure Git inside it:
 ```bash
 docker compose config --quiet
 docker compose up -d --wait --wait-timeout 180 kobo
-docker compose exec kobo kobo-github-app-token --check
-docker compose exec kobo git config --global --replace-all credential.https://github.com.helper ''
-docker compose exec kobo git config --global --add credential.https://github.com.helper '!/usr/local/bin/gh auth git-credential'
-docker compose exec kobo bash -lc 'command -v gh'
-docker compose exec kobo gh repo view YOUR-ORG/YOUR-REPO --json nameWithOwner
-docker compose exec kobo git -C /opt/kobo/projects/my-project ls-remote origin HEAD
+docker compose exec kobo kobo-vps-entrypoint --exec kobo-github-app-token --check
+docker compose exec kobo kobo-vps-entrypoint --exec git config --global --replace-all credential.https://github.com.helper ''
+docker compose exec kobo kobo-vps-entrypoint --exec git config --global --add credential.https://github.com.helper '!/usr/local/bin/gh auth git-credential'
+docker compose exec kobo kobo-vps-entrypoint --exec bash -lc 'command -v gh'
+docker compose exec kobo kobo-vps-entrypoint --exec gh repo view YOUR-ORG/YOUR-REPO --json nameWithOwner
+docker compose exec kobo kobo-vps-entrypoint --exec git -C /opt/kobo/projects/my-project ls-remote origin HEAD
 ```
 
 The empty helper entry resets inherited helpers **only for this HTTPS host**.
@@ -373,7 +475,7 @@ renewals with a bounded lock, and invalidates cached tokens when the configurati
 or key changes. Failed renewal never falls back to an expired token. HTTPS calls
 use the fixed GitHub API endpoint and do not follow redirects.
 
-Use `docker compose exec kobo kobo-github-app-token --check` to validate signing,
+Use `docker compose exec kobo kobo-vps-entrypoint --exec kobo-github-app-token --check` to validate signing,
 GitHub authentication and the cache without exposing a token. It prints a JSON
 status and expiration time. On failure, check file permissions, the key and IDs,
 the App installation's repository access, server clock and outbound HTTPS. Do not
@@ -385,8 +487,8 @@ commits. Configure commit identity separately, for example using your App's bot
 login and its actual GitHub bot-user email:
 
 ```bash
-docker compose exec kobo git config --global user.name 'YOUR-APP[bot]'
-docker compose exec kobo git config --global user.email 'BOT-USER-ID+YOUR-APP[bot]@users.noreply.github.com'
+docker compose exec kobo kobo-vps-entrypoint --exec git config --global user.name 'YOUR-APP[bot]'
+docker compose exec kobo kobo-vps-entrypoint --exec git config --global user.email 'BOT-USER-ID+YOUR-APP[bot]@users.noreply.github.com'
 ```
 
 `BOT-USER-ID` is the bot account's user ID, not the App ID or installation ID.
@@ -427,9 +529,11 @@ assuming a particular server. It uses the local Docker daemon; do not point it
 at a remote Docker context. It requires network access to npm, GitHub and image
 build dependencies. It does not update Traefik or install a scheduled auto-updater.
 
+Keep `kobo-vps-entrypoint` beside `kobo-update` when updating the operator scripts (the guided installer places both in `bin/`). This is required even when building an older release.
+
 Both operator scripts explicitly read the deployment directory's `.env` for
 Compose. Exported `KOBO_DOMAIN`, `KOBO_PROJECTS_DIR`, `TRAEFIK_NETWORK`,
-`TRAEFIK_ENTRYPOINT`, `TRAEFIK_CERTRESOLVER` and `COMPOSE_*` variables in the caller's
+`TRAEFIK_ENTRYPOINT`, `TRAEFIK_CERTRESOLVER`, `KOBO_UID`, `KOBO_GID` and `COMPOSE_*` variables in the caller's
 shell cannot override these commands. This applies to validation, start, stop and
 recovery. Docker context selection and forge authentication remain available to
 child processes; other commands such as image builds retain their environment.
@@ -457,11 +561,11 @@ original deadline and prompt stay unchanged. Already stale, never-attempted
 wakeups are not revived.
 It retrieves npm's `latest` version (or the explicit
 stable version), verifies the Git tag's commit and package version, builds a uniquely
-tagged image, ensures Compose is installed and checks native modules. The old
+tagged image, ensures Compose, Buildx, netcat and the non-root launcher are installed and checks native modules. The old
 service stays available during the build. Plan for roughly 5–15 minutes without
-build cache; backup duration depends on the volume size.
+build cache; backup duration depends only on the size of Kōbō's data directory.
 
-Once idle, it stops Kōbō, archives the complete `/root` volume, tests SQLite
+Once idle, it stops Kōbō, archives only `/root/.config/kobo`, tests SQLite
 migrations/integrity on a copy, pins the new image directly in `compose.yaml`, and
 starts the service. It checks container health, the authenticated internal API,
 the version served through HTTPS, and public API rejection without a token. It
@@ -473,9 +577,12 @@ repository when you want to update the updater.
 ## Backups and failed updates
 
 Each update records its private log, `state.json`, previous Compose file,
-`home.tar.gz` and recovery instructions in `<deployment>/updates/<timestamp>-<id>/`.
-The archive contains credentials as well as application data; keep it private.
-A prepared-only build does not create a home backup. No old images, backups or
+`kobo.tar.gz` and recovery instructions in `<deployment>/updates/<timestamp>-<id>/`.
+The archive contains the whole `/root/.config/kobo` directory: SQLite database
+and WAL/SHM sidecars when present, settings, templates, attachments and other Kōbō
+data. It retains paths relative to `/root`. Settings can contain credentials;
+keep the archive private. `state.json` records the backup scope and archive name.
+A prepared-only build does not create a backup. No old images, backups or
 volumes are automatically removed; monitor disk space and retain off-host copies.
 
 An error before shutdown releases the reservation, including a lost acquisition
@@ -486,9 +593,12 @@ the reservation deliberately has no expiry that could reopen the race. Follow
 container and confirm its exit before restarting it. Restart clears the in-memory
 reservation. Never release it while a Docker stop could still be in progress.
 
-Repositories/worktrees stored outside `/root`, bind-mounted App keys/scripts and
-project database volumes are **not included** in `home.tar.gz`. Back them up
-separately along with `.env` and other deployment files. Never copy a live SQLite
+Claude/Codex configuration and credentials, skills/plugins, caches, browser
+downloads, repositories/worktrees, bind-mounted App keys/scripts and project
+database volumes are **not included** in `kobo.tar.gz`. Files outside the Kōbō
+directory remain in the existing volume; the updater neither archives nor deletes
+them. Back up important files separately, along with `.env` and deployment files.
+Never copy a live SQLite
 file as your only database backup; the updater stops Kōbō before archiving it.
 
 A build failure leaves the current service running. A backup or migration-test
@@ -496,8 +606,17 @@ failure restarts the previous version before new code touches production data.
 After a new-version launch, an error leaves data intact for diagnosis: an older
 image must not be blindly started against a migrated database, and a snapshot
 restore could discard messages or work resumed since launch. Read the generated
-`RECOVERY.md`; restore to a **new volume**, retaining the current one, if a full
-rollback is necessary. An interrupted update blocks subsequent updates until its
+`RECOVERY.md`: for a rollback, stop Kōbō and clone the current volume into a **new
+volume** so engine credentials and skills are retained. In the new volume only,
+replace `.config/kobo` completely from `kobo.tar.gz`, preserving numeric ownership
+and permissions, then use that volume with the previous image. Do not overlay an
+old database onto newer WAL/SHM files. Keep the original volume. This restores
+Kōbō data only, not engine state or project changes.
+
+Older updater versions created `home.tar.gz` containing all of `/root`; use each
+backup's own `RECOVERY.md`. Updating the Kōbō image does not update the operator
+script: install the newer `scripts/kobo-update` to use the smaller backups.
+An interrupted update blocks subsequent updates until its
 recorded state has been reviewed. Inspect logs locally; they may contain secrets.
 
 For troubleshooting, start with `docker compose ps`, the private update log and

package/docs/getting-started.md

@@ -12,6 +12,11 @@ No skill plugin, forge CLI, Docker, Notion, Sentry or voice software is needed f
 
 For a remote installation, follow the [VPS and Docker guide](./deployment-vps.md) first: `kobo-install` guides a fresh installation behind existing Traefik and can configure a GitHub App bot. The same guide documents manual setup. The project picker browses the server/container filesystem: select a repository cloned there, not a folder on the PC running your browser. Authenticate the agent and forge tools inside the container too.
 
+The [VPS projects and skills guide](./vps-projects-and-skills.md) explains how to
+prepare environment files/dependencies, open a remote dev server through SSH,
+and install Claude/Codex skills as the non-root agent user. Host/PC installations
+are not automatically inherited by container agents.
+
 ## Start
 
 ```bash
@@ -51,6 +56,17 @@ Configure integrations only when you need them, in their Settings tabs. Notion a
 
 ## Existing installations
 
+The **Show progress bars** switch in **Settings → Agents** is enabled by default.
+Turn it off and save to hide activity indicators without interrupting their work
+or tracking. Re-enabling it preserves individual dismissals and expiry times.
+
+The **agent inactivity watchdogs** switch is at the top of **Settings → Agents**.
+It is off by default, including after upgrading an existing installation, so a
+long silent task is not stopped by Kōbō's engine inactivity timers. Enable it if
+you want stalled sessions closed automatically. Changes apply on the next agent
+start or resume. The Settings tour explains this option; see
+[session watchdogs](../CONFIGURATION.md#session-watchdogs) for the deadlines.
+
 Upgrades preserve customized prompts, plugin selection, integration toggles, permission modes and resource limits. Existing installations retain legacy automatic Git workflow preferences; review them in Settings if you prefer manual authorization. Existing workspaces receive a snapshot of that historical policy, while new workspaces snapshot the effective global/project/create policy. Changing a global policy does not rewrite existing missions.
 
 Known shipped prompt text and retired sound selections are migrated; custom prompt text is preserved. Audio enablement and volume are retained. Take a complete backup before an upgrade; see [Troubleshooting](./troubleshooting.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loicngr/kobo",
-  "version": "2.1.20",
+  "version": "2.1.22",
   "description": "Kōbō — local multi-workspace orchestrator for Claude Code and OpenAI Codex, with isolated Git worktrees, live review and optional automation.",
   "type": "module",
   "license": "GPL-3.0-or-later",

package/scripts/kobo-install

@@ -20,7 +20,7 @@ spec = importlib.util.spec_from_loader(loader.name, loader)
 updater = importlib.util.module_from_spec(spec)
 loader.exec_module(updater)
 InstallError = updater.UpdateError
-TOOLS = ('kobo-install', 'kobo-update', 'kobo-github-app-token', 'kobo-gh')
+TOOLS = ('kobo-install', 'kobo-update', 'kobo-github-app-token', 'kobo-gh', 'kobo-vps-entrypoint')
 ENV_KEYS = updater.COMPOSE_ENV_KEYS
 
 
@@ -32,6 +32,10 @@ def safe_path(value):
 
 
 def validate_config(config):
+    for name in ('uid', 'gid'):
+        value = str(config.get(name, 1000))
+        if not re.fullmatch(r'[1-9][0-9]{0,9}', value) or int(value) > 2147483647:
+            raise InstallError('UID and GID must be positive non-root numeric IDs.')
     domain = config['domain']
     if (len(domain) > 253 or '.' not in domain or
             not all(re.fullmatch(r'[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?', label)
@@ -49,6 +53,9 @@ def validate_config(config):
         raise InstallError('Projects must be outside container system paths, /app and /root (for example /opt/kobo/projects).')
     if projects.exists() and not projects.is_dir():
         raise InstallError('The projects path must be a directory.')
+    if not projects.exists() and 'uid' in config and os.getuid() not in (0, int(config['uid'])):
+        raise InstallError('A new projects directory requires --uid to match the installer user, or root. '
+                           'Otherwise prepare a directory writable by that UID first.')
     app = [config.get(k) for k in ('github_app_id', 'github_installation_id', 'github_private_key')]
     if any(app):
         if not all(app):
@@ -58,6 +65,10 @@ def validate_config(config):
         key = safe_path(app[2])
         if not key.is_file() or not os.access(key, os.R_OK) or key.stat().st_mode & 0o077:
             raise InstallError('The GitHub private key must be a readable regular file with private permissions (0600).')
+        if 'uid' in config and key.stat().st_uid != int(config['uid']):
+            raise InstallError('The GitHub private key owner must match --uid so the non-root agent can read it.')
+        if 'uid' in config and os.getuid() not in (0, int(config['uid'])):
+            raise InstallError('Run the installer as --uid (or root) to create readable private GitHub configuration.')
     if config['version'] != 'latest':
         updater.normalize_version(config['version'])
 
@@ -81,7 +92,7 @@ def render(config, stack):
                        '        bind:\n          create_host_path: false\n')
         text = text.replace('    networks:\n', mounts + '    networks:\n', 1)
     values = (config['domain'], config['projects_directory'], config['network'],
-              config['entrypoint'], config['certresolver'])
+              config['entrypoint'], config['certresolver'], str(config.get('uid', 1000)), str(config.get('gid', 1000)))
     env = ''.join(f"{key}='{value}'\n" for key, value in zip(ENV_KEYS, values))
     return text, env
 
@@ -180,7 +191,13 @@ class Installer(updater.Updater):
             path = self.stack / name
             path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
             updater.atomic_write(path, data, 0o755 if name.startswith('bin/') else 0o600)
-        Path(config['projects_directory']).mkdir(parents=True, exist_ok=True)
+            if name == 'auth/github-app.json' and os.getuid() == 0:
+                os.chown(path, int(config.get('uid', 1000)), int(config.get('gid', 1000)))
+        projects = Path(config['projects_directory'])
+        projects_existed = projects.exists()
+        projects.mkdir(parents=True, exist_ok=True)
+        if not projects_existed and os.getuid() == 0:
+            os.chown(projects, int(config.get('uid', 1000)), int(config.get('gid', 1000)))
         self.save(phase='configured')
 
     def verify_files(self):
@@ -198,16 +215,19 @@ class Installer(updater.Updater):
         # No files or directories are needed for --check. All substitutions are supplied explicitly.
         text, _ = render(config, self.stack)
         for key, value in zip(ENV_KEYS, (config['domain'], config['projects_directory'], config['network'],
-                                       config['entrypoint'], config['certresolver'])):
+                                       config['entrypoint'], config['certresolver'],
+                                       str(config.get('uid', 1000)), str(config.get('gid', 1000)))):
             text = re.sub(r'\$\{' + key + r'(?::[^}]*)?\}', lambda _: value, text)
         self.run(['docker', 'compose', '--env-file', '/dev/null', '-p', 'kobo', '-f', '-', 'config', '--quiet'],
                  data=text.encode())
 
     def configure_github(self):
-        self.run(self.compose('exec', '-T', 'kobo', '/usr/local/bin/kobo-github-app-token', '--check'))
+        # Legacy prepared installations retain their original root execution.
+        runtime = ['kobo-vps-entrypoint', '--exec'] if 'uid' in self.state.get('config', {}) else []
+        self.run(self.compose('exec', '-T', 'kobo', *runtime, '/usr/local/bin/kobo-github-app-token', '--check'))
         helper = 'credential.https://github.com.helper'
-        self.run(self.compose('exec', '-T', 'kobo', 'git', 'config', '--global', '--replace-all', helper, ''))
-        self.run(self.compose('exec', '-T', 'kobo', 'git', 'config', '--global', '--add', helper,
+        self.run(self.compose('exec', '-T', 'kobo', *runtime, 'git', 'config', '--global', '--replace-all', helper, ''))
+        self.run(self.compose('exec', '-T', 'kobo', *runtime, 'git', 'config', '--global', '--add', helper,
                              '!/usr/local/bin/gh auth git-credential'))
 
     def assert_started(self):
@@ -297,6 +317,8 @@ class Installer(updater.Updater):
 def arguments(argv=None):
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument('--directory', type=Path, required=True)
+    parser.add_argument('--uid', help='Non-root runtime UID (defaults to the invoking user).')
+    parser.add_argument('--gid', help='Runtime GID (defaults to the invoking user).')
     for name in ('domain', 'projects-directory', 'network', 'entrypoint', 'certresolver', 'version',
                  'github-app-id', 'github-installation-id', 'github-private-key'):
         parser.add_argument('--' + name)
@@ -311,7 +333,7 @@ def arguments(argv=None):
 
 def configure(args, installer):
     names = ('domain', 'projects_directory', 'network', 'entrypoint', 'certresolver', 'version',
-             'github_app_id', 'github_installation_id', 'github_private_key', 'docker_socket')
+             'github_app_id', 'github_installation_id', 'github_private_key', 'docker_socket', 'uid', 'gid')
     config = installer.state.get('config', {}).copy()
     config.update({name: getattr(args, name) for name in names if getattr(args, name) is not None})
     interactive = sys.stdin.isatty() and not args.yes
@@ -339,6 +361,10 @@ def configure(args, installer):
     ask('entrypoint', 'Traefik HTTPS entrypoint')
     ask('certresolver', 'Traefik certificate resolver (empty for preloaded certificate)', '')
     ask('version', 'Stable release version', 'latest')
+    # Do not silently change an already managed deployment's recorded config.
+    if not installer.state:
+        ask('uid', 'Host user ID for Kōbō and agents', str(os.getuid() or 1000))
+        ask('gid', 'Host group ID for Kōbō and agents', str(os.getgid() or 1000))
     if config.get('docker_socket') is None:
         config['docker_socket'] = interactive and input('Give agents Docker access (root-equivalent host control)? [y/N]: ').lower() == 'y'
     if not any(config.get(name) for name in ('github_app_id', 'github_installation_id', 'github_private_key')):
@@ -365,6 +391,7 @@ def main(argv=None):
             return 0
         print(f'Install directory: {installer.stack}\nURL: https://{config["domain"]}\n'
               f'Projects: {config["projects_directory"]}\nDocker socket: {config["docker_socket"]}\n'
+              f'Runtime UID:GID: {config.get("uid", "legacy")}:{config.get("gid", "legacy")}\n'
               f'GitHub App: {bool(config["github_app_id"])}')
         if not args.yes and not installer.state:
             if not sys.stdin.isatty() or input('Create this installation? [y/N]: ').lower() != 'y':

package/scripts/kobo-update

@@ -21,7 +21,7 @@ from datetime import datetime, timezone
 REPO = 'https://github.com/loicngr/kobo.git'
 VERSION = re.compile(r'\d+\.\d+\.\d+')
 COMPOSE_ENV_KEYS = ('KOBO_DOMAIN', 'KOBO_PROJECTS_DIR', 'TRAEFIK_NETWORK',
-                    'TRAEFIK_ENTRYPOINT', 'TRAEFIK_CERTRESOLVER')
+                    'TRAEFIK_ENTRYPOINT', 'TRAEFIK_CERTRESOLVER', 'KOBO_UID', 'KOBO_GID')
 BUSY_JS = r"""
 const db = new (require('better-sqlite3'))('/root/.config/kobo/kobo.db', {readonly:true});
 const sessions = db.prepare("SELECT count(*) n FROM agent_sessions WHERE status = 'running'").get().n;
@@ -217,7 +217,7 @@ class Updater:
                                    'node', '-p', 'require("./package.json").version']))
         self.idle()
         self.run(['docker', 'compose', 'version'])
-        used_kib = int(self.run(['docker', 'exec', self.container, 'du', '-sk', '/root']).split()[0])
+        used_kib = int(self.run(['docker', 'exec', self.container, 'du', '-sk', '/root/.config/kobo']).split()[0])
         # Sources/build layers plus archive + migration copy; compression is not assumed.
         required = 6 * 1024**3 + used_kib * 1024 * 2
         docker_root = self.run(['docker', 'info', '--format', '{{.DockerRootDir}}'])
@@ -262,24 +262,38 @@ class Updater:
         self.logged(['docker', 'build', '--progress=plain', '-t', base, str(source)])
         overlay = self.job / 'overlay'
         overlay.mkdir()
+        launcher = Path(__file__).resolve().with_name('kobo-vps-entrypoint')
+        if not launcher.is_file():
+            raise UpdateError('Install kobo-vps-entrypoint beside kobo-update before building an image.')
+        shutil.copyfile(launcher, overlay / 'kobo-vps-entrypoint')
         (overlay / 'Dockerfile').write_text(
-            f'FROM {base}\nRUN docker compose version >/dev/null 2>&1 || '
-            '(apt-get update && apt-get install -y --no-install-recommends docker-compose-plugin '
-            '&& rm -rf /var/lib/apt/lists/*)\n')
+            f'FROM {base}\nUSER root\n'
+            'RUN apt-get update && apt-get install -y --no-install-recommends '
+            'docker-compose-plugin docker-buildx-plugin netcat-openbsd util-linux '
+            '&& rm -rf /var/lib/apt/lists/*\n'
+            'COPY --chmod=755 kobo-vps-entrypoint /usr/local/bin/kobo-vps-entrypoint\n'
+            'RUN chmod a+r /app/package.json /app/package-lock.json /app/CHANGELOG.md '
+            '&& chmod -R a+rX /app/dist /app/src/client/dist\n')
         self.logged(['docker', 'build', '--progress=plain', '-t', image, str(overlay)])
         self.run(['docker', 'run', '--rm', '--network', 'none', '--entrypoint', 'docker',
                   image, 'compose', 'version'])
         self.run(['docker', 'run', '--rm', '--network', 'none', '--entrypoint', 'node', image,
                   '-e', "require('better-sqlite3')(':memory:').close();require('node-pty')"])
+        self.run(['docker', 'run', '--rm', '--network', 'none', '--entrypoint', 'kobo-vps-entrypoint',
+                  image, 'node', '-e', "if(process.getuid()===0)process.exit(1);"
+                  "const fs=require('fs');const dir='/app/src/client/dist/';"
+                  "const mode=['pwa','spa'].find(m=>fs.existsSync(dir+m+'/index.html'));"
+                  "if(!mode)throw Error('Missing built UI');fs.accessSync(dir+mode+'/index.html',fs.constants.R_OK);"
+                  "require('better-sqlite3')(':memory:').close();require('node-pty')"])
         return image
 
     def backup(self):
-        archive = self.job / 'home.tar.gz'
+        archive = self.job / 'kobo.tar.gz'
         with archive.open('xb') as f, self.log.open('ab') as err:
             try:
                 subprocess.run(['docker', 'run', '--rm', '--network', 'none', '--read-only',
                     '--mount', f'type=volume,src={self.volume},dst=/data,readonly',
-                    '--entrypoint', 'tar', self.old_image, '-C', '/data', '-czf', '-', '.'],
+                    '--entrypoint', 'tar', self.old_image, '-C', '/data', '-czf', '-', './.config/kobo'],
                     stdout=f, stderr=err, check=True, timeout=3600)
                 f.flush()
                 os.fsync(f.fileno())
@@ -346,6 +360,7 @@ class Updater:
         self.record('building', previous_image=old_tag, previous_digest=self.old_image,
                     volume=self.volume, version=version, sha=sha,
                     maintenance_owner=self.maintenance_owner,
+                    backup_archive='kobo.tar.gz', backup_scope='/root/.config/kobo',
                     backup_complete=False, new_version_start_attempted=False)
         self.recovery_notes()
         stopped = False
@@ -372,7 +387,7 @@ class Updater:
             self.maintenance('POST')
             self.record('stopping')
             stopped = True  # Also recover if the stop command itself fails/interruption arrives.
-            say('Stopping Kōbō, backing up /root and testing migrations on a database copy…')
+            say('Stopping Kōbō, backing up only /root/.config/kobo and testing migrations on a database copy…')
             self.run(self.compose('stop', '-t', '60', 'kobo'))
             info = json.loads(self.run(['docker', 'inspect', self.container]))[0]
             if info['State']['Running']:
@@ -390,7 +405,7 @@ class Updater:
             self.logged(self.compose('up', '-d', '--no-deps', '--wait', '--wait-timeout', '180', 'kobo'), timeout=240)
             self.verify(version)
             self.record('complete')
-            say(f'Kōbō {version} is up to date. Backup: {self.job / "home.tar.gz"}')
+            say(f'Kōbō {version} is up to date. Backup: {self.job / "kobo.tar.gz"}')
         except BaseException:
             if stopped and not launching:
                 # Only safe before any process from the new version has used production data.
@@ -432,9 +447,11 @@ Private log: `{self.job / 'update.log'}`. Durable phase: `state.json`.
 Previous configuration: `compose.before.yaml`.
 Previous immutable image: `{self.old_image}`.
 Original volume: `{self.volume}`.
-The archive `home.tar.gz` is validated only when backup_complete=true.
+The archive `kobo.tar.gz` is validated only when backup_complete=true.
+It contains ONLY /root/.config/kobo, with paths relative to /root.
 new_version_start_attempted indicates whether a new-version launch was attempted.
-Projects outside /root are NOT included in this archive; back them up separately.
+Claude/Codex credentials, skills/plugins, caches and projects are NOT included;
+back up those files separately if needed. They remain in the original volume.
 Old images, volumes and backups are never automatically deleted.
 
 ## Interrupted admission reservation
@@ -461,10 +478,15 @@ Do not run an older image against a potentially migrated database.
 Inspect the private log and Compose logs (which may contain credentials).
 A proxy error can leave a working backend: check for new messages and resumed
 work before considering a restore.
-To roll back fully, stop Kōbō, back up the current volume too, extract home.tar.gz
-into a NEW empty Docker volume and adapt the previous Compose configuration to
-use that restored volume and the previous immutable image above. Keep the current
-volume. Database rollback does not undo external agent or project changes.
+To roll back Kōbō data, stop Kōbō and preserve the current volume. Clone that
+stopped volume into a NEW Docker volume to retain current engine credentials,
+skills and other files outside .config/kobo. In the NEW volume only, replace
+.config/kobo completely with the contents of kobo.tar.gz (extract at the volume
+root, preserving numeric owners and permissions). Do not merge the old database
+with newer WAL/SHM files or other new-version Kōbō files. Adapt the previous
+Compose configuration to use that restored volume and the previous immutable
+image above. Keep the original volume. This archive cannot roll back files
+outside .config/kobo, external agent actions or project changes.
 After recovery and health verification, set state.json phase to complete or aborted.
 ''')