kugetsu/docs/kugetsu-setup.md

kugetsu Setup Guide

This guide covers setting up a server/container with kugetsu for remote agent interaction.

Table of Contents

1. Prerequisites
2. Container Setup
3. SSH Setup
4. kugetsu Installation
5. Usage
6. 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

# 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

# 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:

curl -fsSL https://raw.githubusercontent.com/shoko/kugetsu/main/skills/kugetsu/scripts/sshd-setup.sh -o sshd-setup.sh
chmod +x sshd-setup.sh
bash sshd-setup.sh <username>

Or if you have cloned the repository:

chmod +x skills/kugetsu/scripts/sshd-setup.sh
bash skills/kugetsu/scripts/sshd-setup.sh <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

apt-get update && apt-get install -y openssh-server sudo

2. Create non-root user

# 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

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

echo '<username> ALL=(ALL) NOPASSWD: ALL' > /etc/sudoers.d/<username>
chmod 0440 /etc/sudoers.d/<username>

6. Start sshd

systemctl enable sshd
systemctl start sshd

Host-Side Port Forwarding

To access SSH from outside the host, configure port forwarding:

Incus

# 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

# Allow SSH on host
ufw allow 2222/tcp

# Or using iptables
iptables -A INPUT -p tcp --dport 2222 -j ACCEPT

Verify SSH Setup

# 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

curl -fsSL https://raw.githubusercontent.com/shoko/kugetsu/main/skills/kugetsu/scripts/kugetsu-install.sh | bash

Manual Install

# 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

# Create base session (requires TTY)
kugetsu init

Start Task

# Start new session for an issue
kugetsu start <issue-ref> <message>

# Example
kugetsu start github.com/shoko/kugetsu#11 "Implement SSH setup"

Continue Task

# Continue existing session
kugetsu continue <issue-ref> [message]

# Resume with auto-filled last message
kugetsu continue github.com/shoko/kugetsu#11

List Sessions

# List interrupted sessions (default)
kugetsu list

# List all sessions
kugetsu list --all

Destroy Session

# Destroy session for issue
kugetsu destroy <issue-ref> [-y]

# Destroy base session
kugetsu destroy --base [-y]

Help

kugetsu help

---

Remote Access via SSH

Once SSH is configured, you can interact with kugetsu from anywhere:

Basic SSH Access

# 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:

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:

ssh -p 2222 -L 3000:localhost:3000 <username>@<host-ip>

SCP/File Transfer

# 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

# 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)

# 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

# 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 - Full kugetsu documentation
• kugetsu Architecture - Technical details
• Subagent Workflow - Multi-agent orchestration