Integrating into an application

Desktop app

The recommended option is a child process per window or a controlled group of workbooks. Keep stdin/stdout open, match one request to one response, and log operation and code, but not cell content.

A caveat to “one response per request”: while you’re waiting for the response to an operation that touches the network, the core can send a counter-question — a line with a kind field. It has no TLS of its own, so it hands off https requests and connections to Postgres or SQL Server to you: you reach the network, and you answer with a line carrying the same id. The core sits idle until it gets that answer. Parse incoming lines by their kind field, and don’t treat every line as a response to your own request — otherwise the first Power Query request over https will end with both sides waiting on each other.

Server

Wrap the command-line program in a service of your own. On a load request, create an isolated working folder, start the process with a memory and time limit, expose your own session token, and never show the client subsetId — it’s the internal name of an open workbook session, living only inside the core process.

Browser

The browser can’t run compute_contract_cli directly: the core is an ordinary executable, and you can’t call it from a page. There’s one working scheme today: the shell runs in the browser, the core process runs on your side, and a persistent connection sits between them. That’s how the live example is built — the workbook is opened by a separate process, and the page shows the sheet and passes along actions. This guide doesn’t promise a package you can install and call straight from the page: what that will include is described in the embedding kit.

Phone and tablet

On iOS and Android, use the server option or an adapter built for the platform itself. Don’t bundle the desktop processor into a mobile app and don’t run it as an arbitrary process: the phone’s sandboxing rules don’t allow it.

Recommended shape for your API

POST /workbooks → your own session token
POST /workbooks/{id}/commands → a typed response
GET /workbooks/{id}/cells → a section of the sheet, not the whole sheet
POST /workbooks/{id}/save → a file or a download link
DELETE /workbooks/{id} → close the session and clean up

Security

Allow only pre-defined folders and file types. Don’t pass a destinationUri that came from an external client straight into the command-line program: the destination address must be assembled on your side.

More on this topic

• The full list of operations with their fields — the Compute Contract reference.
• What arrives in the response and how to read a refusal — How the API session works.
• Before the pilot — the readiness checklist.