Desktop Agent

The Komand desktop agent is a background service that runs on macOS, Windows, and Linux. It gives your AI agents secure access to local files, tools, and system capabilities — extending Komand beyond the browser and messaging channels to your local machine.

Features

File Access

Agents can read, search, and organise local files:

Search — find files by name, content, or metadata
Read — extract text from documents, spreadsheets, and PDFs
Organise — move, rename, and categorise files based on instructions
Watch — monitor folders for new files and process them automatically

Tool Integration

Execute local CLI tools and scripts on behalf of the agent:

Shell commands — run terminal commands with output capture
Script execution — run Python, Node.js, or shell scripts
Build tools — trigger builds, tests, and deployments
Git operations — commit, push, and manage repositories

System Information

Agents can query system status and environment:

Process monitoring — check running processes and resource usage
Disk usage — report storage consumption and identify large files
Environment — read environment variables and system configuration
Network — check connectivity and DNS resolution

Offline Mode

The desktop agent can work with local LLM providers when cloud access isn’t available:

Ollama integration — use locally-hosted models
LM Studio — connect to local model servers
Fallback — automatically switch to local models when cloud is unreachable

Use Cases

Document Management

You:   "Find all invoices from last quarter and summarize them"
Agent: "Found 23 invoices in ~/Documents/Invoices/2026-Q1/:
        - Total: $47,850
        - Largest: $12,500 (Acme Corp, Jan 15)
        - Overdue: 3 invoices ($8,200 total)
        Want me to create a summary spreadsheet?"

Development

You:   "Run the test suite and tell me what failed"
Agent: "Test results: 142 passed, 3 failed:
        1. test_user_login — assertion error on line 45
        2. test_payment_flow — timeout after 30s
        3. test_email_send — mock not configured
        The login test looks like a regression from yesterday's auth changes."

System Administration

You:   "Check disk usage and clean up temp files over 30 days old"
Agent: "Disk usage: 78% (312GB / 400GB)
        Found 4.2GB of temp files older than 30 days:
        - /tmp: 1.8GB (build artifacts)
        - ~/.cache: 2.4GB (package caches)
        Cleaned up 4.2GB. Disk usage now 77%."

Local Automation

You:   "Watch the ~/Downloads folder and process new CSV files as they arrive"
Agent: "Watching ~/Downloads for new CSV files. When I detect one, I'll:
        1. Validate the column headers
        2. Import into the contacts database
        3. Send you a summary notification
        Currently watching. I'll notify you when a file arrives."

Architecture

The desktop agent runs as a lightweight background service:

Desktop Agent (background service)
  ├── File System Watcher
  ├── Tool Executor (sandboxed)
  ├── System Info Collector
  └── API Client
         │
         ▼
    Komand REST API

System tray / menu bar — quick access to status, pause, and settings
API client — connects to your Komand instance (local or cloud)
Local execution — tools and scripts run on your machine, not in the cloud
Event-driven — watches for file changes, cron triggers, and incoming commands

Supported Platforms

Platform	Minimum Version	Status
macOS	13 (Ventura)	In development
Windows	10 (21H2)	In development
Linux	Ubuntu 22.04 / Fedora 38	In development

Security

The desktop agent operates under strict security controls because it has access to your local file system and tools:

Permission Prompts

All file and tool access requires explicit user approval:

First-time access — the agent asks permission before accessing a new directory or running a new tool
Allowlists — pre-approve specific directories and tools for unattended operation
Denylists — permanently block access to sensitive locations (e.g., ~/.ssh, ~/.gnupg)

Sandboxed Execution

Scripts and tools run in restricted environments:

Working directory — confined to a designated workspace
No root access — commands run as the current user, never elevated
Resource limits — CPU, memory, and time limits on executions
Network restrictions — outbound network access requires explicit permission

Audit Logging

All local actions are logged:

File operations — reads, writes, moves, deletes with full paths
Tool executions — commands, arguments, exit codes, output
System queries — what information was accessed and when
Logs sync to the Komand server for centralised audit trail

Kill Switch

Instantly stop all agent activity:

System tray — one-click pause/stop from the menu bar
CLI — komand agent stop to halt all local operations
Keyboard shortcut — configurable hotkey for emergency stop
Auto-stop — agent pauses if it detects unexpected behaviour

Configuration

The desktop agent is configured via ~/.komand/desktop-agent.json:

{
  "server": "http://localhost:5000",
  "token": "YOUR_API_TOKEN",
  "agent": "default",
  "allowedDirectories": [
    "~/Documents",
    "~/Projects"
  ],
  "blockedDirectories": [
    "~/.ssh",
    "~/.gnupg",
    "~/.aws"
  ],
  "allowedTools": [
    "git",
    "npm",
    "python3"
  ],
  "autoStart": true,
  "offlineModel": "ollama:llama3"
}