AI Machine Registry

Self-service registration for new machines joining the AI Platform.

Prerequisites

• macOS with Apple Silicon (M1/M2/M3/M4)
• Dropbox installed and synced (so this folder is accessible)
• Python 3 (any version — scripts use stdlib only)
• conda or mamba installed (for environment setup)

Quick Start — 3 Steps

Step 1: Register the machine

python3 register.py

This script: - Auto-detects hostname, hardware (chip, memory), and storage paths - Finds the Dropbox root by walking up from its own location - Prompts for machine ID, description, and roles - Writes ai-platform/machines/{id}.json - Validates the JSON against the required schema

Step 2: Set up the environment

bash setup_env.sh

This script: - Creates the voicememo-py314 conda environment with Python 3.14 - Installs all required packages (google-genai, fastapi, pydantic, etc.) - Sets up Cursor symlinks from ~/.cursor/skills/ and ~/.cursor/rules/ to the shared 2026project/.cursor/ directory - Checks for GEMINI_API_KEY in your shell profile

Step 3: Verify everything works

python3 verify.py

This script checks: - Machine JSON exists and matches this hostname - All required fields are present - lib/env.py detects this machine correctly - Storage paths exist on disk - Conda environment is available with Python 3.14 - Cursor symlinks point to the shared location - GEMINI_API_KEY is set

What Gets Created

ai-platform/machines/{id}.json     — Machine configuration
~/.cursor/skills/*                  — Symlinks to shared skills
~/.cursor/rules/ai-ports.mdc       — Symlink to shared rule
voicememo-py314 conda env           — Python 3.14 environment

Post-Registration

Tailscale

If Tailscale wasn't installed during registration:

# Install from https://tailscale.com/download
tailscale up
tailscale ip -4
# Update the machine JSON with the IP

GEMINI_API_KEY

If the API key wasn't set:

echo 'export GEMINI_API_KEY="your-key-here"' >> ~/.zshrc
source ~/.zshrc

Get a key at: https://aistudio.google.com/apikey

Full Test Suite

For a comprehensive validation (requires pytest):

conda run -n voicememo-py314 pytest ai-platform/tests/test_machine_portability.py -v

Storage Types

File Overview

ai-machine-registry/
├── README.md                    # This file
├── register.py                  # Step 1: Machine registration
├── setup_env.sh                 # Step 2: Environment setup
├── verify.py                    # Step 3: Verification
└── templates/
    └── machine.json.template    # JSON template reference

For Cursor AI

When a user opens Cursor on a new machine and says "register this machine to the ai-platform", the AI should:

1. Run python3 ai-machine-registry/register.py to create the machine JSON
2. Run bash ai-machine-registry/setup_env.sh to set up the environment
3. Run python3 ai-machine-registry/verify.py to confirm everything works