Remote source reports

Remote reports use folders that the computer owner selects in Connections. Pairing identifies the computer. A separate local grant permits remote reports. Discovery, native sign-in and an existing MCP connection do not create this grant.

The native app supplies its compiled public account-service address to the managed service. No config edit is needed for the release address. A saved paired device or explicit instance setting retains precedence. Invalid explicit settings are refused. This startup handoff carries no account token and grants no access.

Enable access

1. Open Connections on the computer that holds the files.
2. Check the account-service address. Sign in there and obtain a pairing code.
3. Enter the code in Brainlyy. Check the returned account identity.
4. Select the folders that remote reports may read.
5. Review the selected folders and permitted actions. Enable remote reports.

The initial grant lasts 24 hours. It permits report creation, report reading and task cancellation. It does not permit source-file changes, repair application, revision restore, shell commands or model calls. A new folder is not added to an existing grant. Replacing a grant creates a new grant ID and revokes the old one.

Open the paired computer from the account page to use Work in a browser. The browser shows the approved scope. A report uses the same bounded keyword search as local Work: at most 2,000 eligible notes, 256 KiB per file, six excerpts and a cooperative 30-second scan budget. The report records source versions. It does not independently establish that the source statements are true.

Connection loss and recovery

The worker saves an accepted task before it acknowledges the request. A stable request key identifies the submission. Repeating that key with the same query returns the same task. Reusing it with a different query is refused.

The browser can close after acceptance. The worker can continue under the local grant. Graceful app shutdown returns an interrupted, still-authorized attempt to the queue for the next start. If the process stops abruptly, a later worker can claim the task after its 120-second lease expires. Each attempt has a different lease. Shutdown never requeues a cancelled task or restores revoked or expired authority. An old attempt cannot replace a newer attempt or an accepted result.

If the submission response is lost, acceptance is unknown. The browser checks the same request key. It must not create a new key automatically. If the computer was offline before submission, no task is queued in the browser or account service. Keep the draft and retry after reconnecting.

A cancellation response can also be lost. Treat cancellation as unconfirmed until a task response confirms it. A finished task cannot be cancelled.

Remove access

Choose Revoke in local Connections. The grant check and report commit share one worker database transaction. Revocation prevents new work and result delivery. Removing an approved folder from the computer's configuration also denies its grant. Cached report content is not a replacement for current permission.

Signing out of the browser removes browser access. It does not cancel tasks already accepted under the owner's local grant. Revoke the grant or cancel a task to stop that work. Account-session revocation is checked before forwarding a browser command and again before delivering its response.

Revoking the paired device at the account service blocks its transport and browser access. An offline worker cannot immediately observe that remote change. Its already accepted local tasks can continue until the local grant expires or is revoked. This is separate from browser-session and upstream-provider logout.

Storage and authority

The worker uses remote-work.sqlite in its instance directory. It contains its workspace identity, local grants, durable tasks, source-version observations and reports. Local Work continues to use work.sqlite. The queues use different tables. Older local workers cannot claim remote tasks with their broader scope.

A grant binds the account-service origin, Auth0 issuer and subject, a persistent worker UUID, the worker workspace UUID, selected source handles and their local folder bindings, allowed actions, version and expiry. Numeric machine IDs in a URL are routing identifiers. They are not proof of authority.

The account service uses the existing live web session and account-to-machine mapping. Native metadata tokens and MCP gateway tokens cannot call this remote Work API. The courier carries typed commands. It does not forward caller headers, local read tokens, arbitrary URLs or arbitrary HTTP methods.

Commands and responses are held in memory while being delivered. The account service does not persist report bodies or a durable task queue. Every delivery has a new random ID, separate from the durable request key. A delayed reply from a previous relay process cannot satisfy a new request after restart.

Open full-size diagram ↗

The sequence shows two distinct decisions. The owner approves folders locally. The account service then authenticates each browser request. The worker checks the local grant before accepting, reading or publishing work. The account service checks the live session again before returning a response.

Versioned interfaces

The local access routes inherit the authenticated local UI boundary. They refuse relayed requests and require the local browser origin for writes.

The browser remote prefix is /m/{machine_id}/api/v1/remote-work. Its scope is resolved through the authenticated paired computer. The status response returns the grant ID and workspace ID. All other requests must supply that exact scope.

GET requests carry grant_id and workspace_id in the query. POST requests carry them in the JSON body. Duplicate or unknown fields are refused. Creation returns HTTP 202 only after worker persistence. Unknown task/result IDs return 404 without exposing another grant's records.

Current limits

A complete command frame is limited to 16 KiB of UTF-8 JSON. A result is limited to 512 KiB. JSON is limited to 64 nested levels. Duplicate fields, nonfinite numbers and invalid Unicode are refused. The courier permits two active HTTP calls and does not queue more. An expired call keeps its slot until its actual network operation exits. Profile, pairing and reply calls have a 10-second deadline. A poll has a 35-second deadline. The account service permits one poll per worker, eight pending commands per worker and 32 pending commands in total. These bounds are not a measured scale claim.

The HTTP client uses certificate and hostname verification. It does not follow redirects or use an environment proxy. Cleartext HTTP is allowed only for a numeric loopback development address. Response headers are limited to 32 KiB; consumed response bytes, including chunk framing and trailers, are limited to 640 KiB. A platform resolver can outlive caller cancellation, but a late connection cannot send credentials and cannot free its admission slot early.

This feature covers source reports for the paired account owner. Team roles, remote graph exploration, remote repair approval and general remote execution remain separate release requirements. There is no cloud-model fallback.

The worker permits at most 20 active remote tasks. Status returns the latest 25 tasks and 25 reports. Status query previews contain at most 240 Unicode characters, including a visible ellipsis when shortened; query_truncated identifies each shortened preview. Task lookup, task detail, report detail and export retain the complete query. This bounds the summary response without dropping recent records. Earlier reports remain addressable while their grant is valid. Source checks cannot lock the filesystem or interrupt every blocked operating-system read. A source change after a check can make a result stale. Opening a report checks its sources again without changing its saved check time. Permission checks occur before worker response generation and account-service delivery. Revocation cannot recall bytes already sent to a browser.

Exported records are not signed. Downloaded copies cannot be recalled by later revocation. Database storage relies on the operating-system user boundary and needs a tested backup policy. The feature still requires live hosted, native, independent security and scale qualification before general release.

See maintained work, authentication and release status.