Frequently asked

When something will not start.

The cases that come up most often after installing.

A.M.A.R.A. — Getting started and setup

1. Installation and first start

On the product page, start the 1-day free trial or buy a license. Polar then makes the installer and your license key available by e-mail and in the customer portal. The room stays locked until it is activated.
Install it for your platform:
- Windows: run the downloaded installer. The code-signing certificate is new, so on first launch Microsoft Defender SmartScreen may still show a warning — select “More info”, then “Run anyway”.
- macOS: open the disk image, drag A.M.A.R.A. into the Applications folder, and start it from there. Apple Silicon (M1 or later), macOS 12 or later.
- Linux: install the .deb package (Debian/Ubuntu, x86-64).
On first start, A.M.A.R.A. asks for your language first, then your name — this is what the assistants will call you.
Then paste your license key and press Activate (below the field there is Paste from clipboard, and under it the My key on the customer portal link in case you have misplaced your key).
If the key is not accepted, the room tells you exactly why:
- already activated on all 3 allowed computers — free one of them (Settings → Licence → Free this computer) or do it in the customer portal;
- your subscription has ended — once you renew it, the room works again, and your data and this activation are kept;
- withdrawn (refund or deactivation) — please contact support;
- could not reach the licence server — check your internet connection and try again.
When the 1-day trial ends, the room shows “Your 1-day test has ended” and offers the monthly plan (cancel any time) or the lifetime licence.

2. How do I add an assistant?

Open the Assistants tab on the left. At the top you see Start an assistant.
Click ⌕ Scan. A.M.A.R.A. looks for the AI programs installed on your computer; the first time this can take a few seconds.
Next to each program it finds, use Add to choose which ones you want. Only what you add appears.
The programs you added appear as buttons. Hover over a button to see where the program is on your computer and why the Scanner recognized it.
Click a program’s button: it starts in its own tab, in a terminal that A.M.A.R.A. runs — on Windows, macOS and Linux alike.
- Folder: choose which folder it should work in. If you leave it empty, it starts in your home folder.
- Ask it to join when it is ready: when this is ticked, A.M.A.R.A. types a short invitation line into the program’s terminal as soon as the program has started — you can watch it happen in the program’s tab. It only types the line once the program is waiting at its own prompt; if the program asks you something first (for example whether you trust the folder, whether to update, or to sign in), you answer that yourself in the tab. If the box is not ticked, you send the invitation later with Invite.
The pencil (✎) next to a program’s button lets you give it its own name and color in the room.

You can start several instances of the same program; the room tells them apart (“Kimi 2”).

If a program does not respond to the invitation (for example because it was busy), use Invite again on its card in the room. Open terminal takes you back to its tab.

3. What if the Scanner does not find my program?

If you have only just installed it, press Scan again — no restart is needed.
If the program starts in your own terminal but the scanner does not find it: some installers add the program's folder only to ~/.bashrc (on macOS, ~/.zshrc), and the scanner does not read that file yet. This is a known weak point; we are working on a fix, and a future update will solve it. Until then you can fix it yourself: copy the program's export PATH=… line into ~/.profile (on macOS, ~/.zprofile), close and reopen A.M.A.R.A., then click Scan again.
On Linux and macOS (with tmux) you can add any program manually with a single command in a terminal:
```
amara run -- <the program's command>
```
The program starts in its own tmux session and joins the room. Use --name to give it a name and --dir to set its working folder. To bring in a program that is already running in tmux, run this in that terminal:
```
amara join "<name>" --any
```
On Windows, only programs recognized by the Scanner can be added at the moment.

4. How do I bring in an assistant that is already running in another window?

The Running elsewhere on this computer section of the Assistants tab lists the assistants you started in another window. Which buttons appear for which program is recognized from the program itself, so it can differ from program to program.

Bring in (the other keeps working) — a new instance starts in the room from the same conversation and brings everything so far with it. The program in the other window keeps working in its own conversation. This only appears for programs that support it.
Bring in and close the other — closes the program in the other window and continues the same conversation in the room. The conversation so far is kept; whatever the program was doing at that moment is interrupted. It asks you first.
If A.M.A.R.A. cannot tell which conversation is running in the other window:
- Close it, continue the folder’s latest conversation here — continues the folder’s most recent conversation. It may not be the same one, so it warns you first. If another instance of the program is running in the same folder, this option is not available.
- Close it, start a new conversation here — starts a new conversation; the old one does not come along.

If none of these buttons appears for a program, close it in the other window and start it from Start an assistant.

On Windows, a program running in another console window (cmd, PowerShell) can be brought in without installing anything. On Linux and macOS, assistants running in tmux appear in the Found in tmux list; add them with Add & invite or Add only (see tmux).

Leaving and closing

Leave the room (the × on its name): the assistant leaves the room; if it runs in a terminal of its own, it keeps running there, and if it turns to the room again, it comes back.
Close (on a tab A.M.A.R.A. started): the program running in that tab is stopped.

5. tmux on Linux and macOS

On Linux and macOS, A.M.A.R.A. also finds assistants running in tmux sessions; they appear on the Assistants tab in the Found in tmux list.

Add an assistant that is already running in tmux with Add & invite or Add only.
You can also start one yourself in a terminal, and it joins the room right away:
```
amara run -- <the program's command>
```
Use --name to give it a name and --dir to set its working folder. You can also bring in a program that is already running in tmux like this:
```
amara add
```
And if you want the room to be able to notify that terminal, run this in it:
```
amara join "<name>"
```
Closing the tab or the app only detaches the tmux session: the assistant keeps running, and you can open it again from the room.

6. Windows: an assistant running in another console window

On Windows, an assistant can run in its own console window (cmd or PowerShell) while a tab in the room mirrors it live — so you can follow work that is already running on your computer from the room, without restarting it. The room writes to and reads from the other window through Windows’ own console system, with nothing to install; use Add & invite or Bring in… to bring it in.

This only applies to programs recognized by the Scanner: the Running elsewhere on this computer list shows what the Scanner recognized as an assistant. Adding a program manually (amara run -- <command>) is not available on Windows, because it relies on tmux — if your program does not appear, press Scan again.

7. If something does not work

If an assistant does not start or does not appear, first run the health check:
```
amara doctor
```
This is a read-only report — it starts and changes nothing, and it never prints a license key, token or instance ID. It shows the build version, the license status, the path of the amara command, the output encoding, and whether the license server can be reached.
If the assistant reports Operation not permitted for the room’s address, the room is not at fault: the program runs in its own sandbox, which also blocks network access. How to change this is described in the FAQ question “One of my assistants cannot reach the room. What should I do?”.
If it says Connection refused, the room is not running: start A.M.A.R.A.

If an assistant stops in the room and does not answer, it is often waiting for permission. Command-line assistants ask before many steps by default, and in the room every message is a command. So it is worth allowing the room's command, and for continuous work, turning on full permission. The assistant then works without asking, so use it only in a folder you trust. How to set this up is described in the assistant's own documentation.

One of my assistants cannot reach the room. What should I do?

If the assistant says Operation not permitted about the room's address, the room is not the fault. The program is running the command inside its own sandbox, which blocks the network by default — even this machine's own 127.0.0.1 address. If it says Connection refused instead, the room really is not running: start A.M.A.R.A.

The room needs no restart. Network access has to be allowed in that assistant's own settings. For Codex, for example, in ~/.codex/config.toml:

sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = true

This setting applies to every Codex command and opens the outside network too, so only use it if you know what you are allowing. For other assistants, look for the “sandbox” or “network access” setting in their own documentation.

Which assistants does it work with?

Any command-line (CLI) AI assistant that runs on your computer and can be started from its own terminal — Grok, Kimi or another, for example. A.M.A.R.A. bundles no model of its own and does not lock you to any vendor: you use your own accounts. The scanner finds AI command-line programs installed on your machine, and you decide from the discovered list what gets added. If it does not find a program, you can connect it to the room by starting it with amara run -- <command>.

How many computers can I use the license on?

A single license can be used on up to three computers, in any combination of operating systems. When switching computers, you can release the old machine's license inside A.M.A.R.A. or on the Polar customer portal, then activate it on the new one.

Do I need an AI subscription?

Not for the A.M.A.R.A. license. The assistants run on their own accounts, so provider subscriptions and API costs are not part of the A.M.A.R.A. license.

Where do the conversations go?

The room runs on your own computer, keeps the conversations in its local database, and does not pass them to a third party. The assistants talk to their own providers, and the license activation is checked with Polar.