feat(docs): add ssh sidecar image pipeline and docs

Author: acmore

.github/workflows/sshd-image.yml

@@ -0,0 +1,48 @@
+name: SSHD Sidecar Image
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    tags:
+      - "v*"
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: docker/setup-qemu-action@v3
+      - uses: docker/setup-buildx-action@v3
+
+      - name: Login to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository_owner }}/okdev-sshd
+          tags: |
+            type=raw,value=edge,enable={{is_default_branch}}
+            type=sha,prefix=edge-
+            type=ref,event=tag
+            type=raw,value=latest,enable=${{ startsWith(github.ref, 'refs/tags/v') }}
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: infra/sshd
+          file: infra/sshd/Dockerfile
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

docs/command-reference.md

@@ -23,6 +23,8 @@
 - `okdev use <session>`
 - `okdev connect [--shell /bin/bash] [--cmd "..."] [--no-tty]`
 - `okdev ssh [--setup-key] [--user root] [--cmd "..."]`
+  - SSH target is configured by `spec.ssh.mode` (`dev-container` or `sidecar`).
+  - `okdev` writes managed host aliases to `~/.ssh/config` as `okdev-<session>`.
 - `okdev ports`
 - `okdev sync [--mode up|down|bi] [--background] [--dry-run]`
 - `okdev prune [--ttl-hours 72] [--all-namespaces] [--all-users] [--include-pvc] [--dry-run]`

docs/okdev-design.md

@@ -126,6 +126,8 @@ spec:
     user: root
     remotePort: 22
     localPort: 2222
+    mode: sidecar
+    sidecarImage: ghcr.io/acmore/okdev-sshd:v0.1.0
   podTemplate:
     metadata:
       labels:
@@ -180,7 +182,7 @@ Notes:
 - Pod (or Deployment/StatefulSet later)
 - PVC(s) for workspace/cache
 - ConfigMap/Secret for metadata and credentials
-- Lease annotation/label for ownership and heartbeat
+- Labels/annotations for ownership and metadata
 
 3. **Optional in-pod helper (small sidecar)**
 - Handles optimized sync endpoint and health checks
@@ -224,11 +226,11 @@ Ownership model:
   - scaffolds `.okdev.yaml` from template and detects language/runtime hints
   - supports `-c, --config` to generate a custom config filename/path
 
-- `okdev up [--attach] [--name] [-c|--config]`
+- `okdev up [--no-attach] [--name] [-c|--config]`
   - create or resume session
   - wait for Pod Ready (watch-based readiness events)
-  - optionally connect immediately
-  - with `--attach`, auto-start configured port-forwarding and syncthing in background
+  - by default, attach shell and auto-start configured sync/port-forward/ssh tunnel
+  - with `--no-attach`, skip shell and background integrations
   - supports `--dry-run` to preview operations without applying
   - supports explicit `--session <name>` for multiple concurrent sessions per repo
 
@@ -239,6 +241,8 @@ Ownership model:
 - `okdev ssh [--setup-key] [--cmd]`
   - SSH over auto-managed `kubectl port-forward`
   - optional in-pod public key bootstrap
+  - writes managed host alias (`okdev-<session>`) to `~/.ssh/config`
+  - supports `spec.ssh.mode=sidecar` to avoid requiring sshd in dev container
 
 - `okdev sync [--mode=bi|up|down] [--background] [--dry-run]`
   - syncthing engine: continuous sync for single path mapping
@@ -285,9 +289,9 @@ Ownership model:
 - Sessions are labeled with `okdev.io/owner=<owner>`.
 - Mutating commands refuse non-owner sessions unless session is explicitly marked shareable.
 
-Lease behavior:
-- Session heartbeat is updated in background for long-running commands (`connect`, `ssh`, `ports`, `sync`, and `up --attach`).
-- `okdev down` deletes the Lease object so exclusive sessions can be reacquired immediately.
+Heartbeat behavior:
+- Session heartbeat is updated in background for long-running commands (`connect`, `ssh`, `ports`, `sync`, and `up` default attach flow).
+- No Lease objects are required; implementation remains CRD-less and object-light.
 
 ## 10.1 Multi-Session Model (Multi-Project and Multi-Branch)
 

docs/quickstart.md

@@ -65,6 +65,8 @@ For a named session:
 `okdev` auto-installs local Syncthing and auto-injects a pod sidecar when `sync.engine=syncthing`.
 Default sidecar image tag follows the running `okdev` binary version (`ghcr.io/<repo-owner>/okdev:<okdev-version>`). For dev builds, fallback is `ghcr.io/<repo-owner>/okdev:edge`. Update `spec.sync.syncthing.image` only if you publish to a different registry/repository.
 Use `spec.sync.exclude` for local ignore patterns and `spec.sync.remoteExclude` for remote-only ignore patterns.
+For SSH, default mode is `spec.ssh.mode=dev-container` (your dev image runs sshd). Set `spec.ssh.mode=sidecar` to use `ghcr.io/<repo-owner>/okdev-sshd:<okdev-version>` instead.
+`okdev ssh` and `okdev up` manage `~/.ssh/config` entries as `okdev-<session>`.
 
 Preview-only mode (no cluster changes):
 

docs/release.md

@@ -33,12 +33,16 @@ git push origin v0.1.0
 
 ## Sidecar image tags
 
-The sidecar image tag is aligned with the `okdev` release tag:
+Sidecar image tags are aligned with the `okdev` release tag:
 
-- release `vX.Y.Z` publishes `ghcr.io/acmore/okdev:vX.Y.Z`
-- dev/main pushes publish `ghcr.io/acmore/okdev:edge`
+- release `vX.Y.Z` publishes:
+  - `ghcr.io/acmore/okdev:vX.Y.Z` (syncthing sidecar)
+  - `ghcr.io/acmore/okdev-sshd:vX.Y.Z` (SSH sidecar)
+- dev/main pushes publish:
+  - `ghcr.io/acmore/okdev:edge`
+  - `ghcr.io/acmore/okdev-sshd:edge`
 
-`okdev` resolves default sidecar image from its own binary version, with `edge` fallback for dev builds.
+`okdev` resolves default sidecar images from its own binary version, with `edge` fallback for dev builds.
 
 ## Install from release
 

docs/troubleshooting.md

@@ -26,6 +26,9 @@
 
 ## SSH connect issues
 
-- Ensure an SSH server is running in the dev container.
+- Ensure an SSH server is available:
+  - `spec.ssh.mode=dev-container`: dev container must run sshd.
+  - `spec.ssh.mode=sidecar`: okdev injects `okdev-ssh` sidecar on port 22.
 - Use `okdev ssh --setup-key` once to install your public key in the pod.
 - If port `2222` is busy locally, pass `okdev ssh --local-port <port>`.
+- Check managed SSH alias in `~/.ssh/config` (`Host okdev-<session>`).

infra/sshd/Dockerfile

@@ -0,0 +1,13 @@
+FROM alpine:3.21
+
+RUN apk add --no-cache openssh-server && \
+    mkdir -p /run/sshd /root/.ssh && \
+    chmod 700 /root/.ssh
+
+COPY sshd_config /etc/ssh/sshd_config
+COPY entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+EXPOSE 22
+
+ENTRYPOINT ["/entrypoint.sh"]

infra/sshd/README.md

@@ -0,0 +1,15 @@
+# okdev SSH Sidecar
+
+This image provides an SSH daemon sidecar for `spec.ssh.mode=sidecar`.
+
+Build locally:
+
+```bash
+docker build -f infra/sshd/Dockerfile -t okdev-sshd:dev infra/sshd
+```
+
+Run locally:
+
+```bash
+docker run --rm -p 2222:22 okdev-sshd:dev
+```

infra/sshd/entrypoint.sh

@@ -0,0 +1,13 @@
+#!/bin/sh
+set -eu
+
+mkdir -p /run/sshd /root/.ssh
+chmod 700 /root/.ssh
+touch /root/.ssh/authorized_keys
+chmod 600 /root/.ssh/authorized_keys
+
+if [ ! -f /etc/ssh/ssh_host_ed25519_key ]; then
+  ssh-keygen -A
+fi
+
+exec /usr/sbin/sshd -D -e -f /etc/ssh/sshd_config

infra/sshd/sshd_config

@@ -0,0 +1,16 @@
+Port 22
+Protocol 2
+HostKey /etc/ssh/ssh_host_rsa_key
+HostKey /etc/ssh/ssh_host_ecdsa_key
+HostKey /etc/ssh/ssh_host_ed25519_key
+PermitRootLogin prohibit-password
+PasswordAuthentication no
+KbdInteractiveAuthentication no
+ChallengeResponseAuthentication no
+UsePAM no
+PubkeyAuthentication yes
+AuthorizedKeysFile .ssh/authorized_keys
+ClientAliveInterval 180
+ClientAliveCountMax 2
+PidFile /run/sshd/sshd.pid
+Subsystem sftp internal-sftp