VPS Skills Sync Setup

Step 1 of 5

Back up the VPS library

Treat the existing VPS library as the initial source of truth. Make a timestamped copy before adding Git metadata.

test -d ~/.agents
backup_dir="$HOME/.agents.backup.$(date +%Y%m%d-%H%M%S)"
cp -a ~/.agents "$backup_dir"
echo "Backup: $backup_dir"

Nothing is deleted or moved. Keep this backup until both machines have completed several successful syncs.

Step 2 of 5

Create the private Git source

Authenticate GitHub CLI over HTTPS first. Its credential helper remains available to the background timer without an SSH agent.

gh auth status || gh auth login
gh config set git_protocol https
gh auth setup-git

Then initialize ~/.agents directly so the repository contains the library contents—not an extra wrapper directory. Exclude credentials before the first commit.

cd ~/.agents
test -d .git || git init -b main
printf '%s
' '.env' '.env.*' '*.key' '*.pem' '*token*' '*secret*' >> .gitignore
git config user.name "YOUR_NAME"
git config user.email "YOUR_EMAIL"
git add -A
git commit -m "chore: initialize shared agent skills"
gh repo create code-os-skills --private --source=. --remote=origin --push

Keep the repository private. Never include Cloudflare tokens, dashboard credentials, bypass keys, SSH keys, or machine-specific environment files.

If the private repository already exists, replace the final command with git remote add origin https://github.com/YOUR_ACCOUNT/code-os-skills.git and git push -u origin main.

Step 3 of 5

Configure and test synchronization

Open /app/settings and set the private GitHub repository URL, ~/.agents checkout, and branch. The built-in worker commits local changes, rebases, and pushes. A directory lock prevents overlapping executions.

code-os skills-sync
git -C ~/.agents status --short --branch

Step 4 of 5

Enable Code OS and the timer

The service installer starts Code OS now, enables it after every reboot, and creates the two-minute skills-sync timer from the same configuration. It also enables systemd user lingering so neither service depends on an interactive SSH login.

code-os service install
code-os doctor

Step 5 of 5

Verify the VPS side

Trigger one execution, inspect its log, and confirm that the checkout is clean and tracking origin/main.

systemctl --user start code-os-skills-sync.service
journalctl --user -u code-os-skills-sync.service -n 30 --no-pager
git -C ~/.agents status --short --branch
systemctl --user list-timers code-os-skills-sync.timer
loginctl show-user "$USER" -p Linger

A healthy run ends with “is up to date.” If Git reports a conflict, the worker stops without discarding either side.

If Git reports a conflict

The worker stops and will not stage anything else while a rebase, merge, or unresolved file exists. Inspect the files and choose one path:

git -C ~/.agents status

# Keep the rebase and resolve each reported file
git -C ~/.agents add PATH_TO_RESOLVED_FILE
git -C ~/.agents rebase --continue
~/.local/bin/code-os-skills-sync

# Or return to the exact state before the pull
git -C ~/.agents rebase --abort

NEXT SIDEConfigure your computer

Open guide