NAS-Based Development Setup Guide

For new machines joining the BlueFly.io development environment

Prerequisites

1. NAS Access

   • NFS mount to AgentPlatform volume
   • Mount point: /Volumes/AgentPlatform/ (macOS)
   • NAS IP: 192.168.68.54 (or blueflynas.tailcf98b3.ts.net via Tailscale)

2. Tailscale

   • Installed and authenticated
   • Connected to tailcf98b3.ts.net
   • Subnet routing enabled for 192.168.8.0/24

3. GitLab Access

   • GitLab token configured (~/.tokens/gitlab-token)
   • SSH keys added to GitLab
   • Member of blueflyio organization

One-Time Setup (New Machine)

Step 1: Mount NAS Volume

macOS (Finder):

# Open Finder → Go → Connect to Server (⌘K)
# Enter: nfs://192.168.68.54/volume1/AgentPlatform
# Or via Tailscale: nfs://blueflynas.tailcf98b3.ts.net/volume1/AgentPlatform

Verify mount:

ls -la /Volumes/AgentPlatform/
# Should show: repos/, worktrees/, wikis/

Step 2: Create Local Workspace

# Create minimal local directory
mkdir -p ~/Sites/blueflyio/.claude

# Copy CLAUDE.md from NAS
cp /Volumes/AgentPlatform/wikis/blueflyio/technical-docs.wiki/getting-started/CLAUDE.md ~/Sites/blueflyio/

# That's it! NO clones, NO wikis, NO worktrees locally

Step 3: Configure Git

# Set global git config
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Configure GitLab token (if using HTTPS)
git config --global credential.helper osxkeychain

# Or use SSH (recommended)
ssh-keygen -t ed25519 -C "your.email@example.com"
# Add ~/.ssh/id_ed25519.pub to GitLab → Settings → SSH Keys

Step 4: Test NAS Access

# List bare repos
ls /Volumes/AgentPlatform/repos/bare/blueflyio/

# List wikis
ls /Volumes/AgentPlatform/wikis/blueflyio/

# List worktrees
ls /Volumes/AgentPlatform/worktrees/shared/

✅ Setup complete! You're ready to work.

---

Working with Projects (Code)

Projects = Git worktrees on NAS

Creating a Worktree

# 1. Choose device namespace:
#    - shared/   = Multi-device work (Mac M3, M4, code-server, phone)
#    - m3/       = Mac M3 performance-specific
#    - m4/       = Mac M4 performance-specific

# 2. Set paths
BARE_REPO="/Volumes/AgentPlatform/repos/bare/blueflyio/agent-platform/[project-name].git"
WORKTREE="/Volumes/AgentPlatform/worktrees/shared/$(date +%Y-%m-%d)/[project-name]/[branch-name]"

# 3. Fetch latest
git -C "$BARE_REPO" fetch --prune origin

# 4. Create worktree
git -C "$BARE_REPO" worktree add "$WORKTREE" [branch-name]

# 5. Navigate to worktree
cd "$WORKTREE"

Example (agent-mesh project, feature branch):

BARE_REPO="/Volumes/AgentPlatform/repos/bare/blueflyio/agent-platform/agent-mesh.git"
WORKTREE="/Volumes/AgentPlatform/worktrees/shared/$(date +%Y-%m-%d)/agent-mesh/feat-awesome-feature"

git -C "$BARE_REPO" fetch --prune origin
git -C "$BARE_REPO" worktree add "$WORKTREE" -b feat/awesome-feature
cd "$WORKTREE"

Working in a Worktree

# You're now in: /Volumes/AgentPlatform/worktrees/shared/2026-01-23/agent-mesh/feat-awesome-feature/

# Normal git workflow
npm install
npm run dev

# Make changes
git add .
git commit -m "feat: add awesome feature"
git push origin feat/awesome-feature

Cleanup After MR Merges

# 1. Verify MR is merged
glab mr view 123

# 2. Check for uncommitted changes
cd /Volumes/AgentPlatform/worktrees/shared/2026-01-23/agent-mesh/feat-awesome-feature
git status  # Should be clean

# 3. Remove worktree
BARE_REPO="/Volumes/AgentPlatform/repos/bare/blueflyio/agent-platform/agent-mesh.git"
WORKTREE="/Volumes/AgentPlatform/worktrees/shared/2026-01-23/agent-mesh/feat-awesome-feature"
git -C "$BARE_REPO" worktree remove "$WORKTREE"

---

Working with Wikis (Documentation)

Wikis = Git repos on NAS (NOT worktrees)

Available Wikis

1. technical-docs.wiki - Platform documentation
2. api_normalization.wiki - API Normalization project docs

Editing Wiki

# Navigate to wiki (directly on NAS)
cd /Volumes/AgentPlatform/wikis/blueflyio/technical-docs.wiki/

# Pull latest
git pull origin main

# Make changes
vim architecture/overview/platform-overview.md

# Commit and push
git add .
git commit -m "docs: update platform overview"
git push origin main

No worktrees needed for wikis - just work directly in the NAS location.

Accessing from Multiple Devices

Same command on ALL devices:

cd /Volumes/AgentPlatform/wikis/blueflyio/technical-docs.wiki/

• Mac M4: /Volumes/AgentPlatform/...
• Mac M3: /Volumes/AgentPlatform/...
• code-server: /workspace/wikis/technical-docs.wiki/ (NAS mount)
• Phone/iPad: Via code-server browser

---

Key Differences: Projects vs Wikis

---

Common Tasks

List Active Worktrees

# For a specific project
git -C /Volumes/AgentPlatform/repos/bare/blueflyio/agent-platform/agent-mesh.git worktree list

# Find all worktrees (your device only)
ls /Volumes/AgentPlatform/worktrees/shared/$(date +%Y-%m-%d)/

Switch Between Projects

# Projects are just directories - cd into them
cd /Volumes/AgentPlatform/worktrees/shared/2026-01-23/agent-mesh/feat-branch
cd /Volumes/AgentPlatform/worktrees/shared/2026-01-23/compliance-engine/bugfix-branch

Update Wiki

# Single command workflow
cd /Volumes/AgentPlatform/wikis/blueflyio/technical-docs.wiki/ && \
git pull && \
# make changes \
git add . && \
git commit -m "docs: update" && \
git push

---

Troubleshooting

NAS Not Mounted

# macOS: Remount via Finder
# Or command line:
mount -t nfs 192.168.68.54:/volume1/AgentPlatform /Volumes/AgentPlatform

# Verify
ls /Volumes/AgentPlatform/

Permission Denied

# Check NFS permissions on NAS
# All files should be owned by your user
ls -la /Volumes/AgentPlatform/repos/bare/blueflyio/

Stale Worktrees

# Prune stale registrations
git -C /Volumes/AgentPlatform/repos/bare/blueflyio/agent-platform/[project].git worktree prune

---

Best Practices

DO:

✅ Always use device namespaces (shared/m3/m4) ✅ Always fetch before creating worktrees ✅ Always check git status before removing worktrees ✅ Use shared/ for work you'll access from multiple devices ✅ Commit and push immediately (work is on NAS but not backed up until pushed)

DON'T:

❌ Create local clones of repos ❌ Create local copies of wikis ❌ Work outside /Volumes/AgentPlatform/ ❌ Leave uncommitted changes when switching machines ❌ Delete worktrees without checking git status

---

Questions? See Separation of Duties for complete rules.

Last Updated: 2026-01-23