# 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 (Debian/Ubuntu) incus launch images:debian/12 # Or create Fedora container incus launch images:fedora/43 # Or use an existing container incus exec -- bash # Ensure systemd is installed # For Debian/Ubuntu: incus exec -- apt-get update incus exec -- apt-get install -y systemd # For Fedora: incus exec -- dnf install -y systemd # Enable systemd in container (Incus specific - verify with your setup) incus config set security.syscalls.intercept.systemd true > **Note:** Container must be privileged or have CAP_SYS_ADMIN for systemd features. > The exact command may vary by Incus version - check Incus documentation for your setup. --- ## SSH Setup ### Automated Setup Run the setup script inside your container: ```bash chmod +x skills/kugetsu/scripts/sshd-setup.sh bash skills/kugetsu/scripts/sshd-setup.sh ``` Replace `` with your preferred username, or omit to use default `kugetsu`. **The script automatically detects your OS and installs the correct packages.** Supported OSes: Debian, Ubuntu, Fedora, RHEL, CentOS ### Manual Setup If you prefer to set up SSH manually: #### 1. Install openssh-server **Debian/Ubuntu:** ```bash apt-get update && apt-get install -y openssh-server sudo ``` **Fedora/RHEL/CentOS:** ```bash dnf install -y openssh-server sudo ``` #### 2. Verify installation ```bash which sshd sshd -V ``` #### 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 # If you have cloned the repository bash 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 (if repo is cloned on container) ssh -p 2222 @ 'bash ~/path/to/kugetsu/skills/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