Skip to content

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 Code

Overview

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.

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

    Terminal
    node --version
  2. Download 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-connector folder 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.

    Download
    Version
    0.16.1 · syniray-connector-0.16.1.zip · 284 KB
    SHA-256
    907d0208680c1715028a6f2235af84ce38f53c0a0b18d9474a7ac3d54d7b8a19
    Terminal
    shasum -a 256 ~/Downloads/syniray-connector-0.16.1.zip
  3. Unpack it in your home folder

    The first command creates ~/syniray-connector; the second lists what is in it: six .mjs files and a browser folder. Keep them together in this folder: the connector checks that its files belong to the same version.

    Terminal
    unzip ~/Downloads/syniray-connector-0.16.1.zip -d ~
    ls ~/syniray-connector
  4. Run 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 marked skip names 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.

    Terminal
    node ~/syniray-connector/selftest.mjs
    node ~/syniray-connector/security-selftest.mjs
  5. Install 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 say module 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.

    Terminal
    node ~/syniray-connector/syniray-connector.mjs browser install
    node ~/syniray-connector/syniray-connector.mjs browser status
  6. Pair 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-XXXX below is only an example. The connector answers paired. and keeps its token in ~/.syniray/connector.json, readable only by your user; the token is never printed.

    Terminal
    node ~/syniray-connector/syniray-connector.mjs pair XXXX-XXXX
  7. Choose 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.

  8. 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 run per computer: if a second one starts, the first one stops.

    Terminal
    node ~/syniray-connector/syniray-connector.mjs run
  9. Approve the access on this computer

    Open a second Terminal window, leave run running, and run one of the two commands below — the Copy button copies both, so keep only the one you want. approve with the code run printed (ABC123 is only an example) grants the folders and permissions listed in the request. deny discards the request, but while Syniray still proposes that access, run asks 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.

    Terminal
    node ~/syniray-connector/syniray-connector.mjs approve ABC123
    node ~/syniray-connector/syniray-connector.mjs deny
  10. Check the connection

    status shows 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. doctor tests 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 run is running, Syniray shows the computer as online.

    Terminal
    node ~/syniray-connector/syniray-connector.mjs status
    node ~/syniray-connector/syniray-connector.mjs doctor
  11. Use 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.

  12. Stop, disconnect or uninstall

    To stop the connector, press Control+C in the window where run is running: it also stops the commands it had started, and the computer goes offline. Start run again 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: logout deletes 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.

    Terminal
    node ~/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.

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

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

    PowerShell
    wsl --install
  3. Install Node.js, npm and unzip

    In the Ubuntu window, run the three commands below; sudo asks 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 --version
  4. Download 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, replace YOUR-NAME with 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; -f is there because a file copied from /mnt/c arrives 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.

    Download
    Version
    0.16.1 · syniray-connector-0.16.1.zip · 284 KB
    SHA-256
    907d0208680c1715028a6f2235af84ce38f53c0a0b18d9474a7ac3d54d7b8a19
    Ubuntu (WSL)
    cp -f /mnt/c/Users/YOUR-NAME/Downloads/syniray-connector-0.16.1.zip ~/
    sha256sum ~/syniray-connector-0.16.1.zip
  5. Unpack it and run the self-test

    The first command creates ~/syniray-connector in 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 marked skip names 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.mjs
  6. Pair 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-XXXX below 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-XXXX
  7. Choose 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.

  8. 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 run
  9. Approve the access on this computer

    Open a second Ubuntu window from the Start menu, leave run running, and approve with the code run printed — ABC123 is 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 ABC123
  10. Check the connection

    status shows what was proposed in Syniray, what this computer approved and what is in force — the only part that runs — plus any pending request. doctor tests 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 run is running, Syniray shows the computer as online.

    Ubuntu (WSL)
    node ~/syniray-connector/syniray-connector.mjs status
    node ~/syniray-connector/syniray-connector.mjs doctor
  11. Without 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 its skip lines are checks Windows cannot run here — commands through /bin/sh and, 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, and browser status must then say module ready. The fifth pairs the computer, with your own code instead of XXXX-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 code run shows instead of ABC123.

    Folders are Windows paths, such as C:\Users\your-name\Projects\app. Choose only project folders, for the same reason as above.

    PowerShell
    Get-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 ABC123

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

  12. Stop, disconnect or uninstall

    To stop the connector, press Ctrl+C in the window where run is 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: logout deletes 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 ~/.syniray
  13. Uninstall it from PowerShell

    If you installed the connector directly in PowerShell (Without WSL), stop it first with Ctrl+C in the window where run is 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: logout deletes the token, and the second line deletes the syniray-connector and .syniray folders in your Windows user folder, with the connector's log. Your project folders are not touched.

    PowerShell
    node $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