FAQ

We've compiled frequently asked questions and solutions regarding installation, operation, security, and troubleshooting.

General

What is AllvIa?

AllvIa is a user-behavior-based automation agent. It analyzes computer usage patterns at the OS level to automatically detect repetitive tasks, and the AI recommends and executes optimal automations. It's implemented as a Rust native binary, providing high stability and processing performance.

Which operating systems are supported?

macOS 12+ (Monterey or later) is the required/recommended environment. Windows execution is available through scripts/run_core.ps1, and Linux can be compiled through the Rust-native codebase.

Can I control my computer using natural language?

Yes. By entering natural language instructions like "Search for weather" or "Create a note in Notes" with the surf command, intent_router analyzes intent, plan_builder generates an execution plan, and visual_driver and browser_automation control the OS directly. We also support complex multi-app scenarios that connect multiple apps.

Can I use it offline?

Data collection (routine, status) and application control (control, exec) work offline. However, LLM-based analysis (recommend) and workflow generation (build_workflow) require an OpenAI API connection. A complete offline mode is on our future roadmap.

Is it free to use?

The AllvIa core agent is open-source and available for free. Additional operational features vary by plan. Detailed pricing information can be found on the Pricing page.

Installation & Setup

Is an OpenAI API Key absolutely necessary?

Yes. OpenAI API is used for LLM-based behavioral pattern analysis (analyzer.rs) and natural language workflow generation (build_workflow). You must set OPENAI_API_KEY in your .env file. We support both GPT-3.5 and GPT-4 models.

Why is Accessibility permission needed on macOS?

The OS sensor uses macOS's Accessibility API to collect app switching, active windows, and system events. Grant permission to your terminal app in System Settings → Privacy & Security → Accessibility.

Can I use it without n8n?

Yes. n8n is an optional workflow orchestration layer. Core features of the agent (routine, recommend, exec, control) work independently without n8n. Add n8n when you need to visually manage complex multi-step workflows.

What if the build fails?

Check the following in order:

• Verify Rust version is 1.70 or higher: rustup update && rustc --version
• Check if Xcode Command Line Tools are installed (macOS): xcode-select --install
• Check if Visual Studio C++ Build Tools are installed (Windows)
• Check network connection — an internet connection is required to download Cargo dependencies

Security & Data

How is security handled?

AllvIa applies a 5-layer security model based on Zero Trust principles:

• PolicyEngine (policy.rs): Classifies actions into 3 levels: Safe / Caution / Critical
• CommandClassifier (security.rs): Automatically analyzes and blocks risky shell commands
• ToolPolicy (tool_policy.rs): Manages per-tool Allow/Denylists based on environment variables
• PrivacyGuard (privacy.rs): Automatically masks PII such as emails and card numbers before saving to the DB
• API Auth (api_server.rs): Applies middleware authentication based on STEER_API_KEY
• Write Lock: Default locked state with timed auto-relocking to prevent mistakes
• Kill Switch: Instant process termination when Esc is pressed multiple times

Where is the collected data stored?

All data is stored in a local SQLite database (steer.db). No data is sent to external servers. Only summarized pattern data is sent to the OpenAI API during LLM analysis; raw event data is never transmitted.

Data Retention Cycle

The Rust Collector manages the following data lifecycle (based on config.yaml):

• Raw Events: Automatically deleted after 7 days (raw_events_days: 7)
• Session Data: Kept for 30 days (sessions_days: 30)
• Routine Candidates: Kept for 90 days (routine_candidates_days: 90)
• Max DB Size: 500MB (max_db_mb: 500)

Performance & Scalability

Plan Capacity Guidance

The local Core API does not enforce a fixed global rate-limit middleware by default. Operational limits are applied by deployment and plan policy.

Does the agent impact system resources?

As a Rust native binary, AllvIa typically uses less than 1% CPU and under 50MB of memory. The Collector's data collection runs asynchronously in the background.

Can it be deployed for teams?

Yes. Team-scale deployment is possible in the following ways:

• Tauri Desktop App: Bundle as .app / .exe and distribute to team members
• n8n Workflow Sharing: Entire teams can use the same automation workflows
• Self-Healing Guardian: steer-guardian.sh ensures automatic restarts upon process crashes

Troubleshooting

Automation isn't running

Check the following in order:

1. Verify the agent is running correctly with the status command
2. Ensure trigger settings are correct (Webhook URL, schedule, etc.)
3. Verify connector authentication hasn't expired
4. Check Write Lock status — execute unlock if necessary
5. Check error messages in execution history: GET /api/agent/task-runs?status=failed

Processing is slow

Try the following optimizations:

• Enable Batch Mode: Switch to batch analysis for large data processing
• Verify Release Build: Ensure you're using an optimized binary with cargo build --release
• Database Optimization: Run a VACUUM query if the steer.db file is large
• Adjust Collector Interval: Change collection frequency via the STEER_COLLECTOR_INTERVAL environment variable

Webhook transmission fails

Failed webhooks are retried up to 5 times using exponential backoff. If it still fails:

• Verify the target URL is accessible
• Check HTTPS certificate validity
• Ensure the AllvIa service's IP is allowed in your firewall
• Verify response time is within 30 seconds (timeout threshold)

If you have unresolved issues, please open an issue on GitHub Issues or contact our technical team directly.