skz-void/AGENTS.md

Agent Guide

This repository builds and deploys OpenBSD VPN servers on Google Cloud. The goal is to make it easy to create multiple VPN VMs in two flavors:

• WireGuard, matching the existing historical deployment in server/.
• IPsec, using OpenBSD iked/ipsecctl.

Keep this repository focused on VPN server definitions, provisioning glue, firewall rules, and run commands. The local skz-opack/ directory is an ignored dependency that provides the OpenBSD image/build/deploy Makefile interface. Read it when you need to understand OPACK_* variables or targets, but do not modify it unless the user explicitly asks for dependency work.

Repository Shape

• server/ is the current WireGuard deployment. It includes the OpenBSD install disklabel, provisioning script, GCP firewall overlay, and Makefile using ../skz-opack/src/opack.mk.
• src/ is early IPsec/iked work and should stay separate from WireGuard-specific provisioning.
• Future VPN servers should live in separate directories or separate Makefiles. Do not merge WireGuard and IPsec into one opaque shared Makefile until real duplication justifies it.
• Each server definition should declare its own OPACK_TARGET, hostname, GCP project/key settings, provision script, firewall rules, client list, and generated-state ignore patterns.

Tools And Installation

Before build or deployment work, verify the required host tools:

for x in make jq python3 rg curl git ssh scp nc vagrant packer terraform gcloud qemu-system-x86_64; do command -v "$x" || echo "missing: $x"; done

In sloptrap/Codex containers, install missing third-party tools under /sloptrap-tools and expose executables through /sloptrap-tools/bin, which is already on PATH. Do not install toolchains into this repo, $HOME, or one-off directories.

Use /sloptrap-tools for SDKs, plugins, and caches when configurable. For example, a Google Cloud SDK install may live under /sloptrap-tools/google-cloud-sdk with /sloptrap-tools/bin/gcloud symlinked to the real executable. Keep Packer plugin caches and similar generated tool state under /sloptrap-tools when possible.

Secrets And Live State

server/ may contain ignored live credentials and generated deployment state:

• id_ed25519
• skz-void-bbb88f038188.json
• opack-cloud
• opack_deploy_*
• opack_installer_*

Never commit, print, copy into tracked files, rotate, delete, or regenerate these files unless the user explicitly asks. Treat them as live operational material.

Agents may SSH for read-only diagnostics when useful, using the ignored key and current deployed IP:

ssh -i server/id_ed25519 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null root@$(cat server/opack-cloud) 'uname -a; sysctl kern.version'

Do not change services, firewall rules, VPN keys, GCP resources, package state, or deployed configuration on the live VM without explicit user approval.

Workflows

For existing WireGuard deployment work, the main entrypoint is:

make -C server void

This is not a harmless check. It may build an OpenBSD image, run Terraform, apply firewall rules, copy the external skz-wg tree to the live VM, and run remote provisioning. Use it only when the user wants deployment or provisioning work.

For read-only live inspection, prefer direct SSH commands and report exactly what was inspected. Avoid broad commands that dump secrets or large config files.

For future IPsec work, use OpenBSD-native iked/ipsecctl conventions. Keep IPsec provisioning, firewall rules, client/certificate generation, and run targets separate from WireGuard. Make IPsec firewall allowances explicit instead of reusing the WireGuard UDP rule.

For future multi-server work, prefer adding a new isolated server directory or Makefile that includes ../skz-opack/src/opack.mk and overrides OPACK_* values before the include. Keep generated files ignored next to the server that creates them.

Validation

For documentation-only changes, validate with:

sed -n '1,240p' AGENTS.md
git diff -- AGENTS.md

Do not run deployment targets as documentation validation.

For Makefile/provisioning changes, use the narrowest non-destructive validation first, such as reading expanded Make variables, shell syntax checks, or targeted dry-run inspection. Treat make ... opack-cloud, make -C server void, Terraform apply/destroy, and remote provisioning commands as live infrastructure changes.