{"id":51099235,"url":"https://github.com/mweinbach/cowork-runtime","last_synced_at":"2026-06-24T09:30:49.710Z","repository":{"id":366441172,"uuid":"1276279753","full_name":"mweinbach/cowork-runtime","owner":"mweinbach","description":"Versioned cross-platform dependency runtime for Cowork, including Node.js, Python, document tooling, and managed headless LibreOffice.","archived":false,"fork":false,"pushed_at":"2026-06-21T20:07:31.000Z","size":342,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-21T22:05:03.614Z","etag":null,"topics":["bun","cowork","libreoffice","runtime","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mweinbach.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-21T19:18:25.000Z","updated_at":"2026-06-21T20:07:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mweinbach/cowork-runtime","commit_stats":null,"previous_names":["mweinbach/cowork-runtime"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/mweinbach/cowork-runtime","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mweinbach%2Fcowork-runtime","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mweinbach%2Fcowork-runtime/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mweinbach%2Fcowork-runtime/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mweinbach%2Fcowork-runtime/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mweinbach","download_url":"https://codeload.github.com/mweinbach/cowork-runtime/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mweinbach%2Fcowork-runtime/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34724746,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-24T02:00:07.484Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bun","cowork","libreoffice","runtime","typescript"],"created_at":"2026-06-24T09:30:48.939Z","updated_at":"2026-06-24T09:30:49.698Z","avatar_url":"https://github.com/mweinbach.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cowork Runtime\n\nCowork Runtime packages the platform-specific tools and libraries used by the Cowork harness into one versioned release artifact.\n\nThe application itself still runs on Bun. This runtime is the managed execution layer for artifact work: Node, Python, package dependencies, and native utilities. Skills and plugins are separate application downloads from the Cowork skills marketplace and are never bundled into this archive.\n\n## Maintainer guides\n\nThe [maintainer guide index](docs/README.md) covers:\n\n- [updating an existing platform runtime](docs/updating-a-runtime.md);\n- [adding macOS, Linux, or another platform](docs/adding-a-platform.md);\n- [deciding which components to build, generate, or copy](docs/component-lifecycle.md);\n- [the archive/install/environment contract](docs/runtime-contract.md);\n- [publishing and rolling back releases](docs/releasing-and-rollback.md);\n- [agent-coworker integration](docs/harness-integration.md);\n- [runtime troubleshooting](docs/troubleshooting.md).\n\n## Release contract\n\nEach release uses an ISO-date version and a stable asset name:\n\n| Host | Release asset | Notes |\n| --- | --- | --- |\n| Windows x64 | `cowork-runtime-win-x86.zip` | The `x86` asset label means the x86-64 compatibility payload. |\n| Windows ARM64 | `cowork-runtime-win-x86.zip` | Runs through Windows x64 emulation for now. |\n| macOS x64 | `cowork-runtime-macos-x86.zip` | Payload to be assembled later. |\n| macOS ARM64 | `cowork-runtime-macos-arm64.zip` | Native Apple Silicon payload. |\n| Linux x64 | `cowork-runtime-linux-x86.zip` | Payload to be assembled later. |\n| Linux ARM64 | `cowork-runtime-linux-arm64.zip` | Payload to be assembled later. |\n\nFor version `2026-06-22`, the expected release tag is `runtime-2026-06-22`. Every ZIP has a sibling `.sha256` asset. Every payload also contains an Ed25519-signed schema-2 integrity manifest covering the exact file set, sizes, hashes, components, and entrypoints.\n\nInstallation is checksum-verified, extracted into a temporary directory, validated, then atomically promoted to:\n\n```text\n~/.cowork/runtime/2026-06-22/\n```\n\n`~/.cowork/runtime/current.json` selects the active version. There is no mutable `current/` directory or platform-dependent symlink.\n\n## Component policy\n\nThe runtime is assembled from components rather than blindly cloning an upstream directory. [`runtime-components.json`](runtime-components.json) is the shared default, and a platform recipe may provide a narrower component plan.\n\nCurrent bootstrap:\n\n| Component | Current strategy | Intended direction |\n| --- | --- | --- |\n| Cowork manifest, checksums, installer | Generated/built here | Cowork-owned |\n| Node ESM resolver | Built here | Cowork-owned |\n| Relocatable launchers | Generated here | Cowork-owned |\n| Node executable and package tree | Copied from the pinned reference payload | Assemble from official Node, a lockfile, and a supplied private artifact package |\n| Python executable and packages | Copied from the pinned reference payload | Assemble from portable Python and a hashed requirements lock |\n| Git, Poppler, libheif, jxrlib | Copied from the pinned reference payload | Fetch or compile from pinned upstream releases per platform |\n| `@oai/artifact-tool` | Direct copy | Remains a supplied release input unless build inputs become available |\n| LibreOffice conversion engine | Official binary, checksum-pinned and normalized here | Keep full filter/render compatibility while exposing no interactive launcher |\n| Headless `soffice` policy launcher | Built here; Windows uses a tiny Rust shim | Cowork-owned |\n\nEvery installed `runtime.json` records the strategy, path, and provenance of each component. Replacing a copied component with a reproducible builder does not change archive names or the harness integration contract.\n\nExtracted public dependency recipes live under [`recipes/win-x86`](recipes/win-x86/README.md) and [`recipes/macos-arm64`](recipes/macos-arm64/README.md). They deliberately keep `@oai/artifact-tool` and `artifact_tool_v2` outside the public build recipe as supplied inputs.\n\nLarge payloads are intentionally ignored by Git. `payloads/` is local staging and `dist/` contains release assets.\n\n## Build the Windows payload\n\nInstall the small builder dependencies:\n\n```powershell\nbun install\n```\n\nPrepare the checksum-pinned LibreOffice component on the target operating system. Windows release builders also need a Rust toolchain for the small native `soffice.exe` forwarding shim:\n\n```powershell\nbun run prepare:libreoffice -- --asset win-x86 --force\n```\n\nProvide the release signing key through a private file. The public key under [`keys/`](keys/) is pinned by consumers; the private key must never enter the repository or build artifacts:\n\n```powershell\n$env:COWORK_RUNTIME_SIGNING_KEY_FILE = \"$env:RUNNER_TEMP\\cowork-runtime-release-1.pem\"\n```\n\nIn GitHub Actions, the private PEM is stored as the encrypted\n`COWORK_RUNTIME_SIGNING_PRIVATE_KEY` repository secret and the key ID as the\n`COWORK_RUNTIME_SIGNING_KEY_ID` repository variable. The **Runtime Release\nSigning Preflight** workflow securely materializes the file, proves it matches\nthe pinned public key, exports `COWORK_RUNTIME_SIGNING_KEY_FILE` for subsequent\nrelease steps, and removes it in an `always()` cleanup step.\n\nAssemble from the current OpenAI reference runtime:\n\n```powershell\nbun run stage -- `\n  --source \"$env:USERPROFILE\\.cache\\codex-runtimes\\codex-primary-runtime\" `\n  --asset win-x86 `\n  --version 2026-06-22 `\n  --force\n```\n\nThis copies only the components marked `copied`, builds the Cowork-owned support layer, generates launchers, preserves the original source manifest under `provenance/`, and writes the canonical Cowork `runtime.json`.\n\nNo source skill or plugin tree is copied. Marketplace skills consume this runtime through the environment contract below; the marketplace owns their instructions and helper scripts.\n\nBuild and verify the release:\n\n```powershell\nbun run build -- --runtime payloads/win-x86 --asset win-x86\nbun run verify -- --runtime payloads/win-x86 --deep --execute\n```\n\nThe build creates:\n\n```text\ndist/cowork-runtime-win-x86.zip\ndist/cowork-runtime-win-x86.zip.sha256\n```\n\n## Build the macOS ARM64 payload\n\nBuild on Apple Silicon using the native `darwin-arm64` reference runtime. The platform-specific plan excludes the reference runtime's duplicate LibreOfficeDev tree and packages the checksum-pinned official app instead:\n\n```bash\nbun install --frozen-lockfile\nbun run prepare:libreoffice -- --asset macos-arm64 --force\nbun run stage -- \\\n  --source \"$HOME/.cache/codex-runtimes/codex-primary-runtime\" \\\n  --asset macos-arm64 \\\n  --version 2026-06-22 \\\n  --component-plan recipes/macos-arm64/runtime-components.json \\\n  --force\nbun run verify -- --runtime payloads/macos-arm64 --deep --execute\nbun run build -- --runtime payloads/macos-arm64 --asset macos-arm64\n```\n\nThe executable verification imports the managed Node and Python stacks, checks pnpm, Git, Poppler and libheif, confirms native Mach-O architecture, completes a real LibreOffice conversion, and validates the app's Developer ID seal. Staging also rejects broken or escaping symlinks and safely normalizes relocatable sibling links from upstream payloads.\n\nThe build creates `dist/cowork-runtime-macos-arm64.zip` and its `.sha256` sidecar.\n\nProduction signing can remain isolated in GitHub. Sign the locally staged payload\nwith a disposable staging key, upload the ZIP, checksum, and staging public key to\na private draft release named `runtime-staging-macos-arm64-\u003cversion\u003e`, then dispatch\nthe **Publish macOS Runtime** workflow. It verifies the staging signature and exact\ntree, re-seals with the repository production key, runs native executable and clean\ninstall checks, publishes without clobbering existing assets, verifies the public\ndownload path, and deletes the private staging release.\n\n## Test the installer locally\n\nUse a temporary home first:\n\n```powershell\nbun src/cli.ts install `\n  --archive dist/cowork-runtime-win-x86.zip `\n  --checksum dist/cowork-runtime-win-x86.zip.sha256 `\n  --home \"$env:TEMP\\cowork-runtime-smoke\"\n\nbun src/cli.ts verify `\n  --runtime \"$env:TEMP\\cowork-runtime-smoke\\.cowork\\runtime\\2026-06-22\" `\n  --deep `\n  --execute\n```\n\nInstall to the real Cowork home by omitting `--home`.\n\nOn macOS, use an isolated home such as `$TMPDIR/cowork-runtime-smoke` and the `cowork-runtime-macos-arm64` asset names, then run the same deep executable verification against its installed `2026-06-22` directory.\n\n## Publish a GitHub release\n\nOnce this repository has a GitHub remote and the ZIP has passed the local install smoke test:\n\n```powershell\ngh release create runtime-2026-06-22 `\n  dist/cowork-runtime-win-x86.zip `\n  dist/cowork-runtime-win-x86.zip.sha256 `\n  --title \"Cowork Runtime 2026-06-22\" `\n  --notes \"Windows x86-64 runtime; Windows ARM64 uses x64 emulation.\"\n```\n\nDuring private release preparation only, before any consumer can have installed the asset, a corrected upload can be replaced with:\n\n```powershell\ngh release upload runtime-2026-06-22 `\n  dist/cowork-runtime-win-x86.zip `\n  dist/cowork-runtime-win-x86.zip.sha256 `\n  --clobber\n```\n\nAfter distribution, never clobber published bytes. Publish a new date version instead. See [Release and rollback](docs/releasing-and-rollback.md).\n\n## Download from the harness or CLI\n\nThe reusable library exports release selection, download, safe extraction, verification, activation, and environment construction. The standalone CLI uses the same code:\n\n```powershell\nbun src/cli.ts download `\n  --repo owner/cowork-runtime `\n  --version 2026-06-22\n```\n\nThe runtime environment exposes a single namespace:\n\n```text\nCOWORK_RUNTIME_DIR\nCOWORK_RUNTIME_VERSION\nCOWORK_RUNTIME_ASSET\nCOWORK_RUNTIME_BIN\nCOWORK_RUNTIME_NODE\nCOWORK_RUNTIME_PYTHON\nCOWORK_RUNTIME_GIT\nCOWORK_RUNTIME_NODE_MODULES\nCOWORK_RUNTIME_NODE_RESOLVER\nCOWORK_RUNTIME_POPPLER_BIN\nCOWORK_RUNTIME_SOFFICE\nCOWORK_RUNTIME_LIBREOFFICE_DIR\nCOWORK_RUNTIME_LIBREOFFICE_BINARY\n```\n\nIt also prepares `PATH`, exposes both the top-level and pnpm-hoisted package closure through `NODE_PATH`, and adds a Node `--import` resolver hook so marketplace skill builders in writable scratch directories can directly import managed packages such as `@oai/artifact-tool`.\n\n## Skills marketplace boundary\n\nThe runtime and skills have independent release lifecycles:\n\n- the app downloads this platform runtime into `~/.cowork/runtime/\u003cdate\u003e`;\n- the app downloads authoritative plugins and skills from the Cowork skills marketplace into the normal project or user plugin roots;\n- plugin discovery never scans the runtime directory;\n- updating the runtime cannot replace skill content, and updating a skill cannot replace runtime binaries.\n\nMarketplace helpers that need package locations use `COWORK_RUNTIME_NODE_MODULES`; they must not reach into a Codex cache or assume a mutable compatibility directory.\n\n## LibreOffice and `soffice`\n\nThe OAI reference payload does not carry LibreOffice, so Cowork adds it as a separate, checksum-pinned component input while still publishing one unified runtime ZIP. [`libreoffice-sources.json`](libreoffice-sources.json) pins the official platform archives and hashes.\n\nOnly Cowork's launcher under `dependencies/bin` is placed on `PATH`. The private LibreOffice program directory is never exposed. The launcher:\n\n- rejects UI, quick-start, view, and printer command-line modes;\n- always forces headless, invisible, no-logo, no-default, no-restore operation;\n- creates and removes an isolated profile for every invocation;\n- disables synchronous printer detection and profile printer loading;\n- disables document macro execution and system file dialogs;\n- forwards only conversion, text-output, version, and help operations.\n\nOn Windows, interactive module launchers such as `soffice.exe`, `swriter.exe`, and `scalc.exe` are removed from the packaged engine. `soffice.com` and `soffice.bin` remain private because they are required for the conversion engine. Rebuilding a custom LibreOffice fork is deliberately avoided: the official filter/render binaries are the compatibility boundary, while the Cowork launcher provides the no-UI/no-print boundary.\n\n## Safety properties\n\n- The archive SHA-256 is verified before extraction.\n- A schema-2 Ed25519 signature authenticates the exact extracted file tree; schema-1 runtimes are diagnostics-only.\n- Complete-tree verification runs before installation, entrypoints are re-hashed before use, and consumer mutation watchers invalidate cached component trust.\n- ZIP entries are bounded by count and unpacked size.\n- Absolute paths, traversal paths, duplicate paths, unsafe links, and special filesystem entries are rejected.\n- Installation uses a staging directory and atomic promotion.\n- The source payload is never modified.\n- Runtime binaries and release ZIPs are not committed to Git.\n\nRun `bun run check` for the typecheck and deterministic test suite.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmweinbach%2Fcowork-runtime","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmweinbach%2Fcowork-runtime","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmweinbach%2Fcowork-runtime/lists"}