Documentation

The connector's security

What the CoRoid connector does on your machine and what it does not, the requests it makes, what it is built to withstand, and how to check that a release is what its public source builds.

The CoRoid connector is the program that lets the coding agents on your own machine do work for CoRoid (see Coding agents on your own machine). It is open source under the Apache-2.0 licence, and its complete source is at github.com/COROID-AI/coroid-connector. This page is for whoever decides whether it may run on your organisation's machines.

How data flows

Your machine

CoRoid connector

Open source. Starts the agent for a turn in a new, empty directory and stops it after.

Your coding agent

The agent you use, signed in as you, with its own tools switched off.

  1. 1Asks for work. Each request is held up to 25 seconds; the connector reports what the agent says every 3 seconds.
  2. 2Calls the role's tools. With a token for this turn only, which stops working when the turn ends.
  3. 3Asks its model. As it would without CoRoid. CoRoid never sees that sign-in.

CoRoid

Orchestrator

Hands out a role's work to the machine of the person who started the task (1).

The role's tools

Run in the task's sandbox, where your code stays (2).

The agent's provider

Answers the agent's model requests under your own sign-in, on your plan (3).

Nothing reaches into the machine: the connector opens no port, sends none of its files and runs no command of its own.

On the machine stay your sign-in to the agent and whatever the agent itself keeps of a turn.

Every connection starts on the machine and goes out over HTTPS. The repository stays in the task's sandbox in CoRoid; the agent works on it only through the role's tools.
  • Outbound only. The connector opens no port, except for a moment on 127.0.0.1 while you sign in. It asks CoRoid for work over HTTPS. Each request is held for up to 25 seconds and then asked again, which is also how CoRoid knows the machine is connected.
  • Your code stays in CoRoid. The repository is never copied to the machine. The role's tools (read a file, run the tests, change the code) run in the task's sandbox in CoRoid. What reaches the machine is the role's instructions and what those tools return, such as the contents of a file the agent reads or the output of a test run.
  • The agent's model requests go to its provider, under your own sign-in and on your plan, as they would without CoRoid. What the agent sends its model includes what the role's tools returned, so your agreement with that provider covers it.
  • Work goes only to the person who started it. A role runs on a machine only when its assignment names an agent, the person who started the task has a machine connected in that organisation, and the organisation's policy allows that agent. Work nobody started, such as an automation, runs on its model.

What the connector does

  • Signs in with OAuth 2.1 and PKCE in your browser, for one scope (connector.turns). The access token lasts 15 minutes; the refresh token 30 days, and it is replaced at every use. Disconnect in Your machines revokes both.
  • Keeps those tokens in the macOS keychain or a Linux desktop's Secret Service, handing them to those tools on standard input, never on a command line. Only where there is neither are they kept in a file only you can read. coroid-connector status says where yours are.
  • Tells CoRoid, with its first request, the machine's name, its operating system, its own version, and each agent's version, state and the models it offers.
  • Runs a turn: starts the agent in a new, empty directory with the agent's own tools switched off, gives it one set of tools (the role's tools for that turn), relays what it says, refuses any permission request that is not a call to those tools, and stops it. Then it removes the directory.

What it does not do

  • Read or send your files, or run a command of its own. The only file it reads that is not its own is Cursor's settings, for the two values that decide whether it may use Cursor (see Limits); nothing of it leaves the machine.
  • Let the agent use its shell, file editing, web search, or its own MCP servers and connectors. Each agent is started with that agent's own switch for this, on the agent versions it was tried on; an agent on another version is listed and not used.
  • Open a port others can reach, or take instructions from anyone but CoRoid over the connection it opened.
  • Download anything when it runs. coroid-connector add installs an agent's adapter once, from exactly the packages its release's lockfile names (each pinned by version and SHA-512), with install scripts off.

The requests it makes

ToWhenWhat for
CoRoid's API (https://api.coroid.ai)Signing in and outRegistering the connector, exchanging, renewing and revoking its tokens (/oauth/…)
CoRoid's APIWhile it runsAsking for work (/connector/v1/poll) and reporting a turn (/connector/v1/turns/…/events)
The npm registryOnly during coroid-connector addThe adapter packages the release's lockfile names

The agent, not the connector, calls the role's tools (an address under /connector/v1/turns/, with that turn's token) and its own provider.

What it is built to withstand

IfThen
Someone else asks to connect a machine as youThe approval happens in your browser, signed in as you, and the sign-in completes only on the machine that started it (at 127.0.0.1, with PKCE). Approve only a connector you started a moment ago.
A connector's tokens are stolenThey reach one scope: asking for this person's work and reporting on it. The access token expires within 15 minutes, and Disconnect revokes both.
A turn's token is reusedIt works for that turn only, and stops working when the turn ends.
A turn asks the agent for something elseThe agent's own tools are off and the connector refuses other permission requests. The role's tools are the same as a cloud model's, with the same QA, review, gates and step limits.
A release is not what its source saysEach release is built by GitHub Actions from a tagged commit of the public repository, attested, and published to npm with provenance. The Homebrew formula takes a new version only after checking its attestation. You can check one yourself (below).

Limits

  • The agent runs as you, with your user's rights on the machine. Keeping it to CoRoid's tools rests on each agent's own switch, which is why the connector uses an agent only on the versions it was tried on.
  • What an agent keeps of a turn in its own storage depends on the agent (see What stays on your machine). Your organisation's policy decides which agents its people may use (see What your organisation allows).
  • Cursor asks before its web fetch, web search and browser only in its default settings. The connector reads two of them on the machine (the approval mode, and whether web searches are accepted automatically) and does not use Cursor when they let it run those tools without asking.
  • The connector has not been tried on Windows.

Check a release

Each release on GitHub carries the published package, the connector file, a CycloneDX bill of materials and SHA256SUMS. Replace <version> with the release you check.

The npm package's registry signature and provenance:

mkdir check && cd check && npm init -y
npm install @coroid/connector@<version>
npm audit signatures

The attestation, which names the commit and the workflow that built the file:

gh release download v<version> --repo COROID-AI/coroid-connector
gh attestation verify coroid-connector-<version>.tgz --repo COROID-AI/coroid-connector \
  --signer-workflow COROID-AI/coroid-connector/.github/workflows/release.yml

The file, built yourself from the tagged source:

git clone https://github.com/COROID-AI/coroid-connector && cd coroid-connector
git checkout v<version> && npm ci && npm run build
shasum -a 256 dist/coroid-connector.mjs   # the same as its line in SHA256SUMS

To report a vulnerability, use the repository's security policy (GitHub's private vulnerability reporting).