Skip to main content
This page covers installation, enrollment, and CLI usage. For what Workspace Mirror is and how sync behaves, see Workspace Mirror.

​
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.

​
Install and connect (Easy)

1

Open the Computers panel

In SYMI, open the Computers panel and select Easy. Before enrollment, the panel may display “None connected yet.”
2

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.
3

Start setup in Terminal

Open Terminal on that computer and run:
The profile name keeps this connection separate from other named connections.
4

Generate an enrollment code

In SYMI, select Connect a computer. A pop-up generates a one-time enrollment code. Copy it.
5

Enter the code

Paste the code into Terminal when setup prompts for it and press Enter.
6

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.
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.

​
Install and connect (Advanced)

1

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:
The backslash continues the command onto the next line — copy both lines together. This downloads and runs the installer script from the displayed server.
2

Generate an enrollment code

Select Connect a computer in SYMI. A pop-up generates a one-time enrollment code. Copy it.
3

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.
4

Start setup if not prompted

If installation finishes without an enrollment prompt, start setup explicitly and enter the code when requested:

​
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

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

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:
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.
1

Confirm the client is running

Make sure the mirror client or background service is running.
2

Create a local test file

Create a small test file in a mirrored target and confirm that SYMI can see it.
3

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.
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

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

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

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

service uninstall removes the background service. To stop the service and remove this computer’s enrollment:
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

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

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

​
Command reference

​
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

1

Check status

Run status for the profile you enrolled. Check the sync target and local folder.
2

Check service status

Run service status for the same profile. If the installed service is stopped, start it.
3

Verify

Run verify. Check whether the saved settings are coherent and whether the server still recognizes this computer.
4

Test with a small file

Check the network connection and try a separate small test file in the reported mirrored target.
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

Workspace Mirror

How Workspace Mirror behaves and what gets synchronized.

Persistent Workspace

Understand which workspace files sync in the first place.