# Set up VARUA on macOS with Lima

Lima runs VARUA inside a separate Ubuntu virtual machine. For **Apple Silicon Macs**, the simpler native setup is at https://varua.ca/guides/macos-native.

## 1. Install Lima

Open **Terminal on your Mac**. You need Homebrew from https://brew.sh.

```bash
brew install lima
```

## 2. Create the Ubuntu computer

Still in **Mac Terminal**, paste this on macOS 13 or newer:

```bash
limactl start --name=varua-rc --vm-type=vz --plain template:default
```

This creates an isolated VM without sharing your Mac folders.

## 3. Open Ubuntu

In **Mac Terminal**, run:

```bash
limactl shell varua-rc
```

From now on, paste commands **inside Ubuntu**. New to Lima? Open the setup help below.

## First time with Lima? Check your Ubuntu user and permissions

1. **Check Lima (Mac Terminal).** If you don't have Homebrew yet, install it from https://brew.sh and follow its **Next steps** to set up your Terminal. Check Lima and your new VM:

```bash
brew --version
limactl list
```

The `varua-rc` VM should show **Running**. If it is stopped, run `limactl start varua-rc` in Mac Terminal.

2. **Check your Ubuntu user (inside Ubuntu).** Lima **creates the Linux user automatically**, usually with your Mac username. Unlike WSL, you do **not** need to create another username or password. Paste:

```bash
whoami
id -nG
```

`whoami` should show your Linux username, **not** `root`. Always launch VARUA as your regular guest user, never as root.

3. **Check admin permissions (inside Ubuntu).** Lima normally sets up password-free `sudo` for its Linux guest user. Paste:

```bash
sudo -n true && echo "sudo ready"
```

You should see `sudo ready`. If you get an error, check that you opened the VM using `limactl shell varua-rc`. **Never start VARUA with sudo**, and don't change sudoers files to work around a failed check.

4. **Create a private project folder (inside Ubuntu).** Paste:

```bash
mkdir -p "$HOME/projects"
chmod 700 "$HOME/projects"
ls -ld "$HOME/projects"
```

Your Linux username should own this folder. Keep projects here, not in your Mac's home folder. Lima `--plain` mode does not mount Mac folders into Ubuntu.

## 4. Prepare Ubuntu

```bash
sudo apt update && sudo apt install -y ca-certificates curl jq
mkdir -p "$HOME/projects"
```

Keep your VARUA projects inside the Ubuntu `~/projects` folder.

## 5. Install VARUA

In **Ubuntu**, paste:

```bash
curl -fsSL https://downloads.varua.ca/varua-remote-control/install.sh | sh
```

## 6. Connect your computer

Inside **Ubuntu**, run one command:

```bash
varua-rc
```

- Select `~/projects` as your allowed folder.
- Keep file changes and command execution off until you need them.
- Select **Link device**. Open the pairing link in your **Mac browser**.
- Check the code, approve the connection, then select **Start Remote Control**.

> The VM cannot open your Mac browser automatically in plain mode. Copy the link from Ubuntu.

## 7. Check that it works

Open https://app.varua.ca/dashboard. Under **Devices**, your Ubuntu computer should say **Online**.

Keep the Ubuntu terminal running while using VARUA. Press **Ctrl+C** to stop.

## Need help?

- **Homebrew missing?** Install it using the instructions at https://brew.sh, then retry step 1.
- **Command not found?** In Ubuntu, run `export PATH="$HOME/.local/bin:$PATH"` and try again.
- **Computer offline?** Open the VM again with `limactl shell varua-rc`, then run `varua-rc`.
- **Want a direct Mac client?** Use the Apple Silicon guide: https://varua.ca/guides/macos-native.

## Optional: check guest isolation

Inside **Ubuntu**, run:

```bash
varua-rc doctor
```

Review the Linux guest-user, project-root and host-sharing checks. In **Mac Terminal**, you can also check that the VM uses the VZ backend with `limactl list varua-rc --format '{{.VMType}}'`. Keep the VM in `--plain` mode and do not forward host folders, ports or the SSH agent unless you need them. This VM is not an OS security sandbox.

## Optional: stop the Ubuntu VM

When finished, exit the Ubuntu shell. In **Mac Terminal**, run:

```bash
limactl stop varua-rc
```

Keep Lima in `--plain` mode. Don't share Mac folders or your SSH agent unless you specifically need that access. This VM is not a full security sandbox.
