DISCOVERY · CONNECTOR
Syniray Connector
Syniray Code, in your own folders.
Install the connector on your computer, pair it with your Syniray account and approve exactly which folders and permissions the agent gets. This guide takes you through it on macOS and Windows.
Open Computers in Syniray CodeOverview
Syniray Code, working on your computer
The Syniray Connector is a small Node.js program that lets Syniray Code run its agent in folders on your own computer instead of Syniray's cloud. Once it is paired and running, a session on “My computer” reads and changes files there, runs commands if you allow it, and uses Syniray's models, your own API key or a local model.
You decide twice what it may touch: in Syniray you choose the folders and the permissions, and on the computer you approve them. The connector checks every operation against what is in force on the computer itself, and it does not listen for connections: it calls out to Syniray and waits for work.
This guide covers version 0.16.1. Syniray has run it on macOS, with its self-tests and the report of what the computer can build with (the toolchain), and ran the self-tests of the downloadable ZIP on Linux (Ubuntu 24.04, in a virtual machine). On Windows 11 it tested version 0.14.4 against a test server rather than the real service, directly in PowerShell and in WSL 1; version 0.16.1 adds the toolchain report and has not been run on Windows. WSL 2 could not be tested.
Before you start
What you need
A Pro or Max plan
Running Syniray Code on your own computer is included in Pro and Max. You pair the computer from your account, in Syniray Code.
Included in: ProMax
Node.js 18 or later
The connector is a Node.js program with no packages of its own to install. npm is needed only to install the optional Syniray Browser.
macOS, or Windows with WSL
A terminal and an internet connection that reaches api.syniray.ai over HTTPS. Syniray has run the connector on macOS, and on Windows 11 in PowerShell and in WSL 1 with Ubuntu — on Windows, against a test server. WSL 2 was not tested.
Syniray Browser — optional
Only if the agent should open web pages on your computer: a separate Chromium of about 150 MB, installed with one command — on macOS, or on Windows directly in PowerShell (not in WSL 1).
Installation
Install it, step by step
Choose your system. Each block has a Copy button that copies all of its lines. XXXX-XXXX, ABC123 and YOUR-NAME are examples: replace them with the code Syniray shows you, the code your computer prints and the name of your Windows user folder before you run the command.
Every command runs in the Terminal app (Applications › Utilities). The connector goes into ~/syniray-connector; its token, approvals and log stay in ~/.syniray.
Check Node.js
Run the command below. It must print v18 or a later version. If Terminal answers that the command is not found, or the version is older, install Node.js from https://nodejs.org and open a new Terminal window.
Terminalnode --versionDownload the connector and check it
Download the ZIP with the button below — your browser saves it in Downloads. Then run the command and compare the long code it prints with the SHA-256 shown beside the button: they must be identical. If they are not, delete the file and do not use it.
If you find a
syniray-connectorfolder in Downloads instead of the ZIP, your browser unpacked it by itself (Safari can do this). Download it again with that option turned off, so that you check the ZIP itself.Terminalshasum -a 256 ~/Downloads/syniray-connector-0.16.1.zipUnpack it in your home folder
The first command creates
~/syniray-connector; the second lists what is in it: six.mjsfiles and abrowserfolder. Keep them together in this folder: the connector checks that its files belong to the same version.Terminalunzip ~/Downloads/syniray-connector-0.16.1.zip -d ~ ls ~/syniray-connectorRun the self-tests
Two offline checks that need no pairing and no internet: they build a temporary folder, try to break out of it in the ways the connector must refuse, and delete it. The last line of each counts the checks that passed (
ok) and those that failed (failures; in the second one,falhas): the failures must be 0. A line markedskipnames a check that cannot run here and says why — from a ZIP, the four that compare with Syniray's server code: they are not failures.Syniray ran both on this ZIP, on macOS, before publishing it, with no failure. They test how the connector behaves; what proves the file is the one published here is the SHA-256.
Terminalnode ~/syniray-connector/selftest.mjs node ~/syniray-connector/security-selftest.mjsInstall the Syniray Browser (optional)
Only if you want the agent to open and read web pages on this computer. The first command installs one pinned package with npm and downloads a separate Chromium of about 150 MB into
~/.syniray/browser-runtime— an empty browser, never your own, with none of your logins. The second shows what is installed: it should saymodule ready.If you do not need it, skip this step: nothing is downloaded unless you run it, and you can come back to it later.
Terminalnode ~/syniray-connector/syniray-connector.mjs browser install node ~/syniray-connector/syniray-connector.mjs browser statusPair this computer
In Syniray Code, open Settings › Code › Computers — the button at the end of this page takes you there — and choose Pair a new computer. Give the computer a name and press Connect computer: Syniray shows a pairing code, valid once and for 10 minutes, and the full command with it.
Run that command here. The
XXXX-XXXXbelow is only an example. The connector answerspaired.and keeps its token in~/.syniray/connector.json, readable only by your user; the token is never printed.Terminalnode ~/syniray-connector/syniray-connector.mjs pair XXXX-XXXXChoose its folders and permissions
Once the connector is paired, the same window moves on by itself to Authorised folder and What it may do (later, the Folder and permissions button in the list of your computers opens them again). Write the full path of each folder the agent may use, one per line, up to 8 — a project folder such as
/Users/your-name/Projects/app. Syniray refuses the whole disk, system folders, your home folder itself and folders that hold keys or browser data.Tick only the permissions the agent needs — they are explained below this guide — and press Save. Nothing is in force yet: this computer has to approve it.
Start the connector
Leave this command running in its own Terminal window: while it runs, the computer is online in Syniray and can receive work. It prints the computer's name, the folders and the permissions in force.
The first time, it also prints what you chose in Syniray as a request for more access, with a six-character code. Until you approve it, that access stays refused. Run one
runper computer: if a second one starts, the first one stops.Terminalnode ~/syniray-connector/syniray-connector.mjs runApprove the access on this computer
Open a second Terminal window, leave
runrunning, and run one of the two commands below — the Copy button copies both, so keep only the one you want.approvewith the coderunprinted (ABC123is only an example) grants the folders and permissions listed in the request.denydiscards the request, but while Syniray still proposes that access,runasks again within about a minute with a new code: to end it, take that folder or permission off in Syniray. If you did not ask for that access in Syniray, do not approve it, and remove the computer in Settings › Code › Computers.The running connector applies an approval within about half a minute and prints
authorisation changed on this computer. A request expires after 15 minutes, and each new folder or permission you add in Syniray brings a new request within about a minute. Removing a folder or a permission needs no approval: it applies on its own within about a minute.Terminalnode ~/syniray-connector/syniray-connector.mjs approve ABC123 node ~/syniray-connector/syniray-connector.mjs denyCheck the connection
statusshows what was proposed in Syniray, what this computer approved and what is in force — the only part that runs — plus the Syniray Browser and any pending request.doctortests each step — reaching api.syniray.ai, signing in with the token, the long poll and the local model runtimes — and shows how long the network steps took. Neither prints your token.While
runis running, Syniray shows the computer as online.Terminalnode ~/syniray-connector/syniray-connector.mjs status node ~/syniray-connector/syniray-connector.mjs doctorUse it in Syniray Code
In Syniray Code, choose My computer as the execution environment, pick this computer and a model — one of Syniray's, your own API key or, if you allowed it, a local model — and describe the task. The session works in the folders in force; files cannot be attached here, so put a file in an authorised folder and mention it.
With Ask before changes, every command, file change and deletion waits for your answer in the conversation. A Trusted workspace runs them without asking, except what is always asked — for example a command or a deletion after the agent has read a web page or searched the web.
Stop, disconnect or uninstall
To stop the connector, press Control+C in the window where
runis running: it also stops the commands it had started, and the computer goes offline. Startrunagain whenever you like.To end its access, remove the computer in Settings › Code › Computers: the token stops working at once, any running session stops and a running connector stops by itself. Removing it deletes nothing on the computer. To take the connector off the computer too, run the two commands below:
logoutdeletes the token, and the second line deletes the connector's folder and~/.syniray, with the log and the Syniray Browser. Your project folders are not touched.Terminalnode ~/syniray-connector/syniray-connector.mjs logout rm -rf ~/syniray-connector ~/.syniray
Syniray tested connector 0.14.4 on Windows 11 Pro 26H2 (build 26300, ARM64), in a virtual machine and against a test server rather than the real service, in two ways: directly in PowerShell (Node.js 24 for Windows, Git for Windows 2.56) and in WSL 1 with Ubuntu 24.04 (Node.js 18 and Git 2.43 from Ubuntu). It checked the self-tests, pairing, approving, status and doctor, the file tools, Git inspection, stopping a turn, reconnecting after the server dropped, logout and uninstalling. Not tested: WSL 2 — the test computer could not run its virtual machine — an x64 PC, and the real service. Which route to take: the agent's commands need WSL, because they run through /bin/sh; the Syniray Browser works directly in PowerShell and not in WSL 1. Each block says where its commands go: PowerShell or the Ubuntu (WSL) window. If a step does not work for you, write to [email protected]. The toolchain report added in 0.15.0 was tested on macOS only; on Windows it reports the operating system and nothing else.
Why WSL
The connector runs the agent's commands with
/bin/sh, a shell macOS and Linux have and Windows does not. Inside WSL it exists, so the steps below install the connector in Ubuntu, where the agent can read and change files, inspect Git and run commands. Directly in PowerShell everything except commands works, the Syniray Browser included: see Without WSL further down. A session works on one computer, so on Windows commands and the browser are not available in the same session.Syniray ran these steps on Windows 11 with WSL 1, not WSL 2: wsl --install sets up WSL 2 on a computer that can run it, and that combination was not tested. In WSL 1 the Syniray Browser cannot run — Chromium's sandbox needs Linux features WSL 1 does not have — and browser status says so.
Install WSL with Ubuntu
Open PowerShell as administrator (in the Start menu, right-click PowerShell and choose Run as administrator), run the command below and restart Windows when it asks. It installs WSL with Ubuntu, its default distribution. Then open Ubuntu from the Start menu and create your Linux user name and password. Microsoft's guide: https://learn.microsoft.com/windows/wsl/install
If you already use WSL with Ubuntu, skip this step.
PowerShellwsl --installInstall Node.js, npm and unzip
In the Ubuntu window, run the three commands below;
sudoasks for the Linux password you created. The last one must print v18 or later. The version Ubuntu installs depends on its release: if it is older than 18, install a current Node.js for Linux from https://nodejs.org instead.Ubuntu (WSL)sudo apt update sudo apt install -y nodejs npm unzip node --versionDownload the connector and check it
Download the ZIP with the button below; Windows saves it in your Downloads folder. In Ubuntu, the Windows drive C: is under
/mnt/c: in the first command, replaceYOUR-NAMEwith the name of your Windows user folder (the one in C:\Users; if it has a space, put the whole path between quotes). The command copies the ZIP into your Ubuntu home folder;-fis there because a file copied from/mnt/carrives read-only, so copying the same ZIP again would otherwise be refused.The second command prints the file's SHA-256: it must be identical to the one shown beside the button. If it differs, delete the file and do not use it.
Ubuntu (WSL)cp -f /mnt/c/Users/YOUR-NAME/Downloads/syniray-connector-0.16.1.zip ~/ sha256sum ~/syniray-connector-0.16.1.zipUnpack it and run the self-test
The first command creates
~/syniray-connectorin your Ubuntu home folder. The other two run the connector's offline self-tests: they build a temporary folder, try to break out of it in the ways the connector must refuse, and delete it. The last line of each counts the checks that passed and those that failed — the failures must be 0. A line markedskipnames a check that cannot run here and says why — from a ZIP, the four that compare with Syniray's server code, and in WSL one that needs a file system that ignores capital letters: they are not failures.Syniray ran both on this ZIP in WSL 1 with Ubuntu 24.04, with no failure.
Ubuntu (WSL)unzip ~/syniray-connector-0.16.1.zip -d ~ node ~/syniray-connector/selftest.mjs node ~/syniray-connector/security-selftest.mjsPair this computer
In Syniray Code, open Settings › Code › Computers — the button at the end of this page takes you there — and choose Pair a new computer. Give the computer a name and press Connect computer: Syniray shows a pairing code, valid once and for 10 minutes, and the full command with it.
Run that command in the Ubuntu window. The
XXXX-XXXXbelow is only an example. The token is kept in~/.syniray/connector.json, inside Ubuntu, and is never printed.Ubuntu (WSL)node ~/syniray-connector/syniray-connector.mjs pair XXXX-XXXXChoose its folders and permissions
Once the connector is paired, the same window moves on to Authorised folder and What it may do (later, Folder and permissions in the list of your computers opens them again). The connector sees folders as Ubuntu does: a folder in your Ubuntu home, such as
/home/your-name/project, or a Windows folder through/mnt/c, such as/mnt/c/Users/your-name/Projects/app. Choose only project folders: through/mnt/c, Syniray does not refuse your whole Windows user folder, a Windows system folder or a folder where programs keep their data, so do not enter any of them.Tick only the permissions the agent needs and press Save. Leave Use the Syniray Browser off here: it cannot run in WSL 1, and Syniray has not tested it in WSL 2. To use the browser on Windows, install the connector directly in PowerShell (Without WSL). Nothing is in force until this computer approves it.
Start the connector
Leave this command running in its own Ubuntu window: while it runs, the computer is online in Syniray. Closing the window stops it. The first time, it prints your choice as a request for more access, with a six-character code, and keeps it refused until you approve it.
Ubuntu (WSL)node ~/syniray-connector/syniray-connector.mjs runApprove the access on this computer
Open a second Ubuntu window from the Start menu, leave
runrunning, and approve with the coderunprinted —ABC123is only an example. It grants the folders and permissions listed in the request, and the running connector applies it within about half a minute. Until you approve, that access stays refused. If you did not ask for it in Syniray, do not approve it, and remove the computer in Settings › Code › Computers.Ubuntu (WSL)node ~/syniray-connector/syniray-connector.mjs approve ABC123Check the connection
statusshows what was proposed in Syniray, what this computer approved and what is in force — the only part that runs — plus any pending request.doctortests each step — reaching api.syniray.ai, signing in with the token, the long poll and the local model runtimes — and shows how long the network steps took. Neither prints your token.While
runis running, Syniray shows the computer as online.Ubuntu (WSL)node ~/syniray-connector/syniray-connector.mjs status node ~/syniray-connector/syniray-connector.mjs doctorWithout WSL: directly in PowerShell
If you cannot use WSL, or you want the Syniray Browser on Windows, install Node.js for Windows from https://nodejs.org — it includes npm — and, for Git inspection, Git for Windows from https://git-scm.com. Then use PowerShell. The Copy button copies all seven lines below: run them one at a time.
The first prints the ZIP's SHA-256 in capital letters — compare it with the one beside the download button, ignoring case. The second unpacks the connector into
$HOME\syniray-connector; to update it later, add-Force, or it refuses to replace the files. The third is the offline self-test: the failures must be 0, and itsskiplines are checks Windows cannot run here — commands through/bin/shand, unless Developer Mode is on, symbolic links. The fourth installs the Syniray Browser — skip it if you do not need it: it downloads a separate Chromium of about 150 MB into$HOME\.syniray\browser-runtime, andbrowser statusmust then saymodule ready. The fifth pairs the computer, with your own code instead ofXXXX-XXXX; then choose its folders and permissions in Syniray, as above, and start it with the sixth. The seventh approves a request for more access, from a second PowerShell window, with the coderunshows instead ofABC123.Folders are Windows paths, such as
C:\Users\your-name\Projects\app. Choose only project folders, for the same reason as above.PowerShellGet-FileHash -Algorithm SHA256 $HOME\Downloads\syniray-connector-0.16.1.zip Expand-Archive $HOME\Downloads\syniray-connector-0.16.1.zip -DestinationPath $HOME node $HOME\syniray-connector\selftest.mjs node $HOME\syniray-connector\syniray-connector.mjs browser install node $HOME\syniray-connector\syniray-connector.mjs pair XXXX-XXXX node $HOME\syniray-connector\syniray-connector.mjs run node $HOME\syniray-connector\syniray-connector.mjs approve ABC123Directly on Windows, “Run commands” does not work: commands need /bin/sh, and the agent is told to use WSL for them. Everything else was tested in PowerShell on Windows 11, against a test server: the file tools, Git inspection with Git for Windows, approvals, stopping, reconnecting, uninstalling and the Syniray Browser — it opened, read, clicked in and captured a page with its sandbox on, refused a port that was not approved, and closed with its profile deleted when the session stopped.
Stop, disconnect or uninstall
To stop the connector, press Ctrl+C in the window where
runis running, or close that window; the computer goes offline.To end its access, remove the computer in Settings › Code › Computers: the token stops working at once and any running session stops. To take the connector off Ubuntu too, run the two commands below in the Ubuntu window:
logoutdeletes the token, and the second line deletes the connector's folder and its data in~/.syniray. If you installed it in PowerShell, these commands do not work there: use the next step instead. Your project folders are not touched.Ubuntu (WSL)node ~/syniray-connector/syniray-connector.mjs logout rm -rf ~/syniray-connector ~/.synirayUninstall it from PowerShell
If you installed the connector directly in PowerShell (Without WSL), stop it first with Ctrl+C in the window where
runis running. To end its access, remove the computer in Settings › Code › Computers, as in the previous step.Then run the two commands below in PowerShell:
logoutdeletes the token, and the second line deletes thesyniray-connectorand.synirayfolders in your Windows user folder, with the connector's log. Your project folders are not touched.PowerShellnode $HOME\syniray-connector\syniray-connector.mjs logout Remove-Item -Recurse -Force $HOME\syniray-connector, $HOME\.syniray
Permissions
What you can allow
Read files
List, read and search files in the authorised folders — and only there: every path is checked on the computer itself, symbolic links included.
Change files
Create and overwrite files in the authorised folders. Each change appears in the session with the lines added and removed when they can be counted, and with Ask before changes each one waits for your approval. A repository's own metadata — the .git folder — is never written; files such as .gitignore are.
Delete files
Delete one file at a time in the authorised folders — never a folder, and never a repository's own metadata in .git. With Ask before changes, each deletion waits for your approval.
Run commands
Run commands — builds, tests, scripts — starting in an authorised folder. It is the broadest permission: a command that runs can reach outside the folder, so grant it only for projects you trust.
Inspect Git
Runs Git commands from a fixed list meant for inspection — status, diff, log, show, blame, shortlog, describe, rev-parse, and branch and remote only to list — so the agent can see the state of a repository. Each command accepts only the options on its own list: anything that writes a file, reaches the network or starts a program (such as --output, --no-index, --ext-diff, status -v, creating a branch or remote show) is refused, and so is a repository whose own settings could make Git do that. commit, push, checkout and merge are not on the list. When the authorised folder is part of a larger repository, the tool sees that folder only.
Use local models
Lets the agent use models served on this computer by Ollama or a local OpenAI-compatible server. Syniray's models and your own API key do not need it: those calls go through Syniray, and your key never reaches the computer.
Use the Syniray Browser
Lets the agent open web pages in the Syniray Browser, once it is installed, and read, click and type in them — typing into a password or payment field always asks you first. It reaches public sites, and a port on this computer, such as your development server, only if you list it in Syniray and approve it here.
Web search
Not a permission on the computer: with connector 0.14.0 or later, Syniray can give the agent a web search that runs on its servers, charged in Syniray credits whatever the model. The agent is told to use the results as information, never as instructions, and after a search that found results, commands and deletions ask you even in a Trusted workspace.
Security
How it connects, and its limits
It calls out; nothing listens
The connector opens no port the network can reach. It keeps an HTTPS request open to api.syniray.ai and receives work as the answer, so your firewall and router need no changes.
More access needs a yes on the computer
Every permission starts off. You choose folders and permissions in Syniray, but anything that widens access only takes effect after you approve it on the computer — the browser alone cannot grant it. Taking access away applies on its own.
One token, kept on your computer
Pairing stores a token in the .syniray folder of your home folder, readable only by your user on macOS and Linux; on Windows, the connector restricts the file to your Windows account. It is never printed, logged or passed to the commands the agent runs; Syniray keeps only a hash of it and its first few characters.
Not a sandbox
The connector runs with your user's rights. It refuses some commands outright — sudo, a plain git push, a few common ways of uploading files — but that list is a safety floor, not isolation: a command that runs can reach outside the folder, and what the agent reads can be sent to the model you chose.
Troubleshooting
When something does not work
The computer shows as offline
It is online only while run is running and has asked Syniray for work in the last 45 seconds. Check that run is open in a terminal and that the computer is not asleep, then run doctor.
Syniray asks for an update
Stop run (Ctrl+C), download the current ZIP from this page, check its SHA-256 and unpack it over the old folder — when unzip asks, answer A to replace every file; in PowerShell, add -Force to Expand-Archive — then start run again. If you use the Syniray Browser, run browser status: if it does not say module ready, run browser install again. Your pairing and approvals stay: they live in .syniray, not in the program's folder.
“The connector restarted”
If the connector is restarted while a session is working, that turn ends and nothing more of it runs. Keep run going and send your message again to continue.
Syniray cannot be reached
doctor shows which step fails. If api.syniray.ai cannot be reached, pair, status and run stop with a Node.js error such as “fetch failed”: check your internet connection and any VPN, proxy or firewall. Once run is connected, it retries on its own.
Access still refused
status shows the pending request and its code: approve it with that code. If you did not ask for it, take that folder or permission off in Syniray — deny only discards this request, and run asks again within about a minute while Syniray still proposes it. Pairing again adds the computer to Syniray as a new one and clears its approvals here, so every folder and permission has to be approved again.
Code refused or expired
A pairing code works once and for 10 minutes: if pair says invalid_pairing_code, create a new one in Syniray; if it says rate_limited, wait before trying again. An access request lasts 15 minutes; once it expires, run prints a new one, with a new code, within about a minute.
Questions
Frequently asked questions
Do I need the connector to use Syniray Code?
No. In Syniray Cloud the agent works on Syniray and nothing is installed. The connector is only for running the agent in folders on your own computer.
Does it work on Windows?
Yes, in two ways, both tested by Syniray on Windows 11 (ARM64, in a virtual machine) against a test server. In WSL 1 with Ubuntu the connector runs as a Linux program: files, Git inspection and the agent's commands work; the Syniray Browser does not run there. Directly in PowerShell, files, Git inspection and the Syniray Browser work; running commands does not. WSL 2 was not tested.
Does the connector open a port on my computer?
No. It calls out to api.syniray.ai over HTTPS and receives work as the answers; nothing on the network can connect to it. It works only in the folders and with the permissions you approved on the computer, and it stops when you close it.
Which models can the agent use on my computer?
Syniray's models of your plan, a model from your own API key, or a local model served by Ollama or a local OpenAI-compatible server — that one needs the “Use local models” permission. Calls to Syniray's models and to your key go through Syniray; your key never reaches the computer.
How many computers can I connect?
Up to 5 per account, counting those still waiting to be paired. To add another, remove one in Settings › Code › Computers.
How do I remove the connector completely?
Remove the computer in Settings › Code › Computers: its token stops working at once and any running session stops. Then, on the computer, run logout and delete the syniray-connector and .syniray folders, as the guide's final steps show. Nothing in your project folders is deleted.
Pair your computer
Open Computers in Syniray Code, create a pairing code and follow the guide above. The connector is part of Syniray Code, included in Pro and Max.
Open Computers in Syniray Code