EngineerOS Connector

Connect a local coding agent or Bug Hunter host to EngineerOS.

Requirements

• Node.js 22 or newer and npm on Windows, macOS or Linux.
• An EngineerOS pairing command and access to your chosen coding agent.
• Git when connecting a code repository.
• Protected credential storage: Windows Credential Manager/Data Protection, macOS Keychain, or Linux Secret Service. On Linux, install secret-tool (libsecret-tools) and run an unlocked keyring such as GNOME Keyring or KWallet.

Install

npm install --global @engineeros/connector@latest
engineeros-connector version

To run without a global install, replace engineeros-connector in the commands below with npx --yes @engineeros/connector@latest.

Connect a workspace

In EngineerOS, open Project steering → Connect workspace and copy the pairing command. Run it inside your project folder. For example, with Codex:

engineeros-connector agent codex-acp install
engineeros-connector pair PAIRING_CODE --url https://your-engineeros.example --workspace . --onboard --agent codex-acp

Replace the code and server URL with the values from EngineerOS. Sign in to the agent when prompted; for Codex, run codex login in another terminal. Keep the connector terminal open.

Run engineeros-connector agents to list supported agents. Use the chosen agent's ID in both commands above; for Claude, use claude-acp.

Restart an already paired workspace with:

engineeros-connector start --workspace .

Goal execution and recovery

Goal execution uses contract 4 and needs the matching EngineerOS backend. The server retains repair reservations across restarts and Resume, including planning, ticket and repository-quality repairs. Restoring a fresh worktree cannot reset those allowances; keep the original checkpoint and completed work.

Scope additions require explicit user approval of repository-relative Path: entries shown in the question and its affected artifacts. Excluded paths stay excluded. A generic attestation cannot authorize an unapproved file.

Runs created before server repair accounting retain their evidence and saved head. Use an explicitly reviewed follow-up Goal to continue their code changes; unknown historical allowances are never initialized as unused. Saved completed results can still be delivered with their original execution attempt.

Connect Bug Hunter without a repository

Choose Find bugs in a running app in EngineerOS, add your target and copy its host command:

engineeros-connector hunt-host PAIRING_CODE --url https://your-engineeros.example --project PROJECT_UUID --agent codex-acp

The command prepares the agent and automatically installs the connector's pinned Playwright runtime and matching managed Chromium when missing. Workspace pair and start, hunts and recorded sign-ins use the same browser setup path. Complete the requested agent sign-in and keep the terminal open. No separate Playwright setup command is needed.

On Linux, setup checks and installs missing system dependencies using available administrator access. A terminal can request your password; a background process never prompts and reports the exact administrator command if access is unavailable. Disabled tools stay disabled, and integrity or version mismatches require explicit repair. Verified packages are retained when browser preparation fails, so a retry continues from the installed package. Setup verifies a real isolated context, synthetic navigation, HTTP/WebSocket interception, state restoration, screenshot/trace capture and evidence storage. Configure test accounts, app builds and devices in Bug Hunter Setup as needed.

Public-only browsing blocks state-changing/unknown HTTP operations and WebSockets before initial navigation. Parsed, unambiguous GraphQL queries on the recognized /graphql endpoint may pass with JSON operation documents; mutations, subscriptions, batches, multipart and persisted/unknown documents do not. The same policy applies to explicit request steps and every browser redirect hop through Chromium response interception. Frames/popups that cannot establish this guard before network access are blocked with an unsupported-capability diagnostic. A connector-local proxy validates and pins actual socket destinations and redirects; metadata/reserved addresses remain denied. Private DNS targets need every approved private address in Allowed hosts; localhost names must resolve exclusively to loopback. Local-looking suffixes grant no private-network access. An address change requires a new authorized run. Health/version checks, launch readiness, reset hooks, schema introspection and discovery use the same guarded socket rules; public-only grants refuse launch/seed/reset effects. Cloud web browsers and Electron with protected HTTP(S) targets are blocked when this socket boundary cannot be enforced. Purely local Electron actions and native WebDriver retain their separate execution paths and are not qualified web transport coverage.

Web cases must declare Effects, Test data and Cleanup starts in Markdown. A write case identifies its own {unique} data and a final cleanup range. Cleanup runs after an assertion failure and preserves that original failure. Unfinished cleanup stops further automatic work until the owned data is resolved and an operator explicitly resumes. Existing cases without declarations remain retained and require explicit regeneration or repair before execution; schema imports never manufacture executable cases when the model produces none.

Unfinished cleanup from cases, probes or re-observation is retained as an incident beside the original result hash in the encrypted hunter/environment ledger. A restart reports it before target work and cannot start another execution. Resolve the named owned data, synchronize the incident, then resume the halted hunter in EngineerOS with a reason and start a fresh authorized run. Only an acknowledgment containing that exact incident identity clears the local barrier. The original result, failure, proof children and attempt budgets remain retained.

Recorded sign-ins bind project, environment, connector, account, role and exact application origins. Record the login once, then start testing; no signed-in marker is required. A marker configured under advanced account options adds an explicit identity check in a separate read-only context before each case. Without one, the runner restores the recording directly and reports sign-in redirects encountered during testing. Restoring state alone does not claim verified login health. The protected host keeps application cookies, localStorage, sessionStorage and IndexedDB, including renewed sessions; optional health checks never collect screenshots or discovery facts. Earlier unbound recordings require explicit re-recording.

The app's own browser requests can reach public APIs and login services on other origins, including Supabase, without configuring those services as test targets. This applies to recording, password sign-in and restored sessions. Explicit case navigation/API requests remain scoped; read-only rules, TLS/CORS and private-network protections remain enforced. Only the app's approved cookie/storage origins are kept; contacting a public identity provider does not capture its sign-in state.

Screenshots and live frames are off by default. Setup's Allow screenshots in new hunts grants permission for a new immutable assignment, including native captures; it does not change an existing run. Visible test data can appear in an authorized image. Without permission, runs retain permitted text observations and checks; insufficient flaky evidence remains quarantined. Known credential values are removed from text metadata, and credential-bearing discovery paths are excluded rather than rewritten into replay URLs. Browser readiness captures only its own synthetic local fixture.

Restart the host with:

engineeros-connector hunt-host --project PROJECT_UUID

Connector agent defaults

Workspace assignments and Bug Hunter agent turns use the connector's shipped execution policy: concise reports, bounded reads, reuse of supplied context/memory, targeted verification, and explicit capability gaps. Required coverage, evidence, permissions and response contracts still apply. The policy is attached on a new session; continuations reuse it instead of repeating it. It does not copy this repository's development instructions into another project or create instruction/skill files there.

These controls apply only to connector launches. They do not edit the coding agent's global settings or copy credentials. Unsupported adapters remain usable with the warning; their extension context cannot be guaranteed. Use a current Codex or Claude ACP adapter for enforced plugin exclusions. Configuration controls reduce avoidable context; actual token savings require comparison of recorded usage for equivalent runs.

Troubleshoot and update

engineeros-connector doctor --workspace .
npm install --global @engineeros/connector@latest

• Missing pairing: copy a new pairing command from EngineerOS.
• Agent sign-in failed: sign in to the selected agent, then restart the connector.
• fetch failed or a network error code: run doctor and check the DNS hostname from the connector's machine. ENOTFOUND/EAI_AGAIN indicate resolution failure; ECONNREFUSED means the destination refused the connection; connect timeouts require checking routing, firewall and the server/proxy listener. Certificate errors require repairing the certificate or trusted CA chain. Keep TLS verification enabled. A request that never received an HTTP acknowledgement does not establish an invalid pairing or API-key rejection; retain the pairing while investigating.
• Credential storage unavailable: unlock or configure the protected store listed above, then restart. Headless Linux hosts also need a running Secret Service.
• Result delivery interrupted: completed prompt answers and failures are saved locally and retried after reconnecting. If EngineerOS permanently rejects an outcome, the terminal names the retained evidence file and reason. Keep that file when investigating; a rejected outcome does not automatically rerun the agent.

Governed native delivery runtime

Pair the workspace first. Prepare a local JSON runtime configuration with kind: docker-readonly-tmpfs-v1, immutable digest-pinned image and proxy_image, connector_entry: /opt/engineeros/bin/engineeros-connector.mjs, and the installed adapter's agent_config (agent_protocol, optional agent_command, agent_args, agent_name). Keep provider credentials in individual local files. Each explicit credentials entry names an absolute regular-file source, a unique /run/credentials/<name> target and readonly: true; directories and symlinks are refused. Never put credential values or environment secrets in the JSON.

engineeros-connector delivery configure --profile /absolute/path/runtime.json --workspace .
engineeros-connector delivery status --workspace .

Restart the connector to advertise the configured isolation identity. Retain the real isolation, process, resource, recovery, provider-bound and scope measurements and obtain environment approval before executing a governed plan. Configuration and delivery probe alone do not qualify a runtime. Changed credentials, images or capability hashes require requalification. Native scope uses a complete measured CLI bundle and filesystem ownership; it does not implement per-tool filtering. Missing prerequisites refuse work before launch and retain existing evidence/accounting.

• Uploaded input refused: use public HTTPS storage or the hunt host's local inputs folder. Downloads reject private/metadata addresses and are limited to 25 MB and 60 seconds.
• Behind a corporate proxy: set HTTPS_PROXY (or HTTP_PROXY), and NO_PROXY for internal hosts, before starting the connector. The connector's own EngineerOS, npm and agent-registry traffic then uses that proxy; loopback addresses always bypass it. For a private certificate authority, also set NODE_EXTRA_CA_CERTS to its PEM file. Coding agents use their own proxy settings, and Bug Hunter target traffic keeps its separate guarded path.

License

Copyright (c) 2026 Techmirus Innovations.

The EngineerOS Connector Binary Use License permits personal and commercial use of the official executable distribution. The original source remains proprietary. Third-party dependencies retain their own licenses; bundled grammar notices are in grammars/NOTICE.md.

Retained job history

engineeros-connector history compact --workspace <folder> combines acknowledged terminal report files while retaining every encrypted evidence body, acknowledgement and execution identity. Pending or rejected reports, locally retained evidence and interrupted/uncertain work stay untouched. New terminal reports compact automatically. Stop older connector versions before this storage-layout cutover; they cannot read compacted archives. The command uses local protected storage without contacting EngineerOS. See the retention contract.