Install on your computer
Install remotxai on the computer where your agents run. It runs in the background and starts when you log in.
Before you start
Section titled “Before you start”- macOS (Apple silicon or Intel) or Linux (x64). No Windows.
- A normal user account. The installer won’t run as root.
curlandtaron the computer.- About 170 MB to 185 MB to download and 490 MB to 510 MB on disk. Node.js is included.
claude,codexorpiinstalled and signed in. remotxai doesn’t sign in for you.
Install
Section titled “Install”- Open a terminal on the computer.
- Run:
curl -fsSL https://app.remotxai.com/install.sh | shThe installer checks the signature and hash of what it downloads, unpacks it into ~/.remotxai, adds ~/.remotxai/bin to your shell profile and starts the background service. In an interactive terminal it then runs remotxai up for you and opens your browser, so you can go straight to Connect it to your account. In a script it prints the command to run. The service needs one agent program on your path: with none installed it stops and says it did not become ready, so install and sign in to one, then run remotxai service install again.
- Open a new terminal window so the
remotxaicommand is on your path.
Check that it works
Section titled “Check that it works”Run:
remotxai doctorEvery line should say PASS. WARN is fine until you use that feature. FAIL names what to fix; see Troubleshooting.
On Linux, terminal features are limited for now. Sessions you start from the phone work normally.
On macOS: let Remotxai into your folders
Section titled “On macOS: let Remotxai into your folders”On a Mac the service runs as an app called Remotxai (~/Applications/Remotxai.app). macOS asks once per folder before it lets the app into Downloads, Desktop or Documents.
- When macOS asks whether Remotxai may access a folder, click Allow.
- If you clicked Don’t Allow, turn the folder on under System Settings, Privacy & Security, Files and Folders, Remotxai.
Allow only the folders your agents need. Don’t add Remotxai to Full Disk Access.
If an agent fails with Operation not permitted, remotxai doctor shows a folder access line naming the refused folder.
You allow it once. Updates replace the runtime under ~/.remotxai and leave the app alone, so macOS keeps your choice. macOS ties the choice to the app’s exact launcher, which your computer builds and signs itself. Building the launcher needs the Xcode command line tools (xcode-select --install). Without them the service runs as plain node, which macOS cannot list, and remotxai doctor says so. In the rare release that changes the launcher, service install says it rebuilt the app and macOS asks again.
The app’s launcher only starts the remotxai runtimes under ~/.remotxai/runtime: their own node with the service entry, nothing else, and it drops NODE_OPTIONS and DYLD_* variables. A program that runs as your user can still edit the runtime files under ~/.remotxai and restart the service, and the changed code then gets the folders you allowed. So treat the folders you allow Remotxai as folders anything running as your user can reach through it.
remotxai service uninstall deletes the app and resets its folder access. --keep-app keeps both, for example before a reinstall.
Connect it to your account
Section titled “Connect it to your account”Run:
remotxai upIt opens the approve page with the code filled in, and prints the page and code. Over SSH or with no display it prints a QR code; --no-browser does the same.
- Sign in on the page if it asks. The page fetches the check code from the computer itself, through a page on
127.0.0.1, and shows it above an Add {computer} button: Check that this matches your terminal. The fingerprint is under Details. - Compare the code with the
check codeline in your terminal. When they match, tap Add {computer}, and confirm with your passkey. When they don’t, tap Cancel.
If you opened the printed page yourself, or on another device, the page shows the fingerprint, and when your browser can approve computers in the organisation, a check code next to Approve. Compare it with the check code line in your terminal and tick The code on the computer matches before you tap Approve.
You type nothing at the terminal. Right after you approve, the page hands over to the computer through a page on 127.0.0.1 and comes back. The terminal shows the account, the browser that approved and the organisation, so you can check they are yours. If no hand-over arrives within 30 seconds, for example because you approved on your phone, the terminal asks for the computer’s login password or Touch ID, with the account and organisation that approved it in the prompt. Where the system can’t ask, it asks you to type the account email instead.
The page ends on You can close this tab when the computer is ready, and the terminal ends on one line to match: Ready. <computer> is in <organisation>. When your browser can’t approve computers, the computer still joins but waits: the page and the terminal say an admin of the organisation has to approve it, and the admins see it on Home and on its Computers row.
It then shows under Settings, Computers. remotxai up needs an interactive terminal. If the code expires, run it again.
A computer belongs to one organisation at a time. To move it, run remotxai logout, then remotxai up.
If you are the first in a new organisation
Section titled “If you are the first in a new organisation”The first computer of an organisation is permanent, so before it creates the organisation the computer asks once for your login password or Touch ID. When the approve page was opened by remotxai up on this computer, that one prompt also approves the browser you approved with. The browser takes the organisation’s codes from the computer through 127.0.0.1 and the page ends on {computer} is ready, with no codes to type. The terminal prints one line naming the browser, your account, a short device id and its access. remotxai up --verbose also prints the browser’s limits and the organisation’s codes.
Where the system can’t ask for your password, the computer stays pending until you approve your first browser. In the browser remotxai up opened, the app shows Approve on my computer. Choose it while that remotxai up is still waiting, up to 10 minutes. The terminal asks for your password or Touch ID, or, where the system can’t ask, for the 16-character device code the browser shows. Only that browser can be your first. A browser on another device signs in with your passkey once the first one is in.
If remotxai up stopped waiting before your first browser was approved, run remotxai up again on the computer’s desktop. It opens your browser on the same step: sign in, tap Approve on my computer, and confirm with your password or Touch ID. You can do this any time in the 24 hours the computer stays pending. Once they run out, remotxai up asks you to approve the computer once more and starts a new 24 hours.
The first computer of an organisation needs a desktop session on that computer, because only a browser that remotxai up opens there can become your first browser. Approve it in the browser remotxai up opened on the computer. When that page doesn’t hand over to the computer within 30 seconds, remotxai up stops before it creates the organisation and signs nothing. That happens over SSH, with no display, with --no-browser or --verify, when the browser didn’t open, when it blocks pages on 127.0.0.1, or when you approved on another device. Run it again from the computer’s own desktop session and approve in the browser it opens. Later computers in the organisation can join over SSH or with no display.
If the organisation already has a computer
Section titled “If the organisation already has a computer”The computer has to trust the organisation’s account code. When you approved from a browser on this computer that is already approved in the organisation, the browser hands its own copy of the code to the terminal and the computer checks it. A mismatch stops with an error and nothing is trusted. A match still counts as not compared yet, because the page that read the browser’s copy comes from the remotxai service too.
Otherwise the computer trusts the code on first use and says so: Pinned <organisation>'s account code on first use. It prints the account code and the latest change code. Compare them with a device already in the organisation by running remotxai lock verify; until you do, remotxai status, remotxai doctor and the app mark the pin as not compared yet. To compare before anything is trusted, run remotxai up --verify instead. It asks for your account email and both codes. If the organisation has no computer yet, its owner has to connect a personal one first.
Next: start your first session. To connect a phone straight to this computer instead, pair your phone.