Imported from ChenyuHeee/dsh-remote (AGENTS.md). Install upstream with npx skills add ChenyuHeee/dsh-remote. Copyright stays with the author.

AGENTS.md — deployment playbook for AI agents

This repository is a deployment kit: it installs a DeepSeek Harness (DSH) web server on a user's Linux box and publishes it on the public internet behind HTTPS + password authentication. When a user asks you to "set up DSH remote" or "deploy this repo to my server", follow this playbook.

TL;DR procedure

1. Gather the four required inputs from the user (ask, don't assume):
   • DSH_DOMAIN — a domain/subdomain whose A record points at the server (DNS must resolve before the nginx step; remind the user to add it early)
   • SSH_HOST — user@host reachable from your machine (root/sudo needed); leave empty only when you are executing on the server itself
   • AUTHELIA_USER — portal login name (default admin)
   • AUTHELIA_PASSWORD — optional; leave empty to auto-generate a strong one (recommended). Never print generated passwords into chat/logs unnecessarily.
2. cp deploy.conf.example deploy.conf and fill it in.
3. Run ./deploy.sh. It renders templates, uploads the kit, and executes the server scripts in order: setup.sh → install-dsh.sh → deploy-authelia.sh → deploy-nginx.sh → check.sh.
4. Verify ALL CHECKS PASSED in the output, then give the user: the URL, the username, where the initial password is stored (server /opt/dsh/authelia/config/INITIAL_PASSWORD.txt, root-only), and the change-password command.

File map

Server scripts (run as root, all idempotent)

• setup.sh — swapfile, Node 22 LTS, pnpm (corepack), nginx+certbot if missing, dsh system user, /opt/dsh tree, kit install. Never touches existing nginx sites or services.
• install-dsh.sh [version] — pins @deepseek-ai/dsh@<version> under /opt/dsh, approves native builds, installs & restarts the systemd unit.
• deploy-authelia.sh — generates secrets once, hashes the password, docker compose up -d, health check.
• deploy-nginx.sh — HTTP-only vhost → certbot certonly --webroot → full HTTPS vhost → reload; handles the nginx http2 syntax split automatically; installs the junk-traffic 444 blocklist and the fail2ban nginx-dsh jail (scanner IPs banned at the firewall for 1h, auto-release).
• change-authelia-password.sh [user] — interactive password change.
• set-deepseek-key.sh [sk-...] — writes /opt/dsh/dsh.env (root-only 600).
• backup.sh [--install-cron] — nightly tar, keeps 7.
• check.sh — the verification checklist (must exit 0).

Verification checklist (all must pass before you report success)

• check.sh prints ALL CHECKS PASSED.
• Anonymous https://$DSH_DOMAIN/ → 302 to /authelia/?rd=....
• Portal HTML has <base href="https://$DSH_DOMAIN/authelia/" and its JS asset loads anonymously with HTTP 200 — this is a regression we actually shipped once (blank login page); check.sh covers it.
• Login flow (JSON, not form-encoded): GET /authelia/api/state?targetURL=..., then POST /authelia/api/firstfactor with {"username","password","targetURL","workflow":"fast"} → 200 OK; then GET / with the session cookie → 200 and __DSH_BOOT__ present.
• Direct http://127.0.0.1:3080/api/... with a foreign Host header → 403.

Hard-won gotchas (do not re-learn these)

1. DSH refuses --host 0.0.0.0 by design (RCE surface). Always bind 127.0.0.1 and put nginx in front; declare the public authority with --trusted-host $DSH_DOMAIN, and preserve the public Host header in the proxy (proxy_set_header Host $host) or every browser call gets 403.
2. nginx http2 syntax split: ≤1.24 uses listen 443 ssl http2;; ≥1.25 rejects that and wants http2 on;. deploy-nginx.sh detects and rewrites.
3. Authelia 4.39 single-domain portal: set server.address: 'tcp://0.0.0.0:9091/authelia' (the old server.path key is deprecated and errors). Without the path in the address the portal's <base href> points at the root, its assets get caught by the auth gate, and the login page renders blank.
4. Authelia API headers: auth endpoints need X-Original-Method (not the old X-Forwarded-Method); POST /api/firstfactor takes a JSON body; the API lives under upstream /api/*, so the nginx location /authelia/api/ must strip the prefix (proxy_pass http://127.0.0.1:9091/api/;).
5. Argon2id params must match between hash and config (iterations 3, memory 65536 KiB, parallelism 4, salt 16, key 32). The CLI flag --random randomizes the password, not the salt — never pass it with --password, or the stored hash won't match the saved password. Authelia 4.39 also requires storage.encryption_key.
6. npm OOMs on ≤2 GiB boxes — always install DSH with pnpm (corepack). pnpm 10+ blocks native build scripts by default: approve node-pty, koffi, @deepseek-ai/dsh-subprocess-local, protobufjs, @google/genai via pnpm-workspace.yaml (onlyBuiltDependencies) and pnpm rebuild, or the bash/PTY tools silently break.
7. Docker published ports bypass ufw — publish Authelia on 127.0.0.1:9091 only, never 0.0.0.0. Also cap_drop: ALL breaks the image entrypoint (it needs SETUID/SETGID for its su-exec user switch).
8. certbot: run certonly --webroot (never --nginx, which rewrites user config); install the renewal deploy hook that reloads nginx; DNS must resolve before issuance — tell the user to add the A record early and re-run deploy-nginx.sh if it fails.
9. DSH web profile is loopback-only by default (127.0.0.1:3080) and the /api trust fence answers 403 to any non-loopback authority not listed in trustedHosts — this is the DNS-rebinding defense; do not "fix" it by binding wider.
10. Use Restart=always, never Restart=on-failure for the dsh unit: the harness exits cleanly (code 0) on signals/graceful shutdowns, which on-failure does NOT restart — the site then sits in 502 until someone notices. Also, MemoryMax/TasksMax bound the WHOLE cgroup (DSH plus the agent's test runners); keep TasksMax ≥4096 and raise MemoryMax for vitest-class workloads.
11. systemd RestrictRealtime= and LockPersonality= silently imply NoNewPrivileges=yes (both are enforced via seccomp filters that require NNP). If the deployment grants the agent sudo ("full-root mode"), these two options make every sudo fail with "The 'no new privileges' flag is set" even when NoNewPrivileges= is explicitly no and the sudoers entry is correct. Removing them is a prerequisite — as is setting the deployment sandbox default to danger-full-access (profile patch on sandbox-policy, plus permission.defaultPreset: danger-full-access), because the bash/terminal tools otherwise run under the Landlock launcher, which sets no_new_privs on every spawned shell and blocks setuid.

Safety rules (hard)

• Never edit or remove anything under /etc/nginx/sites-enabled/ except adding the dsh vhost. The server usually hosts other sites.
• Never write secrets into the repo: deploy.conf, build/, secrets/ are gitignored. Passwords/API keys exist only server-side (root 600) or in the deployer's local deploy.conf.
• Never bind DSH or Authelia to a wildcard interface.
• After deploying, tell the user to change the initial password and (if a key was shared in chat) rotate provider API keys.
• If any step fails, fix the cause and re-run the failing script — every script is idempotent; a fresh full ./deploy.sh must also be safe.

After deployment

• API keys: bash /opt/dsh/scripts/set-deepseek-key.sh sk-... then pick DeepSeek + model in the GUI (Settings → Models).
• GitHub access for the agent (gh/git): bash /opt/dsh/scripts/set-github-token.sh ghp_... — gh auth is per-machine, so the server needs its own PAT; the agent runs as the dsh user with git identity pre-set in /opt/dsh/.gitconfig.
• Upgrade: bash /opt/dsh/scripts/install-dsh.sh <version>.
• Backups: bash /opt/dsh/scripts/backup.sh --install-cron.
• Full runbook: docs/OPERATIONS.md.