First Run Guide

December 21, 2025 · View on GitHub

This guide walks you through the initial setup and configuration of iDO after installation.

Prerequisites

Make sure you've completed the Installation Guide first.

Starting the Application

Development Mode

For development, you have several options:

Option 1: Frontend Only (Fastest)

pnpm dev
  • Starts React dev server at http://localhost:5173
  • Hot module replacement (HMR) for instant updates
  • Use when working on UI without backend changes
pnpm tauri:dev:gen-ts
  • Starts complete desktop application
  • Auto-generates TypeScript client from Python handlers
  • Use when working on both frontend and backend

Option 3: Backend API Server

uvicorn app:app --reload

Initial Configuration

1. Grant System Permissions (macOS/Linux)

On first run, iDO will request system permissions:

macOS

  • Accessibility: Required to monitor keyboard and mouse events
  • Screen Recording: Required to capture screenshots

The app will guide you through granting these permissions in System Settings.

Linux

Permissions are typically granted automatically, but you may need to run:

# Add user to input group
sudo usermod -a -G input $USER

2. Configure LLM Provider

iDO requires an LLM provider for activity analysis:

  1. Open Settings → LLM Configuration
  2. Choose your provider:
    • OpenAI (recommended)
    • Compatible OpenAI API endpoints
  3. Enter your API key
  4. Select a model (e.g., gpt-4 or gpt-3.5-turbo)
  5. Click Test Connection to verify

Privacy Note: LLM calls are made with your API key. No data is sent to iDO servers.

3. Configure Screen Capture

Choose which monitors to capture:

  1. Open Settings → Screen Capture
  2. View detected monitors
  3. Toggle monitors on/off
  4. Click Save

By default, only the primary monitor is enabled.

4. Adjust Screenshot Settings (Optional)

Fine-tune screenshot behavior:

  1. Open Settings → Screenshot Settings
  2. Configure:
    • Capture Interval: How often to take screenshots (default: 1 second)
    • Save Path: Where to store screenshots (default: ~/.config/ido/screenshots)
    • Image Quality: Balance between quality and disk space (default: 85%)
    • Image Optimization: Enable smart deduplication (recommended: enabled)

Verify Everything Works

1. Check Perception Layer

# View real-time stats
# In the app: Dashboard → System Status

You should see:

  • ✅ Keyboard events being captured
  • ✅ Mouse events being captured
  • ✅ Screenshots being taken

2. Test Processing Pipeline

  1. Use your computer normally for 1-2 minutes
  2. Navigate to Activity Timeline
  3. You should see activities being created with:
    • Event titles and descriptions
    • Associated screenshots
    • Timestamps

3. Test Agent System

  1. Open Agents view
  2. Select an activity
  3. Click Generate Tasks
  4. Agents should analyze the activity and suggest tasks

Understanding the Interface

Dashboard

  • System status and statistics
  • Active model information
  • Processing pipeline status

Activity Timeline

  • Chronological view of your activities
  • Grouped by date with sticky headers
  • Click any activity for details

Agents

  • AI-generated task recommendations
  • Task priority and status
  • Agent execution results

Settings

  • LLM configuration
  • Screen capture preferences
  • System permissions
  • UI preferences (theme, language)

Common First-Run Issues

No Events Being Captured

Symptoms: Dashboard shows 0 events

Solutions:

  1. Check system permissions are granted
  2. Verify perception layer is running (Dashboard → System Status)
  3. Restart the application

LLM Connection Failed

Symptoms: "Test Connection" fails

Solutions:

  1. Verify API key is correct
  2. Check internet connection
  3. Ensure API endpoint is reachable
  4. Try a different model

Screenshots Not Saving

Symptoms: No images in activity details

Solutions:

  1. Check screen capture permissions (macOS)
  2. Verify save path is writable
  3. Ensure at least one monitor is enabled in settings
  4. Check disk space

Application Won't Start

Symptoms: Crash or error on startup

Solutions:

  1. Check logs: ~/.config/ido/logs/
  2. Verify all dependencies installed: pnpm setup
  3. Try clean build: pnpm clean && pnpm tauri dev
  4. Check Troubleshooting Guide

Next Steps

Now that iDO is running:

Data and Privacy

Where is Data Stored?

All data is stored locally:

  • Database: ~/.config/ido/ido.db (SQLite)
  • Screenshots: ~/.config/ido/screenshots/ (configurable)
  • Logs: ~/.config/ido/logs/
  • Config: ~/.config/ido/config.toml

What Gets Sent to LLM?

Only when processing activities:

  • Screenshot images (as base64)
  • Keyboard/mouse event summaries (no raw keystrokes)
  • Timestamps and window titles

No cloud storage - Everything stays on your device except LLM API calls.

Need Help?