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 (Debian/Ubuntu)
incus launch images:debian/12 <container-name>

# Or create Fedora container
incus launch images:fedora/43 <container-name>

# Or use an existing container
incus exec <container-name> -- bash

# Ensure systemd is installed
# For Debian/Ubuntu:
incus exec <container-name> -- apt-get update
incus exec <container-name> -- apt-get install -y systemd

# For Fedora:
incus exec <container-name> -- dnf install -y systemd

# Enable systemd in container (Incus specific - verify with your setup)
incus config set <container-name> 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 <username>

Replace <username> 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:

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

Fedora/RHEL/CentOS:

dnf install -y openssh-server sudo

2. Verify installation

which sshd
sshd -V

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

# 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

# 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

---

Remote Access via Tailscale (Optional)

Tailscale provides VPN access without requiring a public IP on the host. Each container gets its own unique Tailscale IP and can be accessed from any device on your Tailscale network.

Why Tailscale?

	Port Forwarding	Tailscale
Public IP required	Yes	No
Firewall config	Needed	Not needed
Cross-network access	Limited	Full
Setup complexity	Higher	Lower

Automated Setup

Run the Tailscale setup script inside your container:

chmod +x skills/kugetsu/scripts/tailscale-setup.sh
bash skills/kugetsu/scripts/tailscale-setup.sh <username> <device-name>

Arguments:

• <username>: SSH user that will be created (defaults to current user)
• <device-name>: Tailscale hostname (defaults to current hostname)

Authentication Methods

The script will prompt you to choose:

1. AUTHKEY (Recommended for automation)

• Pre-generate an auth key from: https://login.tailscale.com/admin/settings/keys
• Click "Generate auth key", copy the key (starts with tskey-auth-)
• Paste it when prompted

2. Headless (Browser-based)

• Script will show a login URL
• Open the URL in your browser and authenticate
• Return to complete setup

After Setup

1. Install Tailscale on your other devices: https://tailscale.com/download
2. Log in with the same Tailscale account
3. Connect via SSH using your device name:

   ssh <username>@<device-name>
   

Or use the Tailscale IP directly:

ssh <username>@<tailscale-ip>

Verify Connection

Inside the container:

tailscale status
tailscale ip -4

Tailscale + SSH

Tailscale handles the network connection. Once connected via Tailscale, you can SSH normally and use kugetsu:

ssh <username>@<device-name>
kugetsu list
kugetsu start github.com/shoko/kugetsu#11 "Fix bug"

Uninstall Tailscale

sudo systemctl stop tailscaled
sudo systemctl disable tailscaled
sudo dnf remove tailscale  # Fedora
# or
sudo apt remove tailscale  # Debian/Ubuntu

---

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 (if repo is cloned on container)
ssh -p 2222 <username>@<host-ip> 'bash ~/path/to/kugetsu/skills/kugetsu/scripts/kugetsu-install.sh'

---

See Also

• kugetsu Skill - Full kugetsu documentation
• kugetsu Architecture - Technical details
• Subagent Workflow - Multi-agent orchestration