Local-first agent for macOS

# aictrlx: an agent that works on your Mac

One agent for code and the rest of your work — tests, mail, calendar, Drive, a real browser and macOS apps — that asks you first before it sends mail, changes your calendar or presses a button that submits, sends, deletes or buys.

 [Docs and use cases](https://aictrlx.ru/agent/docs) 

macOS now; other operating systems later.

## What it can do

### Code, end to end

Explores the repository, searches, reads, patches, runs the tests, reads the failures and fixes them — with checkpoints, resumable sessions, and `/diff` and `/undo` for what a task changed.

### Gmail

Searches with Gmail's query syntax, reads messages and threads, writes drafts and replies, labels and archives. Bulk triage by a search shows first how many messages, from whom and when.

### Google Calendar

Finds genuinely free slots from free/busy data — computed by code, not guessed by the model — and creates, changes and cancels events in the right time zone.

### Google Drive, read-only

Searches, lists folders, opens Docs, Sheets and Slides as text and saves a file into the workspace. It cannot change anything in Drive.

### A real browser

Chromium for sites no API or MCP server serves: page snapshots, clicks, forms, downloads and uploads. Sign-ins stay in profiles, and passwords are typed by reference — the model never sees them.

### macOS apps

Desktop applications through Accessibility: UI trees, clicks, typing and shortcuts. Each action is judged by what it acts on, and one run drives the desktop at a time.

### MCP servers

Register any MCP server and its tools become a capability; how risky they are is decided by your configuration, not by the server. Servers set up in Claude Desktop, Cursor, VS Code and other apps can be imported.

### Subagents

Splits a task into parts, runs the independent ones side by side and reviews the results against evidence. Code written in parallel comes back as change sets applied together or not at all.

### Queued and scheduled work

Queue a job or schedule recurring work in a real time zone, and a background worker runs it. When it needs you, it parks and waits rather than proceeding or giving up.

### Memory and plans

What you asked it to remember reaches the next run by itself, and a long task keeps a plan that a retry or a compacted conversation cannot take away.

## How it works with aictrlx.ru

Your aictrlx.ru account gives the Mac two things: its models and the phone relay. Both take the same project API key, and one command gets it.

1.  ### Sign in with one command
    
    `aictrlx login` shows a code and opens aictrlx.ru/device. You check the code, pick a project and what this Mac may do — “Models”, and “Relay for the phone” where your plan has it — and approve. The key is kept only in the macOS Keychain.
    
2.  ### Models through the service
    
    With “Models”, login registers the model `aictrlx` when the Mac has none for the service yet: the `coding` routing mode at `https://aictrlx.ru/v1`, an OpenAI-compatible API that picks a model for every request. It gets work once you allow remote models.
    
3.  ### The phone relay
    
    Away from home the Mac and the phone both dial out to `relay.aictrlx.ru`, which splices them. The phone's TLS to the Mac runs end to end inside, so the relay sees ciphertext and metadata, never content. It is off until `aictrlx phone relay on`.
    

What aictrlx login prints (an example)

```
$ aictrlx login
To sign this Mac in to aictrlx, open https://aictrlx.ru/device
and check that it shows the code   WDJB-MJHT
(opened in your browser). Waiting for you to approve it… Ctrl+C stops.
Signed in to aictrlx as anna@example.com — project "Default Project".
  key      "aictrlx — Anna's MacBook Pro", kept in the macOS Keychain only
  models   the model "aictrlx" (coding) at https://aictrlx.ru/v1 has this key — registered now
  relay    the phone relay key for relay.aictrlx.ru is set
Next (nothing else was changed):
  aictrlx config set model_privacy allow_remote   remote models get no work until you allow them
  aictrlx model policy --default aictrlx          send work to it
  aictrlx phone relay on                          reach this Mac from the phone away from home
```

## Your phone as a front end

The aictrlx Android app is a front end for the agent, like the terminal: the agent and its models stay on the Mac.

### Approvals with your fingerprint

Answer parked approvals one at a time; each decision is signed after your fingerprint (or the phone's PIN, if you allow it at pairing). There is no approve-all.

### Jobs, live

Queue, stop, pause, resume and continue jobs; follow a background job's run live and send it words, which it reads at its next step.

### Results, inbox, schedules

Read results and the inbox, see a job's subagents and the files it changed, and keep the schedules.

### Terminal windows and sharing

See the aictrlx windows open on the Mac and write to them; share a text, a link or a file from any app into a new task.

Pairing happens only at the Mac: `aictrlx phone pair` draws a QR code, the app scans it, and you compare six digits on both screens. At home the phone reaches the Mac directly; away from home, through the relay.

The phone decides nothing by itself: it cannot change a setting, a job's mode or a phone's routes, and it does no sign-ins, CAPTCHAs or one-time codes — those need you at the Mac.

## Safety and privacy

### Local first

The agent, its tools, its memory and the history of each folder live on your Mac. API keys and OAuth tokens are kept only in the macOS Keychain — never in a file, a log or anything the model sees.

### Approvals decided by code

Every call is rated by deterministic rules, not by the model. Sending mail and changing calendars always ask, with a preview built from the actual arguments; a send, a deletion or a purchase is confirmed on its own, never in a batch.

### Remote models only when you allow them

By default (`model_privacy local_only`) no model on somebody else's machine sees the agent's work. Mail, calendar, Drive, memory and computer use are on `local_only_capabilities` by default and stay off remote models even when you allow them.

### The relay never reads content

The phone's TLS to the Mac runs end to end: the relay copies ciphertext it cannot decrypt and learns only metadata — the account, the phones' ids and keys, addresses, times and sizes.

### Pages and mail are data

What other people wrote — mail, events, Drive files, web pages, MCP output — reaches the model fenced as data. A page can at most make the model propose an action, and that meets the same approvals.

### A sandbox and an honest verifier

On macOS every shell command runs, by default, in a Seatbelt sandbox: writes only inside the workspace and temp folders, network to localhost only. Before a run is called done, an independent verifier checks the diff and the changed files — and may say it cannot judge.

## Platforms

### macOS

Now. Computer use and the shell sandbox are macOS features.

### Other operating systems

Later: aictrlx will come to other operating systems.

### Android

The phone app: approvals, jobs and results, at home and away.

## Install

### aictrlx for macOS

Install with one command (Terminal on your Mac):

```bash
git clone https://github.com/aictrlx/aictrlx_agent.git aictrlx && cd aictrlx && ./install.sh
```

It installs aictrlx into `~/.local/share/aictrlx`, downloads the Chromium its browser uses and puts the `aictrlx` command on your PATH. It needs git and Python 3.12 or newer: without that Python the installer says how to get it (`brew install python@3.12`). When it has finished, open a new terminal window. To update: `git pull && ./install.sh` in the `aictrlx` folder.

[View on GitHub](https://github.com/aictrlx/aictrlx_agent)


#### Then, in the terminal

1.  `aictrlx login` sign this Mac in: approve the code on aictrlx.ru/device
2.  `aictrlx config set model_privacy allow_remote` remote models get no work until you allow them
3.  `aictrlx model policy --default aictrlx` send work to the service's model
4.  `aictrlx phone relay on` reach this Mac from the phone away from home
5.  `aictrlx` the interactive mode, in a project folder: describe a task in plain words

`aictrlx login` prints the three steps after it itself, each only while it is still to be taken. `aictrlx doctor` checks the environment.

### Android app

Approvals, jobs and results on your phone; pairing is at the Mac with `aictrlx phone pair`.

**Beta.** A beta version: things may still change, and bugs are possible.

For Android 10 and newer. The first time, Android asks you to allow installing apps from your browser; later versions install over this one.

[Download APK](https://aictrlx.ru/downloads/aictrlx-android.apk)


## Documentation and use cases

Getting started, the phone, the key commands, scenarios and answers to common questions.

 [Open the docs](https://aictrlx.ru/agent/docs)
