homelab-agents/QUICK-START.md

Quick Start: Setting Up Agents on a New VPS

Initial Setup (One-Time)

Run this once on your new VPS to bootstrap agents and helper tools:

source <(curl -s http://100.120.125.113:3000/pdm/homelab-agents/raw/branch/main/scripts/bootstrap-agents.sh)

This:

• ✅ Clones homelab-agents to ~/.homelab-agents
• ✅ Installs helper scripts to ~/.homelab-scripts
• ✅ Sets up git configuration
• ✅ Makes agents and commands available immediately

Creating a New Project

Step 1: Create Repository on Gitea (One-time per project)

Go to http://100.120.125.113:3000/repo/create and create a new repository:

• Repository name: my-new-app (must match your project name)
• Visibility: Public or Private (your choice)
• Initialize repository: Optional (leave unchecked, init-project will set it up)

Step 2: Initialize Project Locally

From your projects directory:

cd ~/projects
init-project my-new-app

This:

• ✅ Creates my-new-app directory
• ✅ Initializes git repository
• ✅ Configures SSH remote to your Gitea repo
• ✅ Copies agents to .claude/agents/
• ✅ Sets git user config
• ✅ Ready to start work

Working on a Project

cd ~/projects/my-new-app

# Do your work...
# Add files, make changes, etc.

# When done, close the session with the summary agent
# The agent will:
# - Commit all changes with descriptive message
# - Create session summary
# - Automatically push to Gitea via SSH

Agent Auto-Updates

Every time you run bootstrap:

source <(curl -s http://100.120.125.113:3000/pdm/homelab-agents/raw/branch/main/scripts/bootstrap-agents.sh)

It will:

• ✅ Pull latest agent versions
• ✅ Install latest helper scripts
• ✅ Keep your tools synchronized

Available Commands

After bootstrap:

init-project <name>     # Initialize a new project (repo must exist on Gitea)

Available Agents

Current agents in the repository:

• finish-up - Closes sessions and creates session summaries with VPS hostname
• Located at: ~/.homelab-agents/agents/ or .claude/agents/ in your project

Project Structure

Your typical VPS layout:

~/projects/
├── project-1/
│   ├── .git (remote: git@100.120.125.113:pdm/project-1.git)
│   └── .claude/agents/ (agents for Claude Code)
├── project-2/
│   ├── .git (remote: git@100.120.125.113:pdm/project-2.git)
│   └── .claude/agents/
└── project-3/
    ├── .git (remote: git@100.120.125.113:pdm/project-3.git)
    └── .claude/agents/

Each project is independent with its own Gitea repository and local agents.

Workflow Summary

1. ✅ Bootstrap (once per VPS): source <(curl -s ...bootstrap-agents.sh)
2. ✅ Create Repo on Gitea (once per project): http://100.120.125.113:3000/repo/create
3. ✅ Init Project (once per project): init-project my-app
4. ✅ Work: Create files, make changes
5. ✅ Close Session: Use summary agent → auto-commits & pushes
6. ✅ Resume: Clone from Gitea next time

SSH Key Setup

For git push to work, your VPS needs an SSH key configured on Gitea:

1. Generate key: ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -N ""
2. Get public key: cat ~/.ssh/id_ed25519.pub
3. Add to Gitea: http://100.120.125.113:3000/user/settings/keys
4. Test: ssh -T git@100.120.125.113

See SSH-SETUP.md for detailed instructions.

For detailed information, see:

• README.md - Overview and structure
• scripts/README.md - Script documentation
• SSH-SETUP.md - SSH key configuration
• agents/README.md - Available agents