> ## Documentation Index
> Fetch the complete documentation index at: https://radiusbrowser.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Other Macs

> Add a Mac you reach with ssh, install Radius on it, and run Radius commands there.

Radius can drive another Mac you own over ssh. You add the Mac once; after
that, any `radius` command runs there with `--on <name>`.

Radius uses your existing ssh setup. It never stores a password, never opens a
port, and never asks ssh's questions on your behalf: when ssh needs a person,
Radius tells you the command to run in a terminal.

## Add a Mac

List the hosts in your ssh config, then add one:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
radius machine hosts
radius machine add studio
```

`machine add` also accepts `user@host` and `user@host:port`.

Run from a terminal, `machine add` first logs in so ssh can ask for a
password, a code, or a new host key. That login stays open for ten idle
minutes and later commands reuse it.

If Radius is not installed on that Mac, `machine add` offers to install it.
Pass `--install` to install without being asked:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
radius machine add studio --install
```

The installer downloads the latest Radius, checks that it is signed by Radius
and accepted by Gatekeeper, and puts it in `/Applications`, or in
`~/Applications` when that user cannot write to `/Applications`. It never uses
`sudo`. To install a specific build, add `--download-url <https-url>`.

You can run the same installer by hand on any Mac:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
radius app install-script | ssh studio sh -s
```

## Macs you reach through Amika

A Mac that is not in your ssh config, such as one behind a router or in a
cloud, can be reached through [Amika](https://docs.amika.dev). Make it a
bare-metal rig there, then add it by rig name:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
radius machine hosts --amika
radius machine add amika:demo-mac
```

Radius runs the Amika CLI in place of ssh for that Mac; everything else is the
same, including `--install`, `machine ls`, and `--on`. When your Amika sign-in
lapses, Radius reports `needs_login` with the command to run:
`amika auth login`.

## See how each Mac is doing

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
radius machine ls
```

`machine ls` connects to every added Mac and reports its state now:

| State | Meaning |
| - | - |
| `connected` | Radius is running there and can take commands. |
| `app_not_running` | Radius is installed but not running. |
| `needs_login` | ssh needs a password, a code, or a host key. Run `radius machine login <name>`. |
| `needs_update` | Radius there is too old for this CLI. |
| `radius_missing` | Radius is no longer installed there. |
| `host_key_changed` | The Mac answers with a different host key than before. |
| `identity_changed` | A different Mac now answers at that address. |
| `unreachable` | ssh could not connect. The reason is included. |

Radius opens windows only in a logged-in desktop session. If nobody is logged
in at that Mac's screen, Radius cannot be started there from here, and
`machine ls` says so.

## Run commands there

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
radius --on studio app status
radius --on studio tab list
radius --on studio app status --launch
```

Everything after `--on <name>` runs on that Mac, and the command's output and
exit status come back unchanged. Paths are that Mac's paths: use absolute ones.

A command runs only on the Mac that was added under that name. If the address
now reaches a different Mac, the command fails with `identity_changed` and
nothing runs there; `machine update` checks the same before it installs.

A command is sent once. If the connection fails after the other Mac has started
it, Radius reports the failure and does not send it again, so a dropped
connection never starts the same agent turn twice.

## Manage the list

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
radius machine login studio        # log in again after needs_login
radius machine rename studio desk
radius machine update desk         # reinstall the latest Radius there
radius machine rm desk             # forget it; nothing is removed on that Mac
```

## Scripts and other programs

Every `machine` command accepts `--json`. A failure prints one JSON object on
standard error:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": {
    "code": "MACHINE_NEEDS_LOGIN",
    "message": "studio wants a login typed by a person (a password, a passphrase or a code)",
    "details": { "kind": "needs_login", "target": "studio", "command": "radius machine add studio" }
  }
}
```

`details.kind` is stable. When `details.command` is present, it is the exact
line a person runs in a terminal to get past the problem; a program can show
it, then run `radius machine add <target> --json` again to learn when it is
done. Adding a Mac that is already added the same way succeeds.

Machine failures exit with status `6`; an unknown machine name exits with `3`.

## Claude Code sessions on another Mac (experimental)

A Claude Code chat in this Mac's Radius can do its work on another Mac: the
chat, its permission prompts and the browser tools stay here, while file and
shell tools run there. Turn it on in Settings, AI, Other Macs (or start Radius
with `RADIUS_CLAUDE_REMOTE_WORKSPACES=1`) and ask the agent to move, for
example "continue this in \~/code/app on studio". It moves its own session with
a `switch_workspace` tool and can move back the same way. With no folder named
("move to studio"), the session starts in that Mac's home folder.

* The other Mac runs the same Claude Code release this Radius pins. If it is
  not there yet, Radius downloads it into `~/.radius/agent-runtimes` on that
  Mac and verifies it first.

* Nothing is signed in on the other Mac. Radius hands the session a credential
  when it starts: the API key or gateway token Radius already uses, or a
  one-year sign-in kept in this Mac's keychain. Choose Sign In under Settings,
  AI, Other Macs, or store a token yourself:

  ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
  claude setup-token
  security add-generic-password -U -s "Radius Remote Claude Code" -a "$USER" -w
  ```

* A Mac added with `radius machine add` is checked each time: if a different
  Mac now answers at its address, nothing is started there and no sign-in,
  file or conversation is sent to it.

* Files are not copied between Macs; the folder must already exist there.
  Asked for one that does not, the agent is told the closest folder that does
  and what is in it.
  Skills, attached files and the project's Claude memory are copied over, and
  memory written there comes back.

* A Mac that is reachable over ssh but not added yet can be named with
  `RADIUS_CLAUDE_REMOTE_HOSTS=name=ssh-target`.

The diff panel and file previews still show this Mac's folder.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.