Allow2 Automate Agent

A cross-platform system service for process monitoring and parental controls. The agent runs as a background service on Windows, macOS, and Linux, monitoring running processes and enforcing policies set by parent applications.

Features

Cross-Platform Support: Runs on Windows, macOS, and Linux
Process Monitoring: Continuously monitors running processes
Policy Enforcement: Automatically terminates prohibited processes
REST API: HTTPS API for remote management
mDNS Discovery: Automatic discovery by parent applications
Auto-Update: Self-updating mechanism
Secure: JWT authentication, encrypted communications
System Service: Runs as a native system service

Architecture

┌─────────────────────────────────────────┐
│        Allow2 Automate Agent            │
├─────────────────────────────────────────┤
│  ┌──────────────┐  ┌─────────────────┐ │
│  │   API Server │  │ Process Monitor │ │
│  │  (REST/JWT)  │  │  (30s interval) │ │
│  └──────────────┘  └─────────────────┘ │
│  ┌──────────────┐  ┌─────────────────┐ │
│  │ Policy Engine│  │ mDNS Discovery  │ │
│  │ (Sync/Cache) │  │   (Bonjour)     │ │
│  └──────────────┘  └─────────────────┘ │
│  ┌──────────────┐  ┌─────────────────┐ │
│  │ Auto-Updater │  │  Config Manager │ │
│  └──────────────┘  └─────────────────┘ │
├─────────────────────────────────────────┤
│      Platform Abstraction Layer         │
│   (Windows | macOS | Linux)             │
└─────────────────────────────────────────┘

Installation

Prerequisites

Node.js >= 18.0.0
Administrator/root privileges for service installation

Install Dependencies

npm install

Development Mode

npm run start:dev

Install as System Service

Windows

npm run build:windows
# Run the generated MSI installer

macOS

npm run build:macos
# Install the generated PKG

Linux

npm run build:linux
# Install the generated DEB/RPM package

Configuration

The agent stores configuration in platform-specific locations:

Windows: C:\ProgramData\Allow2\agent\config.json
macOS: /Library/Application Support/Allow2/agent/config.json
Linux: /etc/allow2/agent/config.json

Default Configuration

{
  "apiPort": 8443,
  "checkInterval": 30000,
  "logLevel": "info",
  "enableMDNS": true,
  "autoUpdate": true
}

Configuration Options

Option	Type	Default	Description
`agentId`	string	null	Unique agent identifier
`parentApiUrl`	string	null	Parent application API URL
`authToken`	string	null	JWT authentication token
`apiPort`	number	8443	API server port
`checkInterval`	number	30000	Process check interval (ms)
`logLevel`	string	"info"	Logging level
`enableMDNS`	boolean	true	Enable mDNS advertising
`autoUpdate`	boolean	true	Enable auto-updates

REST API

The agent exposes a REST API on port 8443 (configurable).

Authentication

All API endpoints (except /api/health, /api/heartbeat, and /api/platform-users) require JWT authentication:

Authorization: Bearer <token>

Endpoints

Health Check

GET /api/health

Returns agent health status and basic information.

Heartbeat

POST /api/heartbeat

Keep-alive endpoint for monitoring.

Platform Users

GET /api/platform-users

Discover local platform users for account linking.

Policy Management

Create policy:

POST /api/policies
Content-Type: application/json

{
  "id": "policy-123",
  "processName": "game.exe",
  "allowed": false,
  "schedule": {
    "startTime": "14:00",
    "endTime": "16:00",
    "days": [1, 2, 3, 4, 5]
  }
}

List policies:

GET /api/policies

Get policy:

GET /api/policies/:id

Update policy:

PATCH /api/policies/:id
Content-Type: application/json

{
  "allowed": true
}

Delete policy:

DELETE /api/policies/:id

Sync with Parent

POST /api/sync

Trigger policy synchronization with parent API.

Configuration

Get configuration:

GET /api/config

Update configuration:

PATCH /api/config
Content-Type: application/json

{
  "checkInterval": 60000,
  "logLevel": "debug"
}

Process Monitoring

Get monitor status:

GET /api/monitor/status

Start monitoring:

POST /api/monitor/start

Stop monitoring:

POST /api/monitor/stop

Process List

GET /api/processes

Returns list of currently running processes.

Auto-Update

POST /api/update
Content-Type: application/json

{
  "version": "1.1.0",
  "downloadUrl": "/downloads/agent-1.1.0.msi"
}

mDNS Discovery

The agent advertises itself via mDNS/Bonjour for automatic discovery:

Service Type: _allow2._tcp
Service Name: allow2-agent-{hostname}
TXT Records:
- agentId: Unique agent identifier
- hostname: System hostname
- version: Agent version
- platform: Operating system platform
- arch: System architecture

Process Monitoring

The agent monitors processes at regular intervals (default: 30 seconds) and:

Fetches active policies from the policy engine
Checks if prohibited processes are running
Terminates any prohibited processes
Reports violations to parent API
Enforces time-based schedules and quotas

Policy Structure

{
  id: "policy-123",
  processName: "game.exe",
  allowed: false,
  schedule: {
    startTime: "14:00",  // 2:00 PM
    endTime: "16:00",    // 4:00 PM
    days: [1, 2, 3, 4, 5] // Monday-Friday (0=Sunday)
  },
  quotas: {
    dailyMinutes: 120  // 2 hours per day (future)
  }
}

Development

Project Structure

allow2automate-agent/
├── src/
│   ├── index.js              # Main entry point
│   ├── ApiServer.js          # REST API server
│   ├── ProcessMonitor.js     # Process monitoring
│   ├── PolicyEngine.js       # Policy management
│   ├── ConfigManager.js      # Configuration
│   ├── DiscoveryAdvertiser.js # mDNS advertising
│   ├── AutoUpdater.js        # Auto-update
│   ├── Logger.js             # Logging utility
│   └── platform/
│       ├── windows.js        # Windows implementation
│       ├── darwin.js         # macOS implementation
│       └── linux.js          # Linux implementation
├── tests/
│   ├── ConfigManager.test.js
│   ├── PolicyEngine.test.js
│   ├── ProcessMonitor.test.js
│   └── platform/
│       ├── windows.test.js
│       ├── darwin.test.js
│       └── linux.test.js
├── config/
│   └── default.json
├── installers/
│   ├── windows/
│   ├── macos/
│   └── linux/
├── scripts/
└── package.json

Running Tests

# Run all tests
npm test

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage

Code Style

# Lint code
npm run lint

Platform-Specific Implementation

Each platform has its own implementation for process management:

Windows

Uses tasklist to check running processes
Uses taskkill /F to terminate processes
Processes identified by executable name (e.g., chrome.exe)

macOS

Uses pgrep to check running processes
Uses pkill -9 to terminate processes
Processes identified by app name (case-insensitive)

Linux

Uses pgrep to check running processes
Uses pkill -9 to terminate processes
Similar to macOS implementation

Security

JWT Authentication: All API endpoints require valid JWT tokens
Secure Storage: Configuration files have restricted permissions (0600)
HTTPS: API server uses HTTPS (certificates configurable)
Token Rotation: Support for token refresh
Rate Limiting: Violation reports are rate-limited

Logging

Logs are stored in platform-specific locations:

Windows: C:\ProgramData\Allow2\agent\logs\
macOS: /Library/Logs/Allow2/agent/
Linux: /var/log/allow2/agent/

Log files:

agent.log - General application logs
error.log - Error logs only

Log rotation:

Maximum file size: 10 MB
Maximum files: 5

Troubleshooting

Diagnostic Scripts

We provide diagnostic scripts for each platform that check all agent components and display relevant log entries. Run these first when troubleshooting:

Platform	Script	Command
Windows	diagnose-windows.ps1	`powershell -ExecutionPolicy Bypass -File .\diagnose-windows.ps1`
macOS	diagnose-macos.sh	`sudo ./diagnose-macos.sh`
Linux	diagnose-linux.sh	`sudo ./diagnose-linux.sh`

These scripts check:

Service/daemon status
Running processes
Binary installation and architecture
Configuration file validity
Log file contents
Network connectivity to parent
System requirements

Quick Status Commands

Windows

# Check service status
sc query Allow2AutomateAgent

# Check process
tasklist /FI "IMAGENAME eq allow2automate-agent.exe"

# View logs
Get-Content "C:\ProgramData\Allow2\agent\logs\agent.log" -Tail 50

# Start/stop/restart service
sc start Allow2AutomateAgent
sc stop Allow2AutomateAgent

macOS

# Check service status
sudo launchctl list | grep allow2

# Check process
pgrep -fl allow2automate-agent

# View logs
tail -50 /Library/Logs/Allow2/agent/agent.log

# Start/stop service
sudo launchctl start com.allow2.automate-agent
sudo launchctl stop com.allow2.automate-agent

# Check binary architecture (important for M1/M2/M3 Macs)
file /usr/local/share/allow2automate-agent/allow2automate-agent

Linux

# Check service status
sudo systemctl status allow2automate-agent

# Check process
pgrep -fl allow2automate-agent

# View logs
tail -50 /var/log/allow2/agent/agent.log
sudo journalctl -u allow2automate-agent -f

# Start/stop/restart service
sudo systemctl start allow2automate-agent
sudo systemctl stop allow2automate-agent
sudo systemctl restart allow2automate-agent

Common Issues

Agent Not Starting

Run the diagnostic script for your platform (see above)
Check logs in the platform-specific log directory
Verify configuration file exists and contains valid JSON
Ensure proper permissions (run as admin/root)
Check if port 8443 is available

"SyntaxError: Invalid or unexpected token" on macOS

This error in pkg/prelude/bootstrap.js indicates the binary is corrupt or built for the wrong architecture:

pkg/prelude/bootstrap.js:1
SyntaxError: Invalid or unexpected token

Solution:

Check your Mac's architecture: uname -m
- arm64 = Apple Silicon (M1/M2/M3)
- x86_64 = Intel Mac
Download the correct installer from the parent app
Verify binary architecture: file /usr/local/share/allow2automate-agent/allow2automate-agent
Re-install with the matching architecture build

Configuration File Not Found

The agent requires a config.json with credentials to connect to the parent app:

Platform	Config Location
Windows	`C:\ProgramData\Allow2\agent\config.json`
macOS	`/Library/Application Support/Allow2/agent/config.json`
Linux	`/etc/allow2/agent/config.json`

Solution: Download the installer from the parent app - it embeds the configuration automatically.

Cannot Connect to Parent

Verify the parent app is running
Check parentApiUrl in config points to the correct IP:port
Test connectivity: curl http://<parent-ip>:<port>/api/health
Check firewall rules on both machines
Ensure both devices are on the same network

Process Not Being Terminated

Check if policy is active (schedule, days)
Verify process name matches exactly (case-sensitive on macOS/Linux)
Check agent has sufficient privileges
Review logs for error messages

mDNS Not Working

Ensure enableMDNS is true in config
Check firewall allows mDNS (port 5353 UDP)
Verify network supports multicast
Platform-specific:
- Windows: Bonjour service should be running
- macOS: mDNSResponder is built-in
- Linux: Install and start avahi-daemon

API Not Accessible

Check agent is running
Verify port is not blocked by firewall
Ensure proper authentication token
Check SSL/TLS certificate configuration

Log File Locations

Platform	Log Directory
Windows	`C:\ProgramData\Allow2\agent\logs\`
macOS	`/Library/Logs/Allow2/agent/`
Linux	`/var/log/allow2/agent/`

Log files:

agent.log - General application logs (JSON format)
error.log - Error logs only

Uninstalling

Windows

Run as Administrator:

"C:\Program Files\Allow2\uninstall.bat"

Or use Windows Settings > Apps > Allow2Automate Agent > Uninstall

macOS

sudo /usr/local/share/allow2automate-agent/uninstall.sh

Linux

# Debian/Ubuntu
sudo apt remove allow2automate-agent

# RHEL/Fedora/CentOS
sudo dnf remove allow2automate-agent
# or
sudo yum remove allow2automate-agent

# Or use the uninstall script
sudo /usr/local/share/allow2automate-agent/uninstall.sh

Contributing

Fork the repository
Create a feature branch
Make your changes
Write/update tests
Submit a pull request

License

MIT

Support

For issues and questions:

GitHub Issues: github.com/allow2/allow2automate-agent
Documentation: docs.allow2.com

Name		Name	Last commit message	Last commit date
Latest commit History 74 Commits
.github		.github
.swarm		.swarm
config		config
docs		docs
helper		helper
installers		installers
scripts		scripts
src		src
tests		tests
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
DEVELOPMENT.md		DEVELOPMENT.md
INSTALL.md		INSTALL.md
README.md		README.md
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json

Allow2/allow2automate-agent

Folders and files

Latest commit

History

Repository files navigation

Allow2 Automate Agent

Features

Architecture

Installation

Prerequisites

Install Dependencies

Development Mode

Install as System Service

Windows

macOS

Linux

Configuration

Default Configuration

Configuration Options

REST API

Authentication

Endpoints

Health Check

Heartbeat

Platform Users

Policy Management

Sync with Parent

Configuration

Process Monitoring

Process List

Auto-Update

mDNS Discovery

Process Monitoring

Policy Structure

Development

Project Structure

Running Tests

Code Style

Platform-Specific Implementation

Windows

macOS

Linux

Security

Logging

Troubleshooting

Diagnostic Scripts

Quick Status Commands

Windows

macOS

Linux

Common Issues

Agent Not Starting

"SyntaxError: Invalid or unexpected token" on macOS

Configuration File Not Found

Cannot Connect to Parent

Process Not Being Terminated

mDNS Not Working

API Not Accessible

Log File Locations

Uninstalling

Windows

macOS

Linux

Contributing

License

Support

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 33

Packages 0

Languages

Packages