7fb9b9c581
- 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
327 lines
6.1 KiB
Markdown
327 lines
6.1 KiB
Markdown
# 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 <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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
curl -fsSL https://raw.githubusercontent.com/shoko/kugetsu/main/skills/kugetsu/scripts/sshd-setup.sh | bash -s -- <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
|
|
|
|
```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/<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
|
|
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 <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
|
|
```
|
|
|
|
---
|
|
|
|
## 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
|
|
ssh -p 2222 <username>@<host-ip> '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 |