{"id":48839412,"url":"https://github.com/omkhar/workcell","last_synced_at":"2026-05-30T16:00:42.295Z","repository":{"id":350354968,"uuid":"1188938390","full_name":"omkhar/workcell","owner":"omkhar","description":"Bounded local runtime and policy boundary for coding agents","archived":false,"fork":false,"pushed_at":"2026-05-30T00:06:07.000Z","size":4436,"stargazers_count":14,"open_issues_count":0,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-30T00:13:33.282Z","etag":null,"topics":["coding-agents","containers","developer-tools","macos","provenance","sandbox"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/omkhar.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":"SUPPORT.md","governance":"GOVERNANCE.md","roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":"MAINTAINERS.md","copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-22T19:32:02.000Z","updated_at":"2026-05-30T00:06:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/omkhar/workcell","commit_stats":null,"previous_names":["omkhar/workcell"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/omkhar/workcell","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omkhar%2Fworkcell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omkhar%2Fworkcell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omkhar%2Fworkcell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omkhar%2Fworkcell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/omkhar","download_url":"https://codeload.github.com/omkhar/workcell/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omkhar%2Fworkcell/sbom","scorecard":{"id":1245849,"data":{"date":"2026-04-10T02:24:20Z","repo":{"name":"github.com/omkhar/workcell","commit":"ed731f6d69a354b23aecb876abc7ddeb5178ca51"},"scorecard":{"version":"v5.3.0","commit":"c22063e786c11f9dd714d777a687ff7c4599b600"},"score":7,"checks":[{"name":"Maintained","score":0,"reason":"project was created within the last 90 days. Please review its contents carefully","details":["Warn: Repository was created within the last 90 days."],"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#maintained"}},{"name":"Security-Policy","score":10,"reason":"security policy file detected","details":["Info: security policy file detected: SECURITY.md:1","Info: Found linked content: SECURITY.md:1","Info: Found disclosure, vulnerability, and/or timelines in security policy: SECURITY.md:1","Info: Found text in security policy: SECURITY.md:1"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#security-policy"}},{"name":"Dependency-Update-Tool","score":10,"reason":"update tool detected","details":["Info: detected update tool: Dependabot: .github/dependabot.yml:1"],"documentation":{"short":"Determines if the project uses a dependency update tool.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#dependency-update-tool"}},{"name":"Code-Review","score":0,"reason":"Found 0/10 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#code-review"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#dangerous-workflow"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#binary-artifacts"}},{"name":"Token-Permissions","score":10,"reason":"GitHub workflow tokens follow principle of least privilege","details":["Info: jobLevel 'contents' permission set to 'read': .github/workflows/ci.yml:250","Info: jobLevel 'contents' permission set to 'read': .github/workflows/ci.yml:29","Info: jobLevel 'contents' permission set to 'read': .github/workflows/ci.yml:138","Info: jobLevel 'contents' permission set to 'read': .github/workflows/ci.yml:152","Info: jobLevel 'contents' permission set to 'read': .github/workflows/ci.yml:169","Info: jobLevel 'actions' permission set to 'read': .github/workflows/codeql.yml:26","Info: jobLevel 'contents' permission set to 'read': .github/workflows/codeql.yml:27","Info: jobLevel 'contents' permission set to 'read': .github/workflows/docs.yml:61","Info: jobLevel 'contents' permission set to 'read': .github/workflows/hosted-controls.yml:24","Info: jobLevel 'contents' permission set to 'read': .github/workflows/pin-hygiene.yml:22","Info: jobLevel 'actions' permission set to 'read': .github/workflows/release.yml:29","Info: jobLevel 'contents' permission set to 'read': .github/workflows/release.yml:30","Info: jobLevel 'actions' permission set to 'read': .github/workflows/release.yml:65","Info: jobLevel 'contents' permission set to 'read': .github/workflows/release.yml:66","Info: jobLevel 'contents' permission set to 'read': .github/workflows/release.yml:303","Warn: jobLevel 'contents' permission set to 'write': .github/workflows/release.yml:393","Info: jobLevel 'actions' permission set to 'read': .github/workflows/release.yml:390","Info: jobLevel 'pull-requests' permission set to 'read': .github/workflows/scorecard.yml:26","Info: jobLevel 'checks' permission set to 'read': .github/workflows/scorecard.yml:22","Info: jobLevel 'contents' permission set to 'read': .github/workflows/scorecard.yml:23","Info: jobLevel 'issues' permission set to 'read': .github/workflows/scorecard.yml:25","Info: jobLevel 'contents' permission set to 'read': .github/workflows/security.yml:24","Info: jobLevel 'contents' permission set to 'read': .github/workflows/security.yml:40","Info: jobLevel 'actions' permission set to 'read': .github/workflows/security.yml:70","Info: jobLevel 'contents' permission set to 'read': .github/workflows/security.yml:71","Warn: jobLevel 'actions' permission set to 'write': .github/workflows/upstream-refresh.yml:21","Warn: jobLevel 'contents' permission set to 'write': .github/workflows/upstream-refresh.yml:22","Info: found token with 'none' permissions: .github/workflows/ci.yml:1","Info: found token with 'none' permissions: .github/workflows/codeql.yml:1","Info: found token with 'none' permissions: .github/workflows/docs.yml:1","Info: found token with 'none' permissions: .github/workflows/hosted-controls.yml:1","Info: found token with 'none' permissions: .github/workflows/pin-hygiene.yml:1","Info: found token with 'none' permissions: .github/workflows/release.yml:1","Info: found token with 'none' permissions: .github/workflows/scorecard.yml:1","Info: found token with 'none' permissions: .github/workflows/security.yml:1","Info: found token with 'none' permissions: .github/workflows/upstream-refresh.yml:1"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#token-permissions"}},{"name":"Pinned-Dependencies","score":9,"reason":"dependency not pinned by hash detected -- score normalized to 9","details":["Warn: npmCommand not pinned by hash: tools/remote-validator/Dockerfile:39-146","Warn: npmCommand not pinned by hash: tools/validator/Dockerfile:39-144","Info:  43 out of  43 GitHub-owned GitHubAction dependencies pinned","Info:  18 out of  18 third-party GitHubAction dependencies pinned","Info:   7 out of   7 containerImage dependencies pinned","Info:   1 out of   3 npmCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#cii-best-practices"}},{"name":"Packaging","score":10,"reason":"packaging workflow detected","details":["Info: Project packages its releases by way of GitHub Actions.: .github/workflows/release.yml:379"],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#packaging"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#vulnerabilities"}},{"name":"SAST","score":7,"reason":"SAST tool detected but not run on all commits","details":["Info: SAST configuration detected: CodeQL","Info: SAST configuration detected: CodeQL","Warn: 5 commits out of 30 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#sast"}},{"name":"Branch-Protection","score":5,"reason":"branch protection is not maximal on development and all release branches","details":["Info: 'allow deletion' disabled on branch 'main'","Info: 'force pushes' disabled on branch 'main'","Warn: 'branch protection settings apply to administrators' is disabled on branch 'main'","Info: 'stale review dismissal' is required to merge on branch 'main'","Warn: required approving review count is 1 on branch 'main'","Info: codeowner review is required on branch 'main'","Warn: 'last push approval' is disabled on branch 'main'","Info: 'up-to-date branches' is required to merge on branch 'main'","Info: status check found to merge onto on branch 'main'","Info: PRs are required in order to make changes on branch 'main'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#branch-protection"}},{"name":"Signed-Releases","score":8,"reason":"4 out of the last 4 releases have a total of 4 signed artifacts.","details":["Info: signed release artifact: SHA256SUMS.sigstore.json: https://github.com/omkhar/workcell/releases/tag/v0.7.0","Info: signed release artifact: SHA256SUMS.sigstore.json: https://github.com/omkhar/workcell/releases/tag/v0.6.0","Info: signed release artifact: SHA256SUMS.sigstore.json: https://github.com/omkhar/workcell/releases/tag/v0.5.1","Info: signed release artifact: SHA256SUMS.sigstore.json: https://github.com/omkhar/workcell/releases/tag/v0.2.7","Warn: release artifact v0.7.0 does not have provenance: https://api.github.com/repos/omkhar/workcell/releases/307200016","Warn: release artifact v0.6.0 does not have provenance: https://api.github.com/repos/omkhar/workcell/releases/306752456","Warn: release artifact v0.5.1 does not have provenance: https://api.github.com/repos/omkhar/workcell/releases/305514858","Warn: release artifact v0.2.7 does not have provenance: https://api.github.com/repos/omkhar/workcell/releases/303117414"],"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#signed-releases"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: Apache License 2.0: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#license"}},{"name":"Contributors","score":3,"reason":"project has 1 contributing companies or organizations -- score normalized to 3","details":["Info: found contributions from: linkedin"],"documentation":{"short":"Determines if the project has a set of contributors from multiple organizations (e.g., companies).","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#contributors"}},{"name":"CI-Tests","score":10,"reason":"10 out of 10 merged PRs checked by a CI test -- score normalized to 10","details":null,"documentation":{"short":"Determines if the project runs tests before pull requests are merged.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#ci-tests"}}]},"last_synced_at":"2026-04-10T02:46:15.731Z","repository_id":350354968,"created_at":"2026-04-10T02:46:15.731Z","updated_at":"2026-04-10T02:46:15.731Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33698654,"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-05-30T02:00:06.278Z","response_time":92,"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":["coding-agents","containers","developer-tools","macos","provenance","sandbox"],"created_at":"2026-04-15T01:03:04.859Z","updated_at":"2026-05-30T16:00:42.280Z","avatar_url":"https://github.com/omkhar.png","language":"Go","funding_links":[],"categories":["Sandboxing \u0026 Isolation"],"sub_categories":[],"readme":"# Workcell\n\n[![CI](https://github.com/omkhar/workcell/actions/workflows/ci.yml/badge.svg)](https://github.com/omkhar/workcell/actions/workflows/ci.yml)\n[![Docs](https://github.com/omkhar/workcell/actions/workflows/docs.yml/badge.svg)](https://github.com/omkhar/workcell/actions/workflows/docs.yml)\n[![Security](https://github.com/omkhar/workcell/actions/workflows/security.yml/badge.svg)](https://github.com/omkhar/workcell/actions/workflows/security.yml)\n\nWorkcell runs coding agents inside a bounded local runtime on Apple Silicon\nmacOS: a dedicated Colima VM plus a hardened container inside that VM. It ships\nTier 1 adapters for Codex, Claude Code, and Gemini that seed each provider's\nnative control plane without pretending provider config is the security\nboundary. GitHub Copilot CLI is the next committed Tier 1 provider-parity\ntrack, but current releases do not support `--agent copilot`.\n\nThis project is for teams that want local agent velocity without turning the\nhost home directory, keychain, provider state, or local sockets into the trust\nboundary.\n\n## Why Workcell\n\n- keep the runtime boundary explicit: dedicated VM, hardened container, minimal\n  mounts\n- keep provider adapters native: one shared boundary, thin provider-specific\n  control-plane mapping\n- keep publication on the host: signed commits, signed-range verification, and\n  GitHub publication stay out of Tier 1\n- keep verification paths nonroot by default: runtime and validator images\n  default to a named unprivileged `workcell` user, while repo-mounted\n  validation lanes pass explicit caller UID/GID and isolated writable state,\n  with a synthesized isolated home when the caller UID has no passwd entry in\n  the image\n- keep lower-assurance paths visible: `development`, package mutation,\n  transcripts, and `breakglass` are labeled instead of implied\n\n## How it compares\n\n| Approach | Primary boundary | Provider-native control plane | Host-side signed publication | Lower-assurance paths called out |\n|---|---|---|---|---|\n| Host-native provider CLI | host user session | yes | no | rarely |\n| Generic container wrapper | container only, often mixed with host state | often partial | varies | often unclear |\n| Workcell | dedicated Colima VM plus hardened container | yes | yes | yes |\n\n## Project status\n\n- pre-1.0 and still tightening the public contract\n- Apple Silicon macOS hosts only today; Linux and Windows are not currently\n  supported as launch hosts\n- local host-launched runtime first; cloud-facing paths today are the\n  preview-only `remote_vm/aws-ec2-ssm/compat` and\n  `remote_vm/gcp-vm/compat` broker plans, and their live smokes remain\n  certification-only\n- CLI surfaces for Codex, Claude, and Gemini plus host-side detached session\n  control and inspection commands\n- GitHub Copilot CLI is planned for the same Tier 1 adapter support bar as the\n  current providers; it is not launch-ready until the adapter, auth path,\n  quickstart, deterministic evidence, and live certification land together\n- GitHub-hosted CI verifies repo shape, reproducibility, release posture, and\n  secretless runtime behavior\n- GitHub-hosted CI continuously verifies bundle install/uninstall and Homebrew\n  install/uninstall on Apple Silicon `macos-26` and `macos-15`\n- the real macOS Colima boundary is still a local operator exercise because\n  GitHub-hosted Linux runners cannot prove it\n- the canonical host support boundary lives in\n  [policy/host-support-matrix.tsv](policy/host-support-matrix.tsv), and\n  `--doctor` / `--inspect` emit matching `support_matrix_*` lines\n- Workcell does not yet ship a centralized enterprise policy, inventory, or\n  analytics plane; team rollout today relies on distributing reviewed\n  host-side files\n\nBreaking changes should be called out in [CHANGELOG.md](CHANGELOG.md) and\ntracked in [ROADMAP.md](ROADMAP.md).\n\n## Community\n\n- use GitHub Discussions for usage questions, operator workflow notes, and\n  open-ended design conversations\n- use GitHub issues for confirmed bugs and concrete feature requests\n- use [SECURITY.md](SECURITY.md) for security-sensitive reports\n\nSee [SUPPORT.md](SUPPORT.md), [CONTRIBUTING.md](CONTRIBUTING.md), and\n[CITATION.cff](CITATION.cff) for the contributor and operator contract.\n\n## 5-minute path\n\nInstall Workcell, create the host-side auth policy, inspect the derived\nposture, then launch:\n\n```bash\n./scripts/install.sh\nworkcell auth init\nworkcell auth set \\\n  --agent codex \\\n  --credential codex_auth \\\n  --source /Users/example/.config/workcell/codex-auth.json\nworkcell --agent codex --doctor --workspace /path/to/repo\nworkcell --agent codex --inspect --workspace /path/to/repo\nworkcell --agent codex --workspace /path/to/repo\n```\n\nSee [docs/getting-started.md](docs/getting-started.md) for the release install\npath and provider-specific onboarding. For team rollout patterns on today's\nlocal-first product, see [docs/enterprise-rollout.md](docs/enterprise-rollout.md).\nUse [policy/host-support-matrix.tsv](policy/host-support-matrix.tsv) to interpret the\nhost support boundary that `--doctor` and `--inspect` report.\n\n## Install options\n\n### Tagged release bundle\n\nDownload a tagged release bundle, unpack it, and run the supported installer:\n\n```bash\ntar -xzf workcell-vX.Y.Z.tar.gz\ncd workcell-vX.Y.Z\n./scripts/install.sh\n```\n\nOn Apple Silicon macOS, `./scripts/install.sh` installs only the missing\nrequired Homebrew formulas (`colima`, `docker`, `gh`, `git`, `go`) before it\nlinks the launcher. Use `./scripts/install.sh --no-install-deps` to leave the\nsystem unchanged and get a warning summary of anything still missing.\n\n### Tagged Homebrew formula asset\n\nTagged releases can publish a versioned `workcell.rb` asset. Download it from\nthe release page and install it locally with Homebrew:\n\n```bash\ncurl -LO https://github.com/omkhar/workcell/releases/download/vX.Y.Z/workcell.rb\nbrew install --formula ./workcell.rb\n```\n\nThe formula declares the same required host dependencies: `colima`, `docker`,\n`gh`, `git`, and `go`.\n\n### Source checkout\n\nFor contributors and local repo review:\n\n```bash\ngit clone https://github.com/omkhar/workcell.git\ncd workcell\n./scripts/install.sh\n```\n\n`./scripts/install.sh` is the supported installer entrypoint. The\n`scripts/install-workcell.sh` helper remains an internal implementation detail.\n\n## Requirements\n\n- **macOS** (Apple Silicon only). Workcell manages a dedicated\n  [Colima](https://github.com/abiosoft/colima) VM profile using Apple's\n  Virtualization.Framework. Linux and Windows host platforms are not currently\n  supported.\n- **Homebrew** available on the host if you want the installer to auto-install\n  missing required packages.\n- Required host packages: `colima`, `docker`, `gh`, `git`, and `go`.\n  `./scripts/install.sh` installs only the missing ones on supported macOS\n  hosts by default, or you can install them yourself with\n  `brew install colima docker gh git go`.\n\n## Onboarding and auth\n\nThe supported way to feed stable inputs into sessions is an explicit injection\npolicy, usually at `~/.config/workcell/injection-policy.toml`.\n\nUse the host-side auth helpers instead of hand-editing the common case:\n\n```bash\nworkcell auth init\nworkcell auth set --agent codex --credential codex_auth --source /path/to/auth.json\nworkcell auth status --agent codex\nworkcell auth unset --agent codex --credential codex_auth\nworkcell policy validate\nworkcell why --agent codex --mode strict --credential codex_auth\nworkcell --agent codex --auth-status --workspace /path/to/repo\n```\n\n`workcell auth status` shows the host policy view. `--auth-status` shows the\nderived launch view after selector evaluation and preprocessing.\n`workcell policy show|validate|diff` inspects the merged host policy, and\n`workcell why` explains why one credential is selected, out of scope, filtered,\nor still only configured on the host side.\n\nDirect staged credentials are the primary supported auth path today. Built-in\nresolver coverage now includes Codex host-auth reuse through\n`codex-home-auth-file`, while the Claude macOS resolver remains a fail-closed\nscaffold until a supported export path exists.\n\n`workcell auth status` and `workcell --auth-status` print\n`provider_bootstrap_*` lines, and `workcell why` prints `bootstrap_*` lines for\nthe selected credential. Use those fields with\n[docs/provider-bootstrap-matrix.md](docs/provider-bootstrap-matrix.md) to see\nwhether a path is repo-required, certification-only, or manual.\n\nWorkcell can stage:\n\n- common or provider-specific instruction fragments\n- provider-native credentials such as `codex_auth`, `claude_auth`,\n  `claude_api_key`, `claude_mcp`, `gemini_env`, `gemini_oauth`,\n  `gemini_projects`, and `gcloud_adc`\n- scoped GitHub CLI credentials through `github_hosts` and `github_config`\n- SSH config, known hosts, and identities\n- explicit copied files or directories for non-reserved paths\n\nIt does not support whole-home passthrough, arbitrary environment-variable\nsecret injection, or host socket forwarding on the safe path.\n\nCopilot CLI credentials and `~/.copilot` state are not supported inputs yet.\nThe planned Copilot adapter must use an explicit staged credential, session-local\nCopilot home and cache paths, and reviewed GitHub-token handling before it can\njoin the supported provider set.\n\nSee [docs/injection-policy.md](docs/injection-policy.md) and\n[docs/examples/injection-policy.toml](docs/examples/injection-policy.toml).\nThe by-provider bootstrap tiers and handoffs live in\n[docs/provider-bootstrap-matrix.md](docs/provider-bootstrap-matrix.md).\n\n## Provider quickstarts\n\n| Provider | Tier 1 surface today | Native control plane | Quickstart |\n|---|---|---|---|\n| Codex | CLI | `~/.codex/config.toml`, `AGENTS.md`, rules, MCP config | [docs/examples/quickstart-codex.md](docs/examples/quickstart-codex.md) |\n| Claude | Claude Code CLI | `~/.claude/settings.json`, `CLAUDE.md`, `.mcp.json`, auth mirrors, hooks, host-side macOS auth resolver scaffold | [docs/examples/quickstart-claude.md](docs/examples/quickstart-claude.md) |\n| Gemini | Gemini CLI | `~/.gemini/settings.json`, `GEMINI.md`, `.env`, `projects.json` | [docs/examples/quickstart-gemini.md](docs/examples/quickstart-gemini.md) |\n\nPlanned provider parity:\n\n| Provider | Target surface | Required before support |\n|---|---|---|\n| GitHub Copilot CLI | planned Tier 1 CLI adapter; not current support | `--agent copilot`, explicit token staging, session-local `COPILOT_HOME` and `COPILOT_CACHE_HOME`, unsafe-argument policy, quickstart, deterministic tests, and live `copilot -p` certification |\n\nGUI and IDE surfaces are lower assurance unless they act only as clients to\nthe same bounded runtime.\n\nSee [docs/injection-policy.md](docs/injection-policy.md) for provider auth\nmaturity and [docs/enterprise-rollout.md](docs/enterprise-rollout.md) for the\ncurrent team rollout model.\n\n## Mode map\n\nWorkcell uses two terms throughout the docs:\n\n- `Tier 1`: a provider CLI running fully inside the bounded Workcell runtime\n- `strict`: the default managed Tier 1 runtime mode\n\n`--mode` selects one of four lanes:\n\n| `--mode` | Intended use | Key properties |\n|---|---|---|\n| `strict` | default provider lane | bounded VM plus container, reviewed network posture, repo control-plane masking, provider-focused entrypoint, `--agent-autonomy yolo` by default |\n| `development` | managed interactive development lane | same boundary and masking as `strict`, managed non-provider command execution, broader dependency egress, visibly lower assurance than `strict` |\n| `build` | image preparation and dependency refresh | broader egress for rebuild and preparation work |\n| `breakglass` | explicit higher-trust debugging path | requires `--ack-breakglass`; visibly lower assurance |\n\n`--container-mutability` is orthogonal to `--mode`: `ephemeral` (the\ndefault) allows package-manager mutations and labels the session\n`managed-mutable`, while `readonly` blocks package-manager writes and\ngives the strongest managed posture available — `--mode strict\n--container-mutability readonly` is the lane to pick when no\nlower-assurance downgrade is acceptable.\n\nOther defaults that matter:\n\n- `--agent` is always required; there is no default provider\n- `--agent-autonomy yolo` is the default; `--agent-autonomy prompt` is the\n  explicit lower-assurance opt-out\n- `--cache-profile off` is the default\n- `--cache-profile standard` keeps a workspace-scoped persistent non-secret\n  cache plane for package and compiler caches, but it is an explicit\n  lower-assurance path\n- strict launches prepare the reviewed runtime image automatically when needed\n- interactive launches show a spinner with elapsed time by default; use\n  `--no-spinner` to force plain heartbeat updates instead\n- `--prepare` and `--prepare-only` remain useful when you want to make that step explicit\n\n## Safe-path expectations\n\n- Workcell launches the selected provider directly inside the bounded runtime\n- there is no separate \"start a container, then attach the agent\" step\n- `publish-pr` runs on the host so signed commits, signed-range verification,\n  and GitHub publication stay outside the Tier 1 container, and it blocks\n  unsigned publish ranges and over-broad branch diffs before push so published\n  PRs stay reviewable; `main` is the only supported PR base by default, and\n  non-`main` bases remain an explicit lower-assurance draft-only escape hatch\n  with an explicit preflight warning that repo-owned PR checks are not expected\n  for that base\n- completed and aborted launches are recorded as durable host-side session\n  records that you can inspect with `workcell session ...`\n- `workcell session diff` compares the current workspace against the clean git\n  base recorded at launch and fails closed when the launch started dirty, when\n  no launch git base was recorded, or when the workspace is not a self-contained\n  git worktree\n- `--debug-log`, `--file-trace-log`, and `--audit-transcript` are explicit\n  lower-assurance operator choices and are off by default\n\nUseful operator flows:\n\nUse `--target colima|docker-desktop|aws-ec2-ssm|gcp-vm` to select the managed\nruntime backend.\n\n```bash\nworkcell --agent codex --prepare --workspace /path/to/repo\nworkcell --agent codex --prepare-only --workspace /path/to/repo\nworkcell --target docker-desktop --agent codex --workspace /path/to/repo\nworkcell --target aws-ec2-ssm --target-id i-1234567890abcdef0 --agent codex --workspace /path/to/repo --dry-run\nworkcell --target gcp-vm --target-id workcell-phase8-cert --agent codex --workspace /path/to/repo --dry-run\nworkcell --agent codex --mode development --workspace /path/to/repo -- bash -lc 'git status'\nworkcell session list\nworkcell session list --verbose\nworkcell session start --agent codex --workspace /path/to/repo\nworkcell session delete --id SESSION_ID\nworkcell session attach --id 20260408T120000Z-1a2b3c4d\nworkcell session send --id 20260408T120000Z-1a2b3c4d --message \"continue with tests\"\nworkcell session stop --id 20260408T120000Z-1a2b3c4d\nworkcell session show --id 20260408T120000Z-1a2b3c4d\nworkcell session show --id 20260408T120000Z-1a2b3c4d --text\nworkcell session logs --id 20260408T120000Z-1a2b3c4d --kind audit\nworkcell session timeline --id 20260408T120000Z-1a2b3c4d\nworkcell session diff --id 20260408T120000Z-1a2b3c4d\nworkcell session export --id 20260408T120000Z-1a2b3c4d --output /tmp/workcell-session.json\nworkcell policy show\nworkcell policy diff\nworkcell why --agent codex --mode strict --credential codex_auth\nworkcell --agent codex --doctor --workspace /path/to/repo\nworkcell --agent codex --inspect --workspace /path/to/repo\nworkcell --agent codex --auth-status --workspace /path/to/repo\nworkcell --gc\n./scripts/update-upstream-pins.sh --check\n./scripts/publish-provider-bump-pr.sh\nworkcell --logs audit --colima-profile wcl-...\nworkcell publish-pr --workspace /path/to/repo --branch feature/name \\\n  --title-file /tmp/pr-title.txt \\\n  --body-file /tmp/pr-body.md \\\n  --commit-message-file /tmp/commit-message.txt\n# Lower-assurance exception: non-main bases stay draft-only.\nworkcell publish-pr --workspace /path/to/repo --branch feature/name \\\n  --base feature/review-stack --allow-non-main-base \\\n  --title-file /tmp/pr-title.txt \\\n  --body-file /tmp/pr-body.md \\\n  --commit-message-file /tmp/commit-message.txt\n```\n\nFor the preview-only AWS and GCP remote VM broker paths and their certification\ngates, see [docs/aws-ec2-ssm-preview.md](docs/aws-ec2-ssm-preview.md) and\n[docs/gcp-vm-preview.md](docs/gcp-vm-preview.md).\n\n`workcell session list --verbose` adds target, workspace transport, git branch,\nand worktree columns without changing the default compact inventory view.\n`workcell session show --text` renders stable key=value lines for the same\ntarget-aware record, and `workcell session start|send|stop` emit stable\nkey=value summaries so host-side detached control stays scriptable.\n`workcell --gc` removes stale Workcell-owned temp scratch, disposable\nsession-audit directories, broken latest-log pointers, and over-budget runtime\nimage cache entries without deleting durable session records. It also removes\nstale regenerateable Workcell build cache entries.\n\n## Release posture\n\nTagged releases are rebuilt and verified before publication. The release path:\n\n- reruns validation, smoke, and reproducibility checks\n- reruns repo-mounted validator and release-helper paths under an explicit\n  caller UID/GID with isolated writable home, cache, and tmp roots instead of\n  relying on ambient container-root defaults, including passwd-less caller UIDs\n- verifies from GitHub-owned sources that the release install matrix still\n  targets the newest two GitHub-hosted Apple Silicon macOS runner labels\n- refuses to publish if any reviewed provider, Linux base image, Linux\n  toolchain, or release-build pin is behind the latest tracked upstream\n- adds Copilot upstream pin verification only after Copilot becomes a supported\n  provider adapter\n- publishes from the archived source bundle rather than the live checkout\n- gates publication on bundle and Homebrew install verification on\n  GitHub-hosted Apple Silicon `macos-26` and `macos-15`\n- signs the image, source bundle, Homebrew formula asset, published image\n  digest file, checksums, build-input manifest, control-plane manifest,\n  builder-environment manifest, and both SBOMs with keyless Sigstore/Cosign\n- publishes GitHub-native attestations when the reviewed hosted controls say\n  the repository visibility and GitHub plan support them for every published\n  primary release artifact, as an additional verification surface rather than a\n  replacement for Sigstore\n\nThat install matrix is the current release-gated support window. Other macOS\nversions may work, but they are not currently proven by tagged-release CI.\n\nForks can keep the GitHub attestation gates off. The upstream repo treats\nthose settings as hosted control-plane state and audits them accordingly.\n\nSee [docs/provenance.md](docs/provenance.md) and\n[docs/github-workflows.md](docs/github-workflows.md).\n\n## Docs map\n\n### Product and security docs\n\n| Topic | File |\n|---|---|\n| Getting started | [docs/getting-started.md](docs/getting-started.md) |\n| Security invariants | [docs/invariants.md](docs/invariants.md) |\n| Threat model | [docs/threat-model.md](docs/threat-model.md) |\n| Provider matrix | [docs/provider-matrix.md](docs/provider-matrix.md) |\n| Adapter control planes | [docs/adapter-control-planes.md](docs/adapter-control-planes.md) |\n| Injection policy | [docs/injection-policy.md](docs/injection-policy.md) |\n| Validation coverage | [docs/validation-scenarios.md](docs/validation-scenarios.md) |\n| Requirements validation | [docs/requirements-validation.md](docs/requirements-validation.md) |\n| Scenario gaps | [docs/scenario-gaps.md](docs/scenario-gaps.md) |\n| Use-case coverage | [docs/use-case-matrix.md](docs/use-case-matrix.md) |\n| Session supervisor design | [docs/workcell-session-supervisor-design.md](docs/workcell-session-supervisor-design.md) |\n| Managed workstation contract | [docs/managed-workstation-contract.md](docs/managed-workstation-contract.md) |\n| Enterprise evidence baseline | [docs/enterprise-evidence-baseline.md](docs/enterprise-evidence-baseline.md) |\n| Host expansion readiness | [docs/host-expansion-readiness.md](docs/host-expansion-readiness.md) |\n| Provenance and signing | [docs/provenance.md](docs/provenance.md) |\n| GitHub automation | [docs/github-workflows.md](docs/github-workflows.md) |\n\n### Project docs\n\n| Topic | File |\n|---|---|\n| Contributor workflow | [CONTRIBUTING.md](CONTRIBUTING.md) |\n| Support | [SUPPORT.md](SUPPORT.md) |\n| Code of conduct | [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) |\n| Governance | [GOVERNANCE.md](GOVERNANCE.md) |\n| Maintainers | [MAINTAINERS.md](MAINTAINERS.md) |\n| Roadmap | [ROADMAP.md](ROADMAP.md) |\n| Changelog | [CHANGELOG.md](CHANGELOG.md) |\n| Security reporting | [SECURITY.md](SECURITY.md) |\n\n## Repository layout\n\n- `runtime/`: VM and container boundary implementation\n- `policy/`: shared contract layer and hosted-control policy\n- `adapters/`: provider-native baselines for Codex, Claude, and Gemini; the\n  Copilot baseline joins here only when its adapter support lands\n- `cmd/`: host-side and runtime-side Go entrypoints (the `workcell-*` binaries)\n- `internal/`: shared Go packages backing the `cmd/` binaries\n- `scripts/`: launcher, validation, release, audit, and bootstrap entrypoints\n- `verify/`: invariant-oriented verification material\n- `man/`: workcell.1 manpage\n- `tests/`: scenario manifests and fixtures\n- `tools/`: developer tooling (markdownlint, validator image)\n- `docs/`: user-facing design, quickstarts, install, and release docs\n- `workflows/`: implementation notes such as adapter porting guidance\n\n## License\n\nWorkcell is licensed under Apache-2.0. See `LICENSE`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fomkhar%2Fworkcell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fomkhar%2Fworkcell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fomkhar%2Fworkcell/lists"}