From 7fb9b9c5818436008d54b1be71a55129036a8d8f Mon Sep 17 00:00:00 2001 From: shokollm <270575765+shokollm@users.noreply.github.com> Date: Mon, 30 Mar 2026 03:37:07 +0000 Subject: [PATCH] feat(issue-11): add SSH setup script and kugetsu-setup documentation - Add sshd-setup.sh: automated SSH setup inside container - Checks for systemd prerequisite - Creates non-root user (configurable via argument, fallback to 'kugetsu') - Configures sshd for key-only authentication - Configures passwordless sudo for the user - Enables and starts sshd via systemd - Add docs/kugetsu-setup.md: unified setup documentation - Container setup (Incus, Docker) - SSH setup (automated + manual steps) - Host-side port forwarding (Incus, firewall) - kugetsu installation - Usage guide - Remote access via SSH --- docs/kugetsu-setup.md | 327 +++++++++++++++++++++++++++ skills/kugetsu/scripts/sshd-setup.sh | 79 +++++++ 2 files changed, 406 insertions(+) create mode 100644 docs/kugetsu-setup.md create mode 100755 skills/kugetsu/scripts/sshd-setup.sh diff --git a/docs/kugetsu-setup.md b/docs/kugetsu-setup.md new file mode 100644 index 0000000..823269e --- /dev/null +++ b/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 + +# Or use an existing container +incus exec -- bash + +# Ensure systemd is installed (Debian/Ubuntu) +incus exec -- apt-get update +incus exec -- apt-get install -y systemd + +# Enable systemd as PID 1 (if using systemd in container) +incus config set init.launchd.systemd true +``` + +### Docker/Podman + +```bash +# Use an image with systemd support +docker run -d --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 -- +``` + +Replace `` 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//.ssh +chmod 700 /home//.ssh +echo 'YOUR_PUBLIC_KEY' >> /home//.ssh/authorized_keys +chmod 600 /home//.ssh/authorized_keys +chown -R : /home//.ssh +``` + +#### 5. Configure sudo for passwordless access + +```bash +echo ' ALL=(ALL) NOPASSWD: ALL' > /etc/sudoers.d/ +chmod 0440 /etc/sudoers.d/ +``` + +#### 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 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 @localhost + +# Verify sudo access +ssh -p 2222 @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 + +# Example +kugetsu start github.com/shoko/kugetsu#11 "Implement SSH setup" +``` + +### Continue Task + +```bash +# Continue existing session +kugetsu continue [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 [-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 @ + +# 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 @ \ + "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 @ +``` + +### SCP/File Transfer + +```bash +# Copy files from container +scp -P 2222 @:/path/in/container ./local-path + +# Copy files to container +scp -P 2222 ./local-file @:/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 @ sudo systemctl status sshd + +# Restart sshd +ssh -p 2222 @ sudo systemctl restart sshd +``` + +### Permission Denied (Public Key) + +```bash +# Verify authorized_keys on container +ssh -p 2222 @ cat ~/.ssh/authorized_keys + +# Check key permissions +ssh -p 2222 @ ls -la ~/.ssh/ +``` + +### kugetsu Command Not Found + +```bash +# Check PATH +ssh -p 2222 @ 'echo $PATH' + +# Re-run install +ssh -p 2222 @ '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 \ No newline at end of file diff --git a/skills/kugetsu/scripts/sshd-setup.sh b/skills/kugetsu/scripts/sshd-setup.sh new file mode 100755 index 0000000..1eca205 --- /dev/null +++ b/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@" +echo "" +echo " (Requires host-side port forwarding - see docs/kugetsu-setup.md)" +echo "" +echo "3. Verify SSH access:" +echo " ssh -p 2222 $USERNAME@ sudo systemctl status sshd" +echo "" \ No newline at end of file