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

# Set up Workspace Mirror

> Install the SYMI Mirror client on a computer, enroll it with your SYMI environment, and manage the background service that keeps your workspace in sync.

<Note>
  This page covers installation, enrollment, and CLI usage. For what Workspace Mirror is and how sync behaves, see [Workspace Mirror](/symi/workspace-mirror).
</Note>

## Before you begin

* Sign in to the SYMI environment whose workspace you want to connect.
* Use the computer that will hold the local mirrored files. You need Terminal access on that computer.
* Keep an internet connection available during installation, enrollment, and synchronization.
* The **Easy** installation path documented here uses macOS. The installer is named `symi-mirror-darwin-universal.pkg`.

## How enrollment works

Enrollment registers your computer with SYMI using a one-time code generated in the SYMI **Computers** panel. A **profile** separates the saved settings for a connection. The examples on the setup panel use the `4MINDS` profile and show `~/Symi-4MINDS` as the local folder (`~` is your home directory).

Setup connects your computer, performs the first sync, and starts the SYMI Mirror background service. When setup confirms the computer stays in sync in the background, you can close Terminal. The service starts again automatically when you log in — you don't need to re-run any command periodically.

## Choose an installation path

* **Easy** — download and open the macOS installer.
* **Advanced** — install from Terminal with a single command.

Complete one path, then confirm the connection using [Confirm the connection](#confirm-the-connection).

## Install and connect (Easy)

<Steps>
  <Step title="Open the Computers panel">
    In SYMI, open the **Computers** panel and select **Easy**. Before enrollment, the panel may display *"None connected yet."*
  </Step>

  <Step title="Download and open the installer">
    Select **Download `symi-mirror-darwin-universal.pkg`**. On the computer you want to connect, open the downloaded package and complete the installer prompts.
  </Step>

  <Step title="Start setup in Terminal">
    Open Terminal on that computer and run:

    ```bash theme={null}
    symi-mirror --profile 4MINDS setup
    ```

    The profile name keeps this connection separate from other named connections.
  </Step>

  <Step title="Generate an enrollment code">
    In SYMI, select **Connect a computer**. A pop-up generates a one-time enrollment code. Copy it.
  </Step>

  <Step title="Enter the code">
    Paste the code into Terminal when setup prompts for it and press Enter.
  </Step>

  <Step title="Wait for setup to finish">
    Setup confirms the computer is connected, completes the first sync, and starts the background service. When it confirms the computer stays in sync in the background, close Terminal.
  </Step>
</Steps>

<Tip>
  The panel's short instruction is `symi-mirror setup`. The command above makes the displayed `4MINDS` profile explicit. If your panel shows a different profile name, substitute that name and use it consistently in later commands. Check the local folder reported by `status` before editing mirrored files.
</Tip>

## Install and connect (Advanced)

<Steps>
  <Step title="Run the installer from Terminal">
    From the **Advanced** panel in SYMI, copy the installer command into Terminal on the computer you want to connect. Use the command from your own environment so the server address is correct.

    For the SYMI environment at `symi.4minds.ai`, the command is:

    ```bash theme={null}
    curl -fsSL https://symi.4minds.ai/mirror/install.sh | bash -s -- \
      --url wss://symi.4minds.ai
    ```

    The backslash continues the command onto the next line — copy both lines together. This downloads and runs the installer script from the displayed server.
  </Step>

  <Step title="Generate an enrollment code">
    Select **Connect a computer** in SYMI. A pop-up generates a one-time enrollment code. Copy it.
  </Step>

  <Step title="Enter the code">
    Paste the code into Terminal when the installer or setup flow prompts for it and press Enter. The connection information also identifies the profile, local folder, and protocol. The example shows profile `4MINDS`, folder `~/Symi-4MINDS`, and protocol `mirror-router-v1`.
  </Step>

  <Step title="Start setup if not prompted">
    If installation finishes without an enrollment prompt, start setup explicitly and enter the code when requested:

    ```bash theme={null}
    symi-mirror --profile 4MINDS setup --url wss://symi.4minds.ai
    ```
  </Step>
</Steps>

### About the server address

The `https://` address serves the installer. The `wss://` address identifies the secure WebSocket server used for the connection. Use the address shown by the SYMI environment you intend to connect to.

## Confirm the connection

### Check the saved enrollment

```bash theme={null}
symi-mirror --profile 4MINDS status
```

`status` is a read-only view of this computer's mirror enrollments, sync targets, and any pending recovery. Use it to confirm which workspace and local folder the client is configured to mirror.

### Verify that SYMI recognizes the computer

```bash theme={null}
symi-mirror --profile 4MINDS verify
```

`verify` checks whether the local saved settings are coherent and whether the server still recognizes this device. It is read-only and prints a JSON report in Terminal. Read the report for connection or enrollment issues before changing your configuration.

To check only the saved connection for a particular server:

```bash theme={null}
symi-mirror --profile 4MINDS verify --url wss://symi.4minds.ai
```

For `verify`, `--url` selects a connection that is already saved. It does not replace the saved server address or enroll the computer with a different server.

### Work in the mirrored folder

Open the local folder reported by setup or status. In the setup example, the parent folder is `~/Symi`, and `agent-workspace:main` synchronizes to `~/Symi/agent-workspace-main`. The Computers panel may show a different folder, such as `~/Symi-4MINDS`. Use the destination reported for your own connection.

<Steps>
  <Step title="Confirm the client is running">
    Make sure the mirror client or background service is running.
  </Step>

  <Step title="Create a local test file">
    Create a small test file in a mirrored target and confirm that SYMI can see it.
  </Step>

  <Step title="Ask SYMI to create a file">
    Ask SYMI to create or update a separate test file in the same target, then check that the change appears locally.
  </Step>
</Steps>

These checks confirm files are moving in both directions for your connection. Allow synchronization to finish before checking the other side, use separate test files, and avoid editing the same file from both sides at once while checking.

### First-sync output

After enrollment, setup displays `Running first sync` and a result for each synchronized target. The result identifies the workspace, destination folder, and counts of downloaded, unchanged, and trashed files. The line `Your workspaces are mirrored under` identifies the parent folder on this computer. Wait for the background-service confirmation before closing the setup window.

After setup starts the background service, synchronization continues automatically while the computer, network, and service are available.

## Manage the background service

The background service maintains the mirror independently of a foreground Terminal session. `service status` describes whether that process is running; the top-level `status` command describes enrollments and sync targets. Use both when diagnosing a connection.

### Install and start

```bash theme={null}
symi-mirror --profile 4MINDS service install
symi-mirror --profile 4MINDS service status
```

Setup normally starts the background service automatically after the first sync. Check `service status` first. Use `service install` if background service setup did not complete.

### Control an installed service

```bash theme={null}
symi-mirror --profile 4MINDS service start
symi-mirror --profile 4MINDS service restart
symi-mirror --profile 4MINDS service stop
```

`start` resumes the installed service, `restart` stops and starts it again, and `stop` pauses the service. Stopping the service does not remove the saved enrollment.

### Run in Terminal when needed

```bash theme={null}
symi-mirror --profile 4MINDS run
```

`run` continuously mirrors workspaces in a foreground process. It is not a one-time force-sync command and does not need to be run periodically. Use it when you want to observe the running client in Terminal or run without the background service. Stop the background service before starting a foreground run. End the foreground run with `Ctrl+C`, then start the service again for background operation.

### Remove the service or enrollment

```bash theme={null}
symi-mirror --profile 4MINDS service uninstall
```

`service uninstall` removes the background service. To stop the service and remove this computer's enrollment:

```bash theme={null}
symi-mirror --profile 4MINDS remove
```

Review `remove --help` before proceeding to understand the options available in your installed version. Treat `remove` as a connection removal command, not a pause button. To connect again, run `setup` and obtain a new enrollment code.

## Command help

### Find available commands

```bash theme={null}
symi-mirror
symi-mirror --help
symi-mirror --version
```

Running `symi-mirror` by itself prints the help output. `--help` also displays help, and `--version` prints the installed version. The short forms are `-h` and `-V`.

### Find options for a specific command

```bash theme={null}
symi-mirror setup --help
symi-mirror run --help
symi-mirror verify --help
symi-mirror remove --help
symi-mirror service --help
symi-mirror service install --help
```

The `help` command is also available: `symi-mirror help <command>`, and `service help <command>` provides help for a service subcommand.

### Command reference

| Command | What it does |
| - | - |
| `setup` | Enrolls the computer using a one-time code |
| `run` | Continuously mirrors workspaces in the foreground |
| `status` | Shows enrollments, targets, and pending recovery |
| `verify` | Checks saved connections |
| `remove` | Stops the mirror service and removes enrollment |
| `service` | Manages background operation (`install`/`start`/`stop`/etc.) |
| `help` | Explains command usage |

## Troubleshoot

### Terminal cannot find `symi-mirror`

Confirm that the installer completed on this computer. Open a new Terminal window and try `symi-mirror --version`. If it is still unavailable, keep the installer output and ask your administrator or support team to check the installation.

### Setup has no code or rejects the code

Return to the correct SYMI environment and select **Connect a computer**. Enter the newly generated code when setup prompts for it. Confirm that the profile and server you are using belong to that environment. Do not include enrollment codes in shared screenshots or support requests.

### Files are not appearing on the other side

<Steps>
  <Step title="Check status">
    Run `status` for the profile you enrolled. Check the sync target and local folder.
  </Step>

  <Step title="Check service status">
    Run `service status` for the same profile. If the installed service is stopped, start it.
  </Step>

  <Step title="Verify">
    Run `verify`. Check whether the saved settings are coherent and whether the server still recognizes this computer.
  </Step>

  <Step title="Test with a small file">
    Check the network connection and try a separate small test file in the reported mirrored target.
  </Step>
</Steps>

If `status` reports pending recovery, keep that output for diagnosis. Avoid repeatedly removing the enrollment as a first troubleshooting step.

### The service runs but verification reports a problem

A running process does not by itself confirm that its saved connection is valid. Check the selected profile and server. If verification indicates that enrollment needs to be restored, review `setup --help` and follow your administrator's guidance for reconnecting. Preserve your local files before making recovery changes.

### You want to pause or disconnect

* Use `service stop` for a temporary pause of background synchronization. Use `service start` to resume it.
* Use `remove` when you intend to stop the service and remove the computer's enrollment.
* `service uninstall` only removes the background service; the saved enrollment stays.

### Information to include with a support request

Provide the client version, operating system, selected profile, SYMI server address, service status, and relevant `status` or `verify` errors. Remove enrollment codes, credentials, private file contents, and sensitive local paths before sharing diagnostic output.

## Next steps

<CardGroup cols={2}>
  <Card title="Workspace Mirror" icon="folder-tree" href="/symi/workspace-mirror">
    How Workspace Mirror behaves and what gets synchronized.
  </Card>

  <Card title="Persistent Workspace" icon="folder" href="/symi/persistent-workspace">
    Understand which workspace files sync in the first place.
  </Card>
</CardGroup>