Build Your Personal Digital Assistant: The Complete Guide to AgentHack

Introduction: Revolutionizing Personal Productivity with AgentHack

AgentHack represents a groundbreaking approach to personal digital assistance, built on the innovative AO (Autonomous Objects) network. This comprehensive solution delivers email management, weather updates, calendar integration, and more through a decentralized architecture that puts users in complete control of their data and automation workflows.

What makes AgentHack different from conventional assistant services? Unlike centralized commercial alternatives, AgentHack offers an open-source, self-hosted solution that eliminates monthly fees while providing unparalleled customization capabilities and data ownership.

The Problem with Traditional Digital Assistants

Most digital assistants today come with significant drawbacks: they’re often expensive, collect your personal data, and offer limited customization. AgentHack addresses these issues by providing a framework where you control every aspect of the functionality and data storage.

Author’s reflection: Having experimented with various automation tools over the years, I’ve found that most solutions either lack flexibility or come with hidden costs. AgentHack’s approach of combining decentralized architecture with practical daily utilities represents a significant step forward in personal automation technology.

Understanding AgentHack’s Architecture

How does AgentHack technically accomplish its functionality? The system employs a multi-process distributed architecture where each component has specific responsibilities, communicating through the AO network to deliver seamless automation while maintaining reliability and scalability.

Core Components and Their Roles

AgentHack consists of three main processes and several supporting modules that work in concert:

Agent Process serves as the system’s brain, loading agent/main.lua and handling core logic processing. It contains several specialized modules:

  • emails.lua: Manages email-related functionality
  • weather.lua: Handles weather data acquisition and updates
  • calendar.lua: Processes calendar integration and event management
  • notes.lua: Provides note-taking capabilities
  • tokens.lua: Manages token systems
  • setCrons.lua: Configures scheduled tasks

Relay Process acts as middleware, loading relay_process/mock_relay.lua and managing HTTP requests and external API communications. This component bridges the system with external services like Brevo email service and OpenWeather.

Crontroller Process functions as the task scheduler, loading crontroller/crontroller.lua and configured for 1-minute cron intervals to ensure precise task execution.

Data Flow and Operational Principles

When a user makes a request through the frontend interface, it gets sent to the Agent process, which then communicates with the Relay process as needed to access external APIs. The Crontroller process regularly triggers various tasks (such as weather updates and email checks) to maintain data freshness. All processes operate on the AO network, using message passing for communication.

Practical scenario: Imagine you’re a freelance developer managing multiple client projects. With AgentHack, you can set up automatic reminders that send email notifications one hour before meetings, including weather information (to help plan your commute) and relevant meeting notes. This entire process happens automatically without manual intervention.

Preparation: Gathering Required Resources

What do you need to deploy AgentHack successfully? You’ll need to prepare Node.js environment, Yarn package manager, an AO wallet file, and two free API keys (from Brevo and OpenWeather)—these form the foundational dependencies for system operation.

Development Environment Requirements

Since AgentHack is built on Node.js, you’ll need Node.js version 16 or higher installed. I recommend using Node.js 18 LTS version for better stability and performance. You’ll also need the Yarn package manager, which offers faster dependency installation and more consistent dependency management compared to npm.

The AO wallet file is essential for accessing the AO network. If you don’t already have an AO wallet, you’ll need to create one and securely back it up. The wallet file typically resides at ~/.aos.json and contains authentication information needed to access the AO network.

API Key Acquisition

Brevo email service provides free email sending capabilities. The registration process is straightforward:

  1. Visit https://onboarding.brevo.com/account/register
  2. Complete the necessary registration information to create an account
  3. Generate an API key from your console dashboard

OpenWeather API offers global weather data with a free tier:

  1. Visit https://home.openweathermap.org/users/sign_up
  2. Create a free account
  3. Generate an API key from your account settings

Author’s reflection: Based on my experience setting up multiple AgentHack instances, I’ve learned that carefully documenting your API keys and keeping them secure from the beginning saves significant time during the configuration phase. I recommend using a password manager to store these credentials securely.

Step-by-Step Installation Guide

How do you properly install and configure the AgentHack system? The installation process involves configuring multiple components and ensuring their proper coordination, requiring strict adherence to the steps with particular attention to correct environment variable settings and accurate process ID configuration.

Environment Configuration Steps

First, configure the environment variables for the Relay Monitor component:

# Copy the environment template file
cp relay_monitor/.env.example relay_monitor/.env

Edit the relay_monitor/.env file and update these required fields:

# API Keys (REQUIRED - update these)
BREVO_API_KEY=your_actual_brevo_api_key
OPENWEATHER_API_KEY=your_actual_openweather_api_key

# Email Configuration (REQUIRED - update these)
EMAIL_TO_ADDRESS=your_real_email@example.com
EMAIL_TO_NAME=YourActualName
EMAIL_SENDER_ADDRESS=your_sender_email@example.com

# AO Wallet Configuration (update if different)
AO_WALLET_PATH=~/.aos.json

Important note: Unless you’re also modifying the corresponding agent code, avoid changing any placeholder values (like wouldnt-you-like-to-know, preConfiguredEmailAddress, etc.). The process IDs in the example file are pre-configured and don’t need modification.

Creating AO Processes

Next, you need to create three AO processes, each with specific configurations:

  1. Agent Process: Load agent/main.lua
  2. Relay Process: Load relay_process/mock_relay.lua
  3. Crontroller Process: Load crontroller/crontroller.lua with a 1-minute cron interval

All three processes must be created using legacynet. Once created, the system assigns each process a unique process ID, which you’ll need for subsequent configuration.

Updating Process ID Configuration

After obtaining your process IDs, you need to update the environment configuration files:

  1. Update the process IDs in relay_monitor/.env:
MOCK_RELAY_PROCESS_ID="your-actual-relay-process-id"
CRONTROLLER_PROCESS_ID="your-actual-crontroller-process-id"
  1. Configure the environment variables for the Utilities component:
# Copy the utilities environment template
cp utilities/.env.example utilities/.env

Edit the utilities/.env file and update with your actual values:

# AO Process IDs (update with your actual process IDs)
AGENT_PROCESS_ID = "your-actual-agent-process-id"
RELAY_PROCESS_ID = "your-actual-relay-process-id"
CRONTROLLER_PROCESS_ID = "your-actual-crontroller-process-id"

# User Configuration
USER_WALLET_ADDRESS = "your-actual-wallet-address"
WALLET_PATH = ~/.aos.json

# Weather Configuration
WEATHER_LOCATION = Your City, Your State

Note: The example file contains real process IDs that should be replaced with your own. These IDs are crucial identifiers for communication between system components, and incorrect configuration will prevent the system from functioning properly.

Dependency Installation and Initialization

Install all required dependencies:

# Install Relay Monitor dependencies
cd relay_monitor
yarn install

# Install Frontend dependencies
cd ../front_end
yarn install

# Install Utilities dependencies
cd ../utilities
yarn install

cd ..

After dependency installation, start the Relay Monitor:

cd relay_monitor
yarn start

Keep this terminal window running, as the Relay Monitor needs to run continuously to process HTTP requests.

Run the initial setup script:

cd utilities
node getStarted.js

This script initializes your agent with basic configuration, preparing it for subsequent functionality.

Frontend Configuration

The frontend interface is the primary way users interact with AgentHack and needs proper configuration:

# Copy the frontend environment template
cp front_end/env.example front_end/.env

Edit the front_end/.env file and fill in:

VITE_APP_NAME="GUS - Personal AO Assistant"
VITE_APP_DESCRIPTION="Your personal AO assistant, brought to you by Giga Utility Services"
VITE_ARWEAVE_GATEWAY="https://arweave.net"
VITE_DEFAULT_PERMISSIONS="ACCESS_ADDRESS,ACCESS_PUBLIC_KEY,SIGN_TRANSACTION"

# Process IDs
VITE_AGENT_PROCESS_ID="your-actual-agent-process-id"
VITE_RELAY_PROCESS_ID="your-actual-relay-process-id"
VITE_CRONTROLLER_PROCESS_ID="your-actual-crontroller-process-id"

Start the frontend application:

cd front_end
yarn dev

Your AgentHack assistant will now be available at http://localhost:3000

Important reminder: Functionality requiring HTTP calls may take up to 40 minutes to fully process. This is normal behavior due to the distributed nature of the AO network. Be patient while all initial data processing completes.

Application scenario: Consider a project manager who needs to coordinate teams across different time zones. With AgentHack, they can set up automated daily digest emails that include weather information for each team’s location, schedule reminders adjusted for each time zone, and compile status updates from various sources—all automatically formatted and delivered at appropriate times.

Configuration Details Explained

What role do the various configuration options play, and what impact do they have? Each environment variable controls specific aspects of the system, from API connections to process communication, with correct configuration ensuring stable operation and functional completeness.

Relay Monitor Environment Variables

The Relay Monitor is a critical component for system communication with external services, with configurations divided into required updates and optional updates.

Required configuration updates:

  • BREVO_API_KEY: Brevo email service API key (replace your_brevo_api_key_here)
  • OPENWEATHER_API_KEY: OpenWeather API key (replace your_openweather_api_key_here)
  • EMAIL_TO_ADDRESS: Your email address (replace email@email.com)
  • EMAIL_TO_NAME: Your name (replace Stephen)
  • EMAIL_SENDER_ADDRESS: Sender email address (replace emailSender@email.com)

Optional configuration updates:

  • AO_WALLET_PATH: Path to your AO wallet file (if different from ~/.aos.json)
  • MOCK_RELAY_PROCESS_ID: Your relay process ID (if different from example)
  • CRONTROLLER_PROCESS_ID: Your crontroller process ID (if different from example)

Should not be changed (unless modifying agent code):

  • All placeholder values (e.g., wouldnt-you-like-to-know, preConfiguredEmailAddress, etc.)
  • Timing configuration values (CHECK_INTERVAL, GRAPHQL_FAILURE_DELAY, etc.)
  • Gus price API configuration (GUS_PRICE_REQUIRED_BEARER_TOKEN, VENTO_RETRY_LIMIT, etc.)
  • AO Network configuration URLs (GATEWAY_URL, MU_URL, CU_URL)

Utilities Environment Variables

Utilities provide various tool scripts, with configuration primarily focusing on process identification and user settings.

Required configuration updates:

  • AGENT_PROCESS_ID: Your agent process ID (replace example value)
  • RELAY_PROCESS_ID: Your relay process ID (replace example value)
  • CRONTROLLER_PROCESS_ID: Your crontroller process ID (replace example value)
  • USER_WALLET_ADDRESS: Your wallet address (replace example value)

Optional configuration updates:

  • WALLET_PATH: Path to your wallet file (if different from ~/.aos.json)
  • WEATHER_LOCATION: Your location for weather updates (if different from New York, NY)

Frontend Environment Variables

Frontend configuration primarily controls interface display and permission settings:

  • VITE_AGENT_PROCESS_ID: Your agent process ID
  • VITE_RELAY_PROCESS_ID: Your relay process ID
  • VITE_CRONTROLLER_PROCESS_ID: Your crontroller process ID

Practical application: If you work in Beijing but need to stay informed about weather conditions in New York (where your team is located), you can set WEATHER_LOCATION to “New York, NY”. This ensures your morning weather digest includes New York’s weather information, helping you better coordinate with your remote team.

Author’s reflection: Through multiple AgentHack deployments, I’ve found that process ID configuration is the most error-prone环节. I recommend creating a checklist to verify each process ID is correctly configured. One useful technique is using environment validation scripts that automatically check all required configurations are properly set before startup.

Use Cases and Practical Applications

AgentHack is more than a technical demonstration—it solves real-world automation needs. Understanding these use cases helps you better leverage AgentHack to enhance productivity.

What practical application value does AgentHack offer in real life? AgentHack can automate routine tasks like email management, weather monitoring, and schedule organization, saving users time while reducing manual operation errors.

Email Management Automation

AgentHack’s email functionality goes beyond simple sending and receiving—it can automatically process email flow based on rules. For example, you can set up rules to:

  • Automatically sort emails from specific contacts into designated folders
  • Mark important emails based on content priority
  • Send summary emails at specific times, consolidating the day’s important information

Case study: Imagine you’re a project manager receiving numerous progress report emails from team members daily. With AgentHack, you can configure automatic extraction of key data from these emails (such as completion percentages and blocking issues), generating unified summary reports that save manual compilation time.

Intelligent Weather Integration

The weather functionality provides more than current temperature displays—it can trigger automated actions based on weather data:

  • Automatic reminders to bring rain gear on rainy days
  • Schedule adjustments in advance for extreme weather conditions
  • Suggestions for indoor or outdoor activities based on weather conditions

Case study: If you bicycle to work daily, you can configure AgentHack to check the weather at 6 AM each morning. If precipitation probability exceeds 50%, it automatically sends reminder emails suggesting alternative transportation options and notifying colleagues of potential delays.

Calendar and Schedule Optimization

Calendar integration helps you better manage time and commitments:

  • Automatic detection of schedule conflicts with proposed solutions
  • Background information on meeting participants before events
  • Automatic task priority adjustments based on schedule arrangements

Case study: As a consultant with multiple client meetings, AgentHack can analyze your calendar and send reminder emails one hour before each meeting containing the meeting location, participant list, and notes from previous meetings to help you prepare better.

Author’s reflection: My biggest takeaway from using AgentHack is recognizing that automation shouldn’t completely replace human decision-making but enhance human capabilities. The best automation systems handle repetitive tasks while leaving room for humans to make advanced decisions and engage in creative work. AgentHack successfully strikes this balance between automation and manual control.

Troubleshooting and Best Practices

Even with proper installation and configuration following the guide, you may encounter various issues during actual use. This section provides solutions to common problems and usage recommendations.

What common problems might you encounter when using AgentHack, and how can you resolve them? Common issues include process communication failures, API limit exceedances, and configuration errors—most can be resolved by checking environment configurations and log outputs.

Common Issue Diagnosis

Inter-process communication failures: If system components aren’t functioning properly, first verify all process IDs are correctly configured in each environment file. Use tools provided by the AO network to check if processes are running and responding normally.

API limit issues: Brevo and OpenWeather’s free API tiers have usage limits. If you encounter API call failures, check if you’ve exceeded these limits. Consider optimizing call frequency or upgrading to paid plans.

Initialization delays: Note that functionality requiring HTTP calls may take up to 40 minutes to fully process. This is normal behavior due to the distributed nature of the AO network. Be patient while initial processing completes.

Performance Optimization Recommendations

Adjust check intervals: Depending on your specific needs, you can adjust intervals for various checking tasks. More frequent checks provide more real-time data but increase API calls and system load.

Caching strategy: For infrequently changing data (like weather information), consider implementing caching mechanisms to reduce API calls while maintaining relatively fresh data.

Log monitoring: Regularly check system logs to understand operational status and potential issues. The Log Monitor component provides detailed operation logs to help diagnose problems.

Security Best Practices

API key protection: Ensure environment files containing API keys aren’t committed to public code repositories. Use environment variables or key management services to protect sensitive information.

Minimum permissions: Only grant AgentHack the minimum permissions necessary to perform its functions. Regularly review permission settings to ensure no unnecessary access rights.

Regular updates: Stay informed about AgentHack project updates and promptly apply security patches and feature improvements. The advantage of open-source projects is continuous community improvement, but users need to actively maintain them.

Conclusion and Future Outlook

AgentHack demonstrates the tremendous potential of decentralized personal assistant technology. By returning control to users while providing powerful automation capabilities, it points toward the future development direction of personal technology tools.

What technological trends does AgentHack represent, and what is its future development direction? AgentHack represents the trend of decentralized, user-controllable personal technology tools, with potential future expansion into more automation scenarios and integrated services.

Technical Significance and Value

AgentHack’s core value lies in rebalancing the relationship between technological advancement and personal control. In an era where most tech companies increasingly control user data and experiences, AgentHack offers an alternative: technology should serve users, not the reverse.

By using open-source technology and decentralized architecture, AgentHack ensures no single entity can control or limit the user experience. This model particularly appeals to technical users concerned about privacy and autonomy.

Development Potential

AgentHack, built on the AO network, has enormous expansion potential. Possible future development directions include:

  • Integration with more services (additional email providers, social media platforms, smart home devices)
  • More advanced natural language processing capabilities for more intuitive interactive experiences
  • Machine learning functionality for smarter personalized recommendations and automation
  • Cross-device synchronization providing consistent experiences across phones, tablets, computers, and other devices

Author’s final reflection: Through deep use and exploration of AgentHack, my most profound realization is that true technological innovation shouldn’t just make technology more powerful but should empower users more. AgentHack’s success lies not in how many complex features it includes but in how it presents these features in a user-controllable manner. This user-centered design philosophy is what we should pursue in all technology development.

Practical Summary / Action Checklist

One-page Overview

  1. Core functionality: Email management, weather updates, calendar integration, note-taking, token management
  2. System requirements: Node.js v16+, Yarn, AO wallet, Brevo and OpenWeather API keys
  3. Key processes: Agent process (main logic), Relay process (HTTP communication), Crontroller process (scheduled tasks)
  4. Configuration focus: Correctly set all environment variables (especially API keys and process IDs)
  5. Startup sequence: Install dependencies → Start Relay Monitor → Run initial setup → Start frontend
  6. Expected delays: HTTP-related functionality may require up to 40 minutes for initial processing
  7. Maintenance recommendations: Regularly check logs, monitor API usage, stay updated on project developments

Installation Checklist

  • [ ] Obtain Brevo API key
  • [ ] Obtain OpenWeather API key
  • [ ] Create AO wallet (if you don’t have one)
  • [ ] Create three AO processes (Agent, Relay, Crontroller)
  • [ ] Configure relay_monitor/.env file
  • [ ] Configure utilities/.env file
  • [ ] Configure front_end/.env file
  • [ ] Install all dependencies (relay_monitor, front_end, utilities)
  • [ ] Start Relay Monitor (yarn start)
  • [ ] Run initial setup (node getStarted.js)
  • [ ] Start frontend (yarn dev)

Frequently Asked Questions (FAQ)

Is there a cost to use AgentHack?
AgentHack itself is open-source and free, but you need to register for free accounts with Brevo and OpenWeather to obtain API keys. These services offer free tiers sufficient for personal use.

How much technical knowledge do I need to install AgentHack?
Installing AgentHack requires basic command-line operation knowledge and text editing skills. Following the guide step-by-step, most technical users can successfully complete installation.

Does AgentHack support mobile devices?
The frontend interface features responsive design and can be accessed in mobile browsers. However, there currently isn’t a dedicated mobile application.

What should I do if I encounter API limit issues?
Free accounts for Brevo and OpenWeather have usage limits. If you frequently encounter limit issues, consider upgrading to paid plans or optimizing call frequency.

Where is my data stored?
All data is stored in your own processes on the AO network. You aren’t the “product” of any centralized service, maintaining complete control over your data.

How does AgentHack protect my privacy?
Since the system runs in processes you control and uses open-source code, no data is sent to third parties (except necessary API calls like sending emails or obtaining weather data).

Can I customize AgentHack’s functionality?
Yes, AgentHack is an open-source project—you can modify the code according to your needs, adding new features or adjusting existing functionality.

How do I debug if the system has problems?
Check the log output from the Relay Monitor, which provides detailed operational information. Most problems can be resolved through log diagnosis.