Getting Started

A comprehensive guide to the installation, configuration, and execution of the AllvIa Local OS Agent. Estimated time is about 5 minutes.

What's covered: Environment Preparation → Installation & Build → Running the Agent → Using Core Commands → Workflow Extension

Prerequisites (macOS)

Ensure your environment is ready before starting on macOS.

Item	Requirement	Notes
Operating System	macOS 12+ (Monterey) or later	-
Rust	1.70 or later	Install via rustup.rs
Build Tools	Xcode Command Line Tools	`xcode-select --install`
OpenAI API Key	GPT-4 or GPT-3.5	Required for LLM analysis modules
Git	Latest version	For cloning the repository

Prerequisites (Windows)

Ensure your environment is ready before starting on Windows.

Item	Requirement	Notes
Operating System	Windows 10 / 11	64-bit recommended
Rust	1.70 or later (msvc toolchain)	Install via rustup.rs
Build Tools	Visual Studio Build Tools	Include C++ build tools
OpenAI API Key	GPT-4 or GPT-3.5	Required for LLM analysis modules
Git	Latest version	For cloning the repository

Note for macOS users: You must grant Accessibility permissions to your terminal app in System Settings → Privacy & Security → Accessibility. Without this, OS sensor data cannot be collected.

Note for Windows users: Ensure the PowerShell execution policy is set to `RemoteSigned`. Run the command `Set-ExecutionPolicy RemoteSigned` as an administrator.

Step 1 — Clone and Configure

Clone the AllvIa repository from GitHub and set up environment variables.

# Clone repository
git clone https://github.com/allvia-ai/ALLVIA.git
cd ALLVIA

# Create environment variable file
cp core/.env.example core/.env

# Clone repository
git clone https://github.com/allvia-ai/ALLVIA.git
cd ALLVIA

# Create environment variable file (PowerShell)
Copy-Item core/.env.example core/.env

Edit the .env file to set your OPENAI_API_KEY.

Note: You can obtain an API key from the OpenAI Dashboard.

Step 2 — Build

Build the Rust native binary. A release build takes about 2-3 minutes.

cargo build --manifest-path core/Cargo.toml --release

Binary location after build: ./core/target/release/local_os_agent

Binary location after build: .\core\target\release\local_os_agent.exe

Step 3 — Run the Agent

macOS Execution

# Run Quick Start script (Recommended)
    bash scripts/run_local.sh
    
    # Or run the release binary directly
    ./core/target/release/local_os_agent
    
    # Or use cargo run
    cargo run --manifest-path core/Cargo.toml --bin core --release

Run on Windows

Use the PowerShell script for Windows environments:

# Execute the PowerShell script (recommended)
.scripts
un_core.ps1 -CollectorImpl rust

# Or run directly
.core	arget
eleaselocal_os_agent.exe

When executed successfully, you'll see a prompt like this:

AllvIa Agent ready
Environment Scan: Found 349 apps
Collector: running on port 8080
Write Lock: enabled (use 'unlock' to disable)
Type 'help' for available commands.

>

Step 4 — Core Commands

Available commands while the agent is running:

Command	Description	Example
`surf`	Control entire OS with natural language (Core)	`surf "Open Safari and search for weather"`
`routine`	View results of recurring pattern analysis	`routine`
`recommend`	AI-based automation recommendations	`recommend`
`status`	Check system status	`status`
`control`	Application control	`control Safari open`
`exec`	Execute shell commands (Security policy applied)	`exec "echo hello"`
`build_workflow`	Natural language-based workflow generation	`build_workflow "Slack alert at 9 AM daily"`

Pattern Analysis & Recommendations

View collected usage patterns with routine and get AI suggestions with recommend:

> routine

Analyzed repeating patterns (Last 7 days):
  1. VS Code → Terminal → git commit  (3 times daily)
  2. Slack → Chrome → Google Docs     (5 times daily)
  3. Finder → Terminal → npm run dev   (4 times daily)

> recommend

3 Recommended automations:
  → Create git auto-commit workflow
  → Automate document review notifications
  → One-click dev server execution

Natural Language Workflow Creation

The build_workflow command transforms natural language prompts into n8n-compatible workflows:

> build_workflow "Send daily report to Slack at 9 AM every morning"

Analyzing with LLM...
Generating n8n workflow...
workflow_daily_report.json generation complete

Workflow registered in n8n.
Dashboard: http://localhost:5678

Step 5 — Workflow Expansion (Optional)

n8n Workflow Orchestration

Integrate n8n to manage complex multi-step workflows through a visual interface.

# Run n8n with Docker
docker compose up -d n8n

# Access n8n dashboard
# → http://localhost:5678

# Change runtime mode (env variable)
# STEER_N8N_RUNTIME=manual  (Default)
# STEER_N8N_RUNTIME=docker
# STEER_N8N_RUNTIME=npx

Data Collection & Batch Analysis

Collect OS sensor data with Rust Collector and analyze via batch pipelines:

# Integrated local execution (Recommended)
bash scripts/run_local.sh

# Run Collector independently
cargo build --manifest-path core/Cargo.toml --bin collector_rs
STEER_DB_PATH=./steer.db ./core/target/debug/collector_rs

# Batch analysis pipeline
bash scripts/run_pipeline_rs.sh configs/config.yaml

Build Desktop App (Tauri)

Build desktop applications for team deployment.

./scripts/rebuild_and_deploy.sh

After build, the .app file is created in web/src-tauri/target/release/bundle/macos/.

After build, the .exe installer is created in web/src-tauri/target/release/bundle/msi/ or nsis/.

Next Steps

You've completed your first automation run. Deepen your usage with these resources:

Tutorials — Pragmatic scenario guides for email classification, report generation, etc.
API Reference — Programmatic integration with the local core agent pipeline
FAQ — Frequently asked questions and troubleshooting

If you encounter issues, get help on GitHub Issues or contact our technical team directly.