docs/kugetsu-setup.md

@@ -0,0 +1,327 @@
+# kugetsu Setup Guide
+
+This guide covers setting up a server/container with kugetsu for remote agent interaction.
+
+## Table of Contents
+
+1. [Prerequisites](#prerequisites)
+2. [Container Setup](#container-setup)
+3. [SSH Setup](#ssh-setup)
+4. [kugetsu Installation](#kugetsu-installation)
+5. [Usage](#usage)
+6. [Remote Access via SSH](#remote-access-via-ssh)
+
+---
+
+## Prerequisites
+
+- Linux container (Incus, Docker, Podman, etc.)
+- systemd available inside container
+- SSH key for authentication (RSA, ED25519, or ECDSA)
+
+---
+
+## Container Setup
+
+### Incus
+
+```bash
+# Create container
+incus launch images:debian/12 <container-name>
+
+# Or use an existing container
+incus exec <container-name> -- bash
+
+# Ensure systemd is installed (Debian/Ubuntu)
+incus exec <container-name> -- apt-get update
+incus exec <container-name> -- apt-get install -y systemd
+
+# Enable systemd as PID 1 (if using systemd in container)
+incus config set <container-name> init.launchd.systemd true
+```
+
+### Docker/Podman
+
+```bash
+# Use an image with systemd support
+docker run -d --name <container-name> \
+  --systemd=always \
+  -v /sys/fs/cgroup:/sys/fs/cgroup:rw \
+  debian:12 \
+  /sbin/init
+```
+
+---
+
+## SSH Setup
+
+### Quick Setup (Automated)
+
+Run the setup script inside your container:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/shoko/kugetsu/main/skills/kugetsu/scripts/sshd-setup.sh | bash -s -- <username>
+```
+
+Replace `<username>` with your preferred username, or omit to use default `kugetsu`.
+
+### Manual Setup
+
+If you prefer to set up SSH manually:
+
+#### 1. Install openssh-server
+
+```bash
+apt-get update && apt-get install -y openssh-server sudo
+```
+
+#### 2. Create non-root user
+
+```bash
+# Create user (e.g., 'agent')
+useradd -m -s /bin/bash agent
+
+# Or use an existing user
+```
+
+#### 3. Configure SSH
+
+Edit `/etc/ssh/sshd_config`:
+
+```
+PasswordAuthentication no
+PubkeyAuthentication yes
+PermitRootLogin no
+```
+
+#### 4. Add SSH public key
+
+```bash
+mkdir -p /home/<username>/.ssh
+chmod 700 /home/<username>/.ssh
+echo 'YOUR_PUBLIC_KEY' >> /home/<username>/.ssh/authorized_keys
+chmod 600 /home/<username>/.ssh/authorized_keys
+chown -R <username>:<username> /home/<username>/.ssh
+```
+
+#### 5. Configure sudo for passwordless access
+
+```bash
+echo '<username> ALL=(ALL) NOPASSWD: ALL' > /etc/sudoers.d/<username>
+chmod 0440 /etc/sudoers.d/<username>
+```
+
+#### 6. Start sshd
+
+```bash
+systemctl enable sshd
+systemctl start sshd
+```
+
+### Host-Side Port Forwarding
+
+To access SSH from outside the host, configure port forwarding:
+
+#### Incus
+
+```bash
+# On the HOST (not inside container)
+incus config device add <container-name> sshd proxy listen=tcp:0.0.0.0:2222 connect=tcp:127.0.0.1:22
+```
+
+#### Firewall
+
+```bash
+# Allow SSH on host
+ufw allow 2222/tcp
+
+# Or using iptables
+iptables -A INPUT -p tcp --dport 2222 -j ACCEPT
+```
+
+### Verify SSH Setup
+
+```bash
+# Test connection from host to container
+ssh -p 2222 <username>@localhost
+
+# Verify sudo access
+ssh -p 2222 <username>@localhost sudo systemctl status sshd
+```
+
+---
+
+## kugetsu Installation
+
+### Automated Install
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/shoko/kugetsu/main/skills/kugetsu/scripts/kugetsu-install.sh | bash
+```
+
+### Manual Install
+
+```bash
+# Clone repository
+git clone https://git.fbrns.co/shoko/kugetsu.git
+
+# Run install script
+bash kugetsu/skills/kugetsu/scripts/kugetsu-install.sh
+
+# Reload shell or source bashrc
+source ~/.bashrc
+```
+
+---
+
+## Usage
+
+kugetsu provides session management for opencode.
+
+### Initialize
+
+```bash
+# Create base session (requires TTY)
+kugetsu init
+```
+
+### Start Task
+
+```bash
+# Start new session for an issue
+kugetsu start <issue-ref> <message>
+
+# Example
+kugetsu start github.com/shoko/kugetsu#11 "Implement SSH setup"
+```
+
+### Continue Task
+
+```bash
+# Continue existing session
+kugetsu continue <issue-ref> [message]
+
+# Resume with auto-filled last message
+kugetsu continue github.com/shoko/kugetsu#11
+```
+
+### List Sessions
+
+```bash
+# List interrupted sessions (default)
+kugetsu list
+
+# List all sessions
+kugetsu list --all
+```
+
+### Destroy Session
+
+```bash
+# Destroy session for issue
+kugetsu destroy <issue-ref> [-y]
+
+# Destroy base session
+kugetsu destroy --base [-y]
+```
+
+### Help
+
+```bash
+kugetsu help
+```
+
+---
+
+## Remote Access via SSH
+
+Once SSH is configured, you can interact with kugetsu from anywhere:
+
+### Basic SSH Access
+
+```bash
+# Connect to container
+ssh -p 2222 <username>@<host-ip>
+
+# Run kugetsu commands
+kugetsu list
+kugetsu start github.com/shoko/kugetsu#11 "Fix bug"
+```
+
+### Spawn and Forget
+
+For long-running tasks, SSH and spawn:
+
+```bash
+ssh -p 2222 <username>@<host-ip> \
+  "kugetsu start github.com/shoko/kugetsu#11 'Implement feature' && echo 'Task done' | tee /tmp/task.log"
+```
+
+### Port Forwarding for Web UI
+
+If opencode has a web UI:
+
+```bash
+ssh -p 2222 -L 3000:localhost:3000 <username>@<host-ip>
+```
+
+### SCP/File Transfer
+
+```bash
+# Copy files from container
+scp -P 2222 <username>@<host-ip>:/path/in/container ./local-path
+
+# Copy files to container
+scp -P 2222 ./local-file <username>@<host-ip>:/path/in/container
+```
+
+---
+
+## Security Notes
+
+- **Key-only authentication**: Password authentication is disabled
+- **Non-root user**: SSH user has limited privileges but can sudo
+- **Firewall**: Only port 2222 is exposed (not 22 on host)
+- **Container isolation**: Host filesystem is protected by container boundaries
+
+---
+
+## Troubleshooting
+
+### SSH Connection Refused
+
+```bash
+# Check sshd status inside container
+ssh -p 2222 <username>@<host-ip> sudo systemctl status sshd
+
+# Restart sshd
+ssh -p 2222 <username>@<host-ip> sudo systemctl restart sshd
+```
+
+### Permission Denied (Public Key)
+
+```bash
+# Verify authorized_keys on container
+ssh -p 2222 <username>@<host-ip> cat ~/.ssh/authorized_keys
+
+# Check key permissions
+ssh -p 2222 <username>@<host-ip> ls -la ~/.ssh/
+```
+
+### kugetsu Command Not Found
+
+```bash
+# Check PATH
+ssh -p 2222 <username>@<host-ip> 'echo $PATH'
+
+# Re-run install
+ssh -p 2222 <username>@<host-ip> 'bash ~/.kugetsu/scripts/kugetsu-install.sh'
+```
+
+---
+
+## See Also
+
+- [kugetsu Skill](../skills/kugetsu/SKILL.md) - Full kugetsu documentation
+- [kugetsu Architecture](kugetsu-architecture.md) - Technical details
+- [Subagent Workflow](SUBAGENT_WORKFLOW.md) - Multi-agent orchestration

skills/kugetsu/scripts/sshd-setup.sh

@@ -0,0 +1,79 @@
+#!/bin/bash
+set -euo pipefail
+
+USERNAME="${1:-kugetsu}"
+
+echo "=== kugetsu SSH Setup ==="
+echo "Target user: $USERNAME"
+echo ""
+
+if ! command -v systemctl &> /dev/null; then
+    echo "ERROR: systemd not found."
+    echo ""
+    echo "This script requires systemd to be installed and running inside the container."
+    echo "Please install systemd first:"
+    echo "    apt-get update && apt-get install -y systemd"
+    echo ""
+    echo "If you are running in a container that doesn't support systemd, consider:"
+    echo "    - Using a container image with systemd support"
+    echo "    - Running sshd directly (without systemd) - manual setup required"
+    exit 1
+fi
+
+echo "[1/6] Updating package lists..."
+apt-get update -qq
+
+echo "[2/6] Installing openssh-server..."
+apt-get install -y -qq openssh-server sudo
+
+echo "[3/6] Creating user '$USERNAME' if not exists..."
+if ! id "$USERNAME" &> /dev/null; then
+    useradd -m -s /bin/bash "$USERNAME"
+    echo "User '$USERNAME' created."
+else
+    echo "User '$USERNAME' already exists."
+fi
+
+echo "[4/6] Configuring SSH for key-only authentication..."
+SSHD_CONFIG="/etc/ssh/sshd_config"
+sed -i 's/^#*PasswordAuthentication.*/PasswordAuthentication no/' "$SSHD_CONFIG"
+sed -i 's/^#*PubkeyAuthentication.*/PubkeyAuthentication yes/' "$SSHD_CONFIG"
+sed -i 's/^#*PermitRootLogin.*/PermitRootLogin no/' "$SSHD_CONFIG"
+echo "SSH configured: key-only auth, root login disabled."
+
+echo "[5/6] Configuring sudo for passwordless access..."
+SUDOERS_FILE="/etc/sudoers.d/$USERNAME"
+echo "$USERNAME ALL=(ALL) NOPASSWD: ALL" > "$SUDOERS_FILE"
+chmod 0440 "$SUDOERS_FILE"
+echo "Sudo configured: $USERNAME can run sudo without password."
+
+echo "[6/6] Enabling and starting sshd..."
+systemctl enable sshd
+systemctl restart sshd
+
+if systemctl is-active --quiet sshd; then
+    echo "sshd is running."
+else
+    echo "WARNING: sshd may not have started correctly. Check with: systemctl status sshd"
+fi
+
+echo ""
+echo "=== Setup Complete ==="
+echo ""
+echo "Next steps:"
+echo ""
+echo "1. Add your SSH public key to authorized_keys:"
+echo "   mkdir -p /home/$USERNAME/.ssh"
+echo "   chmod 700 /home/$USERNAME/.ssh"
+echo "   echo 'YOUR_PUBLIC_KEY' >> /home/$USERNAME/.ssh/authorized_keys"
+echo "   chmod 600 /home/$USERNAME/.ssh/authorized_keys"
+echo "   chown -R $USERNAME:$USERNAME /home/$USERNAME/.ssh"
+echo ""
+echo "2. Connect from remote:"
+echo "   ssh -p 2222 $USERNAME@<container-host-ip>"
+echo ""
+echo "   (Requires host-side port forwarding - see docs/kugetsu-setup.md)"
+echo ""
+echo "3. Verify SSH access:"
+echo "   ssh -p 2222 $USERNAME@<container-host-ip> sudo systemctl status sshd"
+echo ""