Runner v3 — Node.js/TypeScript Core

Ejecutor de comandos e agente autônomo para Elon Tools. Executa jobs enviados pelo backend e reporta resultados em tempo real.

📋 Overview

• Language: TypeScript (Node.js)
• Runtime: Node.js 18+
• Modes: headless (CLI), ui (screen control)
• Platforms: macOS, Linux, Windows

🚀 Quick Start

Local Development

# Install dependencies
npm install

# Compile TypeScript
npm run build

# Run locally
npm start -- --server-url=https://elontools.com --pairing-token=PT_xxx

# Or with all flags
npm start -- \
  --server-url=https://elontools.com \
  --pairing-token=PT_xxx \
  --mode=headless

macOS App Bundle

O runner v3 é empacotado dentro de Elon Runner.app para macOS.

# Build for current architecture (arm64 or x86_64)
bash build-mac.sh

# Build specific architecture
bash build-mac.sh arm64
bash build-mac.sh x86_64

# Build universal binary (both architectures)
bash build-mac-universal.sh

Resultado: Binary instalado em ElonRunner.app/Contents/MacOS/runner-v3

📁 Structure

runner-v3/
├── src/
│   └── index.ts              # Main entry point
├── dist/                     # Compiled JavaScript (generated)
├── build/                    # Build artifacts (generated)
│   ├── arm64/
│   ├── x86_64/
│   └── runner-v3-universal   # Universal binary (optional)
├── mac-app/                  # macOS Xcode project
│   └── ElonRunnerApp/
│       └── ElonRunnerApp.app/
│           ├── Contents/
│           │   ├── MacOS/
│           │   │   └── runner-v3        # Executable (copied by build script)
│           │   └── Resources/
│           │       └── runner-v3/       # Source files
├── package.json
├── tsconfig.json
├── build-mac.sh              # Build script (single arch)
├── build-mac-universal.sh    # Build script (universal)
└── README.md                 # This file

🔧 Configuration

Command-Line Arguments

runner-v3 \
  --server-url=https://elontools.com \
  --pairing-token=PT_xxx \
  --runner-id=abc123 \
  --mode=headless

| Argument | Required | Description | |----------|----------|-------------| | --server-url | Yes | Backend server URL (default: https://elontools.com) | | --pairing-token | No* | Pairing token (PT_xxx) - required for first registration | | --runner-id | No | Runner ID (set after registration) | | --mode | No | headless or ui (default: headless) | | --config-path | No | Path to config file (optional) |

*Required on first run for registration

Environment

# Optional: set NODE_BIN for wrapper scripts
export NODE_BIN=/usr/local/bin/node

🔄 Lifecycle

1. Registration (First Run)

runner-v3 --server-url=... --pairing-token=PT_xxx

↓ (POST /api/v1/runner-v3/register)

← Response: { runner_id, runner_token }

↓ (stored in config)

✅ Registered

2. Heartbeat Loop

Every 30 seconds:
  POST /api/v1/runner-v3/:id/heartbeat
  ← { status: "online", uptime: ... }

3. Job Polling

Every 5 seconds:
  GET /api/v1/runner-v3/:id/pull
  ← { jobs: [...] }

For each job:
  - Execute command
  - Capture stdout/stderr
  - POST /api/v1/runner-v3/:id/report

4. Shutdown

Ctrl+C or SIGTERM

→ Graceful shutdown
  - Stop polling
  - Send final heartbeat
  - Exit with code 0

📤 API Integration

Registration

POST /api/v1/runner-v3/register

curl -X POST https://elontools.com/api/v1/runner-v3/register \
  -H "Authorization: Bearer PT_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "headless",
    "platform": "darwin",
    "arch": "arm64"
  }'

# Response:
{
  "runner_id": "run_abc123...",
  "runner_token": "rt3_xyz789..."
}

Heartbeat

POST /api/v1/runner-v3/:id/heartbeat

curl -X POST https://elontools.com/api/v1/runner-v3/run_abc123/heartbeat \
  -H "Authorization: Bearer rt3_xyz789" \
  -H "Content-Type: application/json" \
  -d '{
    "runner_id": "run_abc123",
    "status": "online",
    "mode": "headless",
    "uptime": 3600
  }'

Pull Jobs

GET /api/v1/runner-v3/:id/pull

curl https://elontools.com/api/v1/runner-v3/run_abc123/pull \
  -H "Authorization: Bearer rt3_xyz789"

# Response:
{
  "jobs": [
    {
      "id": "job_123",
      "command": "ls",
      "args": ["-la", "/tmp"]
    }
  ]
}

Report Job Result

POST /api/v1/runner-v3/:id/report

curl -X POST https://elontools.com/api/v1/runner-v3/run_abc123/report \
  -H "Authorization: Bearer rt3_xyz789" \
  -H "Content-Type: application/json" \
  -d '{
    "job_id": "job_123",
    "status": "completed",
    "output": "total 0\ndrwxr-xr-x  ...",
    "error": null
  }'

📊 Logging

Logs are printed to stdout/stderr with timestamps:

[2026-02-18T10:30:00.000Z] ℹ️  Runner v3 iniciado
[2026-02-18T10:30:01.234Z] 📝 Registrando runner com API...
[2026-02-18T10:30:02.456Z] ✅ Runner registrado
[2026-02-18T10:30:05.789Z] 💓 Heartbeat enviado
[2026-02-18T10:30:10.234Z] 🚀 Executando job
[2026-02-18T10:30:15.678Z] 📤 Job result reportado

Log Prefixes

| Prefix | Meaning | |--------|---------| | ℹ️ | Info message | | ✅ | Success | | ⚠️ | Warning | | ❌ | Error | | 💓 | Heartbeat | | 🚀 | Job execution | | 📝 | API call (register) | | 📤 | Report result |

🏗️ macOS Build Process

Step 1: TypeScript Compilation

npm run build
# Creates: dist/index.js + source maps

Step 2: Create Wrapper

Wrapper script that:

• Finds Node.js binary
• Executes dist/index.js with all arguments
• Handles errors gracefully

Step 3: Create Binary

Combines wrapper + runner files into single executable:

• build/arm64/runner-v3 (arm64 only)
• build/x86_64/runner-v3 (x86_64 only)
• build/runner-v3-universal (both, via lipo)

Step 4: Copy to App Bundle

ElonRunnerApp.app/
├── Contents/
│   ├── MacOS/
│   │   └── runner-v3 ← Binary installed here
│   └── Resources/
│       └── runner-v3/ ← Source files for reference

🔍 Debugging

Run with detailed logging

# Set Node.js debug flag
DEBUG=* npm start -- --server-url=... --pairing-token=...

# Or redirect to file
npm start -- ... 2>&1 | tee runner.log

Test binary directly

# From macOS app:
./ElonRunnerApp.app/Contents/MacOS/runner-v3 \
  --server-url=https://elontools.com \
  --pairing-token=PT_test_xxx

# Expected output:
# [timestamp] ℹ️  Runner v3 iniciado
# [timestamp] 📝 Registrando runner com API...
# [timestamp] ✅ Runner registrado

Monitor heartbeat (macOS log)

# From app bundle logs
tail -f ~/Library/Logs/ElonRunner/stdout.log

🚨 Common Issues

"Node.js not found in PATH"

Solution: Install Node.js via Homebrew

brew install node

Or set NODE_BIN environment variable:

export NODE_BIN=/usr/local/bin/node
./runner-v3 --server-url=...

"Binary not found in app bundle"

Solution: Run build script

bash build-mac.sh

"Permission denied"

Solution: Make binary executable

chmod +x ElonRunnerApp.app/Contents/MacOS/runner-v3

🎯 Development Workflow

1. Make changes to src/index.ts

# Auto-compile on save
npm run dev

2. Test locally

npm start -- --server-url=... --pairing-token=... --mode=headless

3. Build for macOS app

bash build-mac.sh

4. Test in app (Xcode)

# Open Xcode project
open mac-app/ElonRunnerApp/ElonRunnerApp.xcodeproj

# Cmd+R to build & run

📦 Distribution

macOS App (.app)

# Build universal binary
bash build-mac-universal.sh

# Copy app to /Applications
cp -r ElonRunnerApp.app /Applications/

# Run
/Applications/ElonRunnerApp.app/Contents/MacOS/Elon\ Runner

Standalone Binary

# Build universal
bash build-mac-universal.sh

# Copy to PATH
cp build/runner-v3-universal /usr/local/bin/runner-v3
chmod +x /usr/local/bin/runner-v3

# Run
runner-v3 --server-url=...

🔐 Security

• ✅ Token Hashing: Pairing tokens are hashed (SHA-256) server-side
• ✅ Bearer Auth: Runner tokens are Bearer tokens (not exposed in logs)
• ✅ HTTPS only: All API calls use HTTPS
• ✅ Process Isolation: Each job runs in isolated process
• ✅ No Plaintext Storage: Tokens removed from disk after registration

📚 References

• Backend: apps/api/src/services/runner-v3.service.ts
• API: apps/api/src/routes/runner-v3.handler.ts
• macOS App: runner-v3/mac-app/ElonRunnerApp/

🤝 Contributing

1. Make changes to src/
2. Test locally (npm run dev + npm start)
3. Build for macOS (bash build-mac.sh)
4. Test in app (Xcode)
5. Commit & push

📄 License

Copyright © 2026 ElonTools. All rights reserved.

Last Updated: 2026-02-18
Version: 3.0.0
Status: MVP (ready for macOS app integration)