# Runbook: Configure Assistant SSH Access

## Purpose

Set up SSH access so Pi can administer homelab systems using a dedicated key and user.

## Safety Rules

- Never share or paste a private key.
- It is safe to share/install the `.pub` public key.
- Prefer a dedicated user such as `piagent` instead of using your personal account.
- Prefer guest VM access over direct Proxmox host access where possible.
- Keep Proxmox access cautious; destructive actions should require confirmation.

## Option A: Generate key on your machine

Run this on the machine/container where Pi will execute SSH from:

```bash
ssh-keygen -t ed25519 -f ~/.ssh/piagent_homelab -C piagent-homelab
```

Show the public key:

```bash
cat ~/.ssh/piagent_homelab.pub
```

Only the output ending in `.pub` should be installed on servers.

## Option B: Use an existing key

If you already have a key you want Pi to use, use the existing public key:

```bash
cat ~/.ssh/id_ed25519.pub
```

Do not expose `~/.ssh/id_ed25519` itself.

## Create a dedicated user on a Debian/Ubuntu VM

On the target VM, as root or with sudo:

```bash
sudo useradd --create-home --shell /bin/bash piagent
sudo passwd -l piagent
sudo mkdir -p /home/piagent/.ssh
sudo nano /home/piagent/.ssh/authorized_keys
```

Paste the public key into `authorized_keys`, then fix permissions:

```bash
sudo chown -R piagent:piagent /home/piagent/.ssh
sudo chmod 700 /home/piagent/.ssh
sudo chmod 600 /home/piagent/.ssh/authorized_keys
```

Optional: allow sudo for admin work:

```bash
sudo usermod -aG sudo piagent
```

If you want passwordless sudo for this assistant user, create:

```bash
sudo visudo -f /etc/sudoers.d/piagent
```

Add:

```text
piagent ALL=(ALL) NOPASSWD:ALL
```

For higher security, skip passwordless sudo and approve commands manually.

## Create a dedicated user on Proxmox

On the Proxmox host shell, as root:

```bash
useradd --create-home --shell /bin/bash piagent
passwd -l piagent
mkdir -p /home/piagent/.ssh
nano /home/piagent/.ssh/authorized_keys
```

Paste the public key, then:

```bash
chown -R piagent:piagent /home/piagent/.ssh
chmod 700 /home/piagent/.ssh
chmod 600 /home/piagent/.ssh/authorized_keys
```

For Proxmox, decide carefully before granting sudo/root-like permissions. Prefer read-mostly access unless we need to create/manage VMs.

## Test SSH access

From the Pi execution environment:

```bash
ssh -i ~/.ssh/piagent_homelab piagent@SERVER_IP_OR_HOSTNAME
```

Expected result: login without a password prompt.

## Configure Pi host aliases

Edit `.pi/ssh/hosts.json` and add entries like:

```json
{
  "allowRawHosts": false,
  "defaultConfirmDestructive": true,
  "hosts": {
    "pve1": {
      "remote": "piagent@PROXMOX_IP_OR_HOSTNAME",
      "remoteCwd": "/home/piagent",
      "description": "Primary Proxmox host",
      "roles": ["proxmox", "hypervisor"],
      "allowWrite": false,
      "allowBash": true,
      "confirmDestructive": true
    },
    "nextcloud-vm": {
      "remote": "piagent@NEXTCLOUD_VM_IP_OR_HOSTNAME",
      "remoteCwd": "/home/piagent",
      "description": "Nextcloud guest VM",
      "roles": ["nextcloud", "vm"],
      "allowWrite": true,
      "allowBash": true,
      "confirmDestructive": true
    }
  }
}
```

Replace `PROXMOX_IP_OR_HOSTNAME` and `NEXTCLOUD_VM_IP_OR_HOSTNAME`.

## Recommended setup for this project

1. Create/use key: `~/.ssh/piagent_homelab`
2. Add public key to Proxmox `piagent` user if you want Pi to help inspect/create VMs.
3. Add public key to the Nextcloud VM `piagent` user for day-to-day administration.
4. Start Pi with SSH alias when needed:

```bash
pi --ssh nextcloud-vm
```

or:

```bash
pi --ssh pve1
```

## Assistant SSH Lifecycle Checklists

Use these checklists for future hosts. Do not test first on production systems; the first full lifecycle test was performed on disposable LXC `access-pilot` / CTID `102` and then destroyed.

### Grant Assistant SSH Access

1. Confirm host is in scope and rollback is available.
2. Use a dedicated assistant account, normally `piagent`.
3. Install only the assistant public key; never copy private keys to the host.
4. Lock the assistant account password.
5. Grant only required sudo or service permissions.
6. Add or update a named alias in `.pi/ssh/hosts.json` if the host should remain managed.
7. Keep raw SSH hosts disabled unless deliberately approved.
8. Verify non-interactive SSH login.
9. Verify required sudo/service command behavior if granted.
10. Log the change in `docs/server-change-log.md` without secret values.

### Rotate Assistant SSH Access

1. Add the replacement public key before removing the old one.
2. Verify login succeeds with the replacement key.
3. Remove the old public key from `authorized_keys`.
4. Verify the old key no longer works.
5. Verify the replacement key still works.
6. Update local SSH alias/key references if needed.
7. Log the rotation.

### Revoke Assistant SSH Access

1. Remove assistant public keys from `authorized_keys`.
2. Remove or disable passwordless sudo if present.
3. Lock, expire, or remove the assistant account if it should no longer exist.
4. Remove or disable the `.pi/ssh/hosts.json` alias if management should stop.
5. Verify revoked access fails.
6. Log the revocation and rollback notes.

### Disposable Pilot Notes

The disposable SSH lifecycle pilot should use a throwaway Debian/Ubuntu VM or LXC and should prove:

- grant works
- sudo policy works if granted
- rotation works before old key removal
- old key fails after rotation
- full revocation fails as expected
- the disposable host can be destroyed or reverted

Do not use Nextcloud, AMP, Proxmox, OPNsense, Home Assistant, or user workstations as the first lifecycle test target.