[← aictrlx for Mac](https://aictrlx.ru/agent)

# aictrlx for Mac: documentation

Getting started with the agent on your Mac, the phone app, the key commands and scenarios — with what exactly happens in each.

## 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)


The installer ends with `aictrlx doctor`, which checks the environment, the credential store, connectors and capabilities; run it again any time.

The agent can also work with a model on your Mac or your network — LM Studio, llama.cpp, Ollama, vLLM: an OpenAI-compatible endpoint with a model that calls tools. Point the agent at it:

Terminal

```
aictrlx config set model_base_url http://gpu-box:1234/v1
```

## Signing in to aictrlx.ru

`aictrlx login` signs this Mac in to your aictrlx.ru account with a device code: nothing is copied by hand.

1.  Run `aictrlx login` in the Mac's terminal. It shows a code and opens aictrlx.ru/device in your browser (with `--no-browser` it only prints the page and the code, to open on any device).
    
2.  On the page, sign in — or register — check that it shows the same code, pick a project and what this Mac may do: “Models” and, where your plan has it, “Relay for the phone”. Approve.
    
3.  The terminal finishes within seconds and prints what it kept and what to do next:
    

aictrlx login

```
$ 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
```

It keeps one ordinary project API key named “aictrlx — <this Mac>”, visible and revocable on the API keys page, and only in the macOS Keychain. With “Models” it is the key of the service's models — and when none is registered yet, login registers the model `aictrlx`, the `coding` routing mode; with “Relay” it is the phone relay key.

It never changes `model_privacy`, `local_only_capabilities`, the default model or the routing, or whether the relay route is on: it prints those commands instead.

### Options and related commands

-   `aictrlx login --no-browser`print the page and the code; open it on any device
-   `aictrlx login --name "Work Mac"`what the cabinet calls this Mac (default: its computer name)
-   `aictrlx login --server https://acp.example.com`your own deployment of the service
-   `aictrlx account`who this Mac is signed in as, its key, the relay, the balance
-   `aictrlx logout`revoke the key login made and remove it from this Mac

Signing in again replaces the key: one `aictrlx login` made is revoked, one made in the cabinet is left valid. After `aictrlx logout` the models registered there stay, without a key, until the next `aictrlx login`. Pasting a key by hand keeps working: `aictrlx model set-key` and `aictrlx phone relay set-key`.

## Models and privacy

Out of the box `model_privacy` is `local_only`: a model on somebody else's machine — the service's included — never sees the agent's work. The two steps `aictrlx login` prints send work to the service's model:

Terminal

```
aictrlx config set model_privacy allow_remote
aictrlx model policy --default aictrlx
```

A model you name — `/model` in the interactive mode, `--model` on `aictrlx run` — is the one the task runs on, or it fails saying why; never another in its place.

Mail, calendar, Drive, memory and computer use stay local whatever the privacy setting says (`local_only_capabilities`, by default `gmail,calendar,drive,memory,computer`): a task on a cloud model you named runs without them, and a conversation that already holds what they returned stays on local models. For that work, use a model on your Mac or network.

The model `aictrlx` uses the `coding` routing mode, which picks by coding ability, context size and tool support. Another mode — `auto`, `smart`, `fast` — or an exact model id of the catalog is registered by hand:

Terminal

```
aictrlx model add <name> --provider control-plane [--region production|self-hosted] [--base-url URL] [--model MODE|ID]
```

Costs are shown in roubles by default, and what the service billed for a call is shown as billed. Limits on what one task and one conversation may spend (`300rub`, say) are in `aictrlx settings --group limits`.

## The phone

The gateway the phone talks to runs inside `aictrlx daemon run` (or the service `aictrlx daemon install` sets up), one per Mac, and nothing listens until a phone is paired.

### Pairing by QR code

1.  Start the daemon: `aictrlx daemon run` — or `aictrlx daemon install` to have macOS start it at login (it shows exactly what it will write and run, then asks).
    
2.  Run `aictrlx phone pair`: it draws a QR code in the terminal, good once for 5 minutes.
    
3.  Scan it with the aictrlx app. Both screens show six digits: compare them and press `y` at the Mac. If the phone says the code was already used by another device, press `n`.
    
4.  The app asks at pairing whether the phone's screen-lock PIN may open the approval key instead of the fingerprint. Anyone who knows the PIN can then approve; turn it off to hold every approval to the fingerprint.
    

-   `aictrlx phone devices [--all]`paired phones, how they proved their keys
-   `aictrlx phone revoke <id>`cut one off; its schedules paused
-   `aictrlx phone status`the gateway, its listeners, its lease, the settings

### Approvals

When a background job reaches something that needs you — sending mail, changing a calendar — it parks: the request is saved with a preview built from the actual arguments, and the job waits. The phone shows it with every recipient and every guest listed, and a body shown only in part marked where it ends. You answer one request at a time, signed with your fingerprint. The job carries the action out when it resumes, and only if it still matches what you approved. At the Mac the same requests are in `aictrlx approvals`.

### Away from home: the relay

Away from home the phone reaches the Mac through `relay.aictrlx.ru`, without opening a port. It needs an API key of your aictrlx.ru account with the relay switch on: `aictrlx login` keeps one when you grant “Relay for the phone”. Then:

-   `aictrlx phone relay on`through the aictrlx service's relay, from anywhere; `relay off` turns it off
-   `aictrlx phone relay status`connected or not, the account's plan, why it was refused
-   `aictrlx phone relay set-key`your aictrlx service key, typed hidden, kept in the keychain — without `aictrlx login`

Paired phones learn the route from a signed route set — no new code. Whether your account may use the relay depends on your plan and the service's settings: [Pricing](https://aictrlx.ru/pricing).

## Key commands

### Tasks

-   `aictrlx`the interactive mode: tasks one after another, in this folder
-   `aictrlx --continue`carry on the latest conversation in this folder
-   `aictrlx run "Review the parser for bugs" --mode review`reads only; changes nothing
-   `aictrlx run "Tidy the changelog" --background`queue it instead of running it here

### Background work and approvals

-   `aictrlx jobs`queued, running, waiting and finished work
-   `aictrlx job watch <id>`follow a job's run, wherever it runs (Ctrl-C stops watching)
-   `aictrlx approvals`everything waiting for you
-   `aictrlx approval approve <id>`approve one request (or `approval reject <id>`)
-   `aictrlx notifications`what happened while you were away
-   `aictrlx schedules`each schedule, whether it is on, and when it next runs
-   `aictrlx daemon install`start the background worker at login: shows what it will write and run, then asks
-   `aictrlx daemon status`the queue, who holds what, the loaded models, what calls cost today

### State and settings

-   `aictrlx doctor`environment, credential store, connectors, capabilities
-   `aictrlx connectors`connections: status, account, granted permissions
-   `aictrlx mcp list`each MCP server: connected or why not, its tools
-   `aictrlx memories`everything it remembers, and how often it was used
-   `aictrlx actions`what the agent sent or changed outside this machine
-   `aictrlx settings`a menu: choose a group, a setting, a new value

### The aictrlx.ru account

-   `aictrlx login [--server URL] [--name NAME] [--no-browser]`sign this Mac in; approve in a browser
-   `aictrlx account`whom it is signed in as, the key, the relay, the balance
-   `aictrlx logout`revoke the key login made and remove it from this Mac

### Connecting Gmail, Calendar and Drive

You need your own Google OAuth client (a Desktop app client in Google Cloud Console, with the Gmail and Google Calendar APIs enabled). Then grant exactly the permissions you want — without `-p`, only read-only access is requested:

Terminal

```
aictrlx connector connect google-workspace \
    --client-secrets ~/Downloads/client_secret_XXX.json \
    -p gmail.read -p gmail.compose -p gmail.modify \
    -p calendar.read -p calendar.write -p drive.read
```

## Use cases

Each scenario is a request in plain words; the commands are the program's own examples.

### Fix a failing test, end to end

`aictrlx run "Fix the failing test in tests/test_parser.py"`

What happens: The agent runs the tests, reads the code, patches it and runs the tests again; every file is checkpointed before it changes. Before the run is done, an independent verifier — a separate model call that never sees the conversation — judges the diff and the changed files; if it cannot judge, the run finishes “not verified”, never passed for it. In the interactive mode `/diff` shows what the task changed and `/undo` puts it back.

### Triage the inbox

`aictrlx run "Find emails from today that probably need a reply from me"``aictrlx run "Archive the obvious newsletters from the last week"`

What happens: Search returns compact metadata — sender, subject, date, labels, a snippet — and full bodies are fetched only for the messages that matter. Archiving by a search asks first, in every mode, with a preview of how many messages, which dates and which senders; what is approved is exactly that set.

Needs: Gmail connected, and a model on your Mac or network: mail stays off remote models.

### Find a free hour next week

`aictrlx run "find the latest mail from Alex about the architecture meeting and suggest when we could meet next week"`

What happens: One task for one runtime: it searches the mail, reads the thread and computes genuinely free slots from free/busy data — by code, not by the model. Creating the event asks you first, with the calendar, the times and the guests in the preview.

Needs: Gmail and Calendar connected, and a model on your Mac or network.

### A site without an API

`aictrlx run "Check the order status on the supplier site" --headed`

What happens: The agent opens a real Chromium (`--headed` shows the window), reads the page as an accessibility snapshot and acts on its elements. Sign in once yourself with `aictrlx browser login <profile> --url https://site`: the profile keeps it, and the agent never sees the password. A click that submits, sends, deletes or buys asks you first, and a CAPTCHA or a one-time code is handed to you.

Needs: Chromium for the browser: `aictrlx browser install`, once per machine (`aictrlx browser status` checks it).

### A recurring job

`aictrlx schedule add "Triage my inbox" --every weekdays --at 08:30 --timezone Europe/Berlin`

What happens: Each time it comes round, the schedule queues an ordinary job and the daemon runs it; 08:30 stays 08:30 across a DST change. A schedule grants no permission: anything that would ask a person parks and waits, and `aictrlx notifications` says what happened while you were away.

Needs: The daemon running: `aictrlx daemon install`.

### Approve from the phone

What happens: A queued job reaches a send and parks. The phone shows the request — every recipient, the subject and the body, a cut one marked where it ends — and you approve it with your fingerprint: one request, one decision. The job sends it when it resumes, and only if the draft is still exactly what you approved; a draft edited since is not sent, and you are asked again. At the Mac the same request is in `aictrlx approvals`.

Needs: A paired phone; away from home, the relay (`aictrlx phone relay on`).

### Review a repository with subagents

`aictrlx run "Analyse this repository: have separate agents look at architecture, test quality and security, then give me one report" --agent-mode multi`

What happens: The run decides first: until it has delegated or said it will do the work itself, it may read and may not change anything. Each agent gets a brief, not the conversation, and a scope no wider than the run's; findings are merged by evidence and disagreements are kept side by side. It is not always faster: a task that is one thread of work is faster and cheaper done by one agent.

## Questions and answers

### What runs where?

The agent, its tools, its memory and the history of your work run and stay on your Mac. Models run where they are: on your Mac or network (LM Studio and the like), or at the service, at `https://aictrlx.ru/v1`. The phone is a front end: it shows and answers, and the work stays on the Mac.

### What is sent to the service?

Only when a task runs on the service's model, and only after you allowed remote models: everything a run sends a model — the task, the files the agent reads, tool results, the conversation. Mail, calendar, Drive, memory and computer use stay on the Mac by default. The API key goes only to the service it came from (and the relay key only to the relay). How the service keeps requests is in the Privacy Policy.

### What can the relay see, and what not?

Ciphertext and metadata: the account the Mac is bound to, the paired phones' ids and transport keys, the addresses both ends connect from, and when, for how long and how many bytes each session carried. It cannot see content — which job, which approval, any preview, task, message or result — nor the Mac's home-network addresses: all of that travels inside the TLS between the phone and the Mac, encrypted to keys the relay never holds. It can refuse, delay or drop connections.

### How much does it cost?

The service's models are billed as usual — from your balance or your plan's allowance, at the prices on the Pricing page — and `aictrlx account` shows the balance. A model on your Mac or network costs nothing. Spending limits per task and per conversation stop a run before a call that could pass them.

### Do I need an account?

For the service's models and the phone relay, yes: the Mac signs in to it with `aictrlx login`. With a model on your Mac or network the agent works without one.

### Windows or Linux?

aictrlx works on macOS now and will come to other operating systems later.

### How do I disconnect a Mac?

`aictrlx logout` revokes the key `aictrlx login` made and removes it from the Mac. In the cabinet, the «Agent for Mac» page lists every device signed in with `aictrlx login` and signs any of them out; any key can also be revoked on the API keys page.

[Pricing](https://aictrlx.ru/pricing)[Privacy Policy](https://aictrlx.ru/privacy)[Your devices](https://aictrlx.ru/app/agent)[API keys](https://aictrlx.ru/app/api-keys)

[About aictrlx for Mac](https://aictrlx.ru/agent)

## Need a key?

Sign up: the key is in the dashboard a minute later.

[Create a free account →](https://aictrlx.ru/register)

## What's new

New models, routing modes and API changes.

[Changelog →](https://aictrlx.ru/docs/changelog)
