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](#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 <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:**
```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/<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
# 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 <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
```

---

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

```bash
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:
   ```bash
   ssh <username>@<device-name>
   ```

Or use the Tailscale IP directly:
```bash
ssh <username>@<tailscale-ip>
```

### Verify Connection

Inside the container:
```bash
tailscale status
tailscale ip -4
```

### Tailscale + SSH

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

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

### Uninstall Tailscale

```bash
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

```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 (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](../skills/kugetsu/SKILL.md) - Full kugetsu documentation
- [kugetsu Architecture](kugetsu-architecture.md) - Technical details
- [Subagent Workflow](SUBAGENT_WORKFLOW.md) - Multi-agent orchestration