From a32596d3ac6302855e89c0038dd3b6f5c63ca7a0 Mon Sep 17 00:00:00 2001 From: msample <4896732+msample@users.noreply.github.com> Date: Thu, 16 Jul 2026 16:57:43 -0700 Subject: [PATCH 1/7] docs(CLA,README,CONTRIBUTING,LICENSE): add/update files --- CODE_OF_CONDUCT.md | 9 ++ CONTRIBUTING.md | 64 +++++++++++++- LICENSE | 202 ++++++++++++++++++++++++++++++++++++++++++++ README.md | 205 ++++++++++++++++++++++++++------------------- legal/CCLA.md | 81 ++++++++++++++++++ legal/ICLA.md | 67 +++++++++++++++ 6 files changed, 542 insertions(+), 86 deletions(-) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 LICENSE create mode 100644 legal/CCLA.md create mode 100644 legal/ICLA.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000000..8f7f43da0f --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,9 @@ +# Code of Conduct + +This project has adopted the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) as its code of conduct. By participating in this project — contributing code, filing issues, joining discussions, or otherwise engaging with the community — you agree to uphold it. + +The full text is available at the link above. + +## Reporting + +To report unacceptable behavior, please email **security@minimal.dev**. Reports will be reviewed and investigated promptly and confidentially. The project maintainers are obligated to respect the privacy and security of anyone who reports an incident. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9b590bb645..f9f33b8025 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,15 @@ -# Contributing +# Contributing to Minimal's Public Registry (https://github.com/gominimal/pkgs) + +Thank you for your interest in contributing! This project is developed by **Minimal.dev Software Inc.** and released under the [Apache License 2.0](./LICENSE). + +We welcome contributions of all kinds — bug reports, documentation improvements, features, and feedback. This document explains how to contribute and what you need to know about our Contributor License Agreement (CLA). + +## TL;DR + +1. Fork the "main" branch and commit your chanages to your fork +4. Submit your PR as normal +2. Before we can accept your pull request, you'll need to sign our **Contributor License Agreement (CLA)**. +3. This happens automatically on your first PR — a bot will comment with a link. It takes about 30 seconds. ## Commit messages @@ -11,6 +22,7 @@ The most common trip-up: a commit has **one type**, and multiple scopes go `type(scope-a),scope-b:` (the latter makes commitlint read an empty type and fails the check). + ## Building and testing See [README.md](README.md) for build instructions. @@ -56,3 +68,53 @@ misnamed, so it can never silently drop out of a lane. When a genuinely new *kind* of check is needed, add it to `scripts/` or the `justfile` (reviewed code) and let the lane call it — never by growing the YAML. + +## Why do we require a CLA? + +A CLA is a standard instrument in many large open source projects (the Apache Software Foundation, Google, Microsoft, the CNCF, and many others all require one). It clearly defines the terms under which intellectual property has been contributed. By having these instruments in place, it supports the growth and sustainability of this open source project. + +Full text: [ICLA](./legal/ICLA.md) · [CCLA](./legal/CCLA.md) + +## Individual vs. Corporate + +- **Contributing as yourself, on your own time, with code you own?** Sign the **Individual CLA (ICLA)**. The bot will walk you through it. +- **Contributing as part of your job, or with code your employer might own?** Your employer needs to sign the **Corporate CLA (CCLA)** and list you as an authorized contributor. Then you'll also sign the ICLA. If you're unsure whether your employer has rights to your contribution, it's worth a conversation with them before contributing. Email **security@minimal.dev** if you need help getting a CCLA in place. + +## How signing works + +We use [CLA Assistant](https://cla-assistant.io/). When you open your first pull request: + +1. A bot will comment with a link to the CLA. +2. Click the link, review the document, and click "I Agree" after signing in with your GitHub account. +3. The bot will re-check your PR and mark the CLA status as satisfied. +4. Once signed, you're covered for all future contributions to any of our repositories. + +Your signature record (GitHub username, email, timestamp, CLA version) is stored and available for your records. + +## Development workflow + +1. Fork the repository. +2. Create a feature branch: `git checkout -b your-feature-name`. +3. Make your changes. Add tests where appropriate. +4. Ensure the existing tests still pass. +5. Commit with a clear message. We don't require a specific commit format, but "why" is more useful than "what." +6. Push to your fork and open a pull request against `main`. +7. Sign the CLA if prompted. + +## What we look for in contributions + +- **Small, focused PRs.** Easier to review, faster to merge. +- **Tests.** New behavior needs tests. Bug fixes should include a regression test. +- **Discuss before large changes.** For anything substantial, please open an issue first so we can align on design. + +## Reporting security issues + +Please do **not** file security issues as public GitHub issues. Email **security@minimal.dev** instead. We'll respond within 5 business days. + +## Code of Conduct + +This project follows the [Contributor Covenant](https://www.contributor-covenant.org/). By participating, you agree to uphold it. + +## Questions? + +Open a discussion, file an issue, or email **security@minimal.dev**. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000000..d645695673 --- /dev/null +++ b/LICENSE @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/README.md b/README.md index 99d60884e0..df931846aa 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,117 @@ -## Building `minimal` +# Minimal -The "minimal" CLI tool runs on amd64 and aarch64 Linux. +Minimal provides VM-based development sandboxes and a secure package manager the for dev tools used in those sandboxes. -8 cores and at least 16 Gb of RAM is recommended to build the entire package registry but it should (slowly) run on a wet piece of spaghetti. +# Features +Minimal can repeatably create a Linux, terminal-baseed development environment sandboxes populated with exactly the toolsets and agents you need as specified in your minimal.toml blueprint. -### Dependencies -1. Install a fairly recent version of rust: https://rust-lang.org/tools/install/ -2. Install deps (openssl, pkg-config, build-essential, git, protoc-compiler): `sudo apt-get install build-essential openssl pkg-config libssl-dev git protobuf-compiler ` +The tool executables (compilers, agents, shells, etc.) available in these sandboxes come from Minimal's [curated package registry](https://github.com/gominimal/pkgs/) which is refreshed daily. Simply add a minimal.toml to your project's git repo and all your teammates will have identical development environemnts that isolate AI agents from their laptops. Updating the shared minimal.toml to reference the freshest tool versions is just a `min update` away. No more outdated wiki pages for dev-env setup and version drift across your team. + +Per-developer "Loadouts" can be included in each development environment so everyone can work efficiently by using the editors, terminal multiplexers and their configs that match their hard-earned muscle memory. + +## Contents + + +## Tech Stack + +Sandboxes: pure Rust client, daemon and VM manager. The sandbox VM is powered by [libkrun](https://github.com/libkrun/libkrun), a custom Linux kernel image and an Alpine Linux rootfs + +[Packages](https://github.com/gominimal/pkgs/): glibc-based packages built frequently on Minimal's build servers from their cannonical sources (GNU, Github, Gitlab, etc.) + + +## Installation + +Minimal works on MacOS/ARM64 and Linux/{ARM64,X86_64}. To get started, install it with the following shell command (stable is coming soon): + +```shell +curl --proto "=https" --tlsv1.2 -fsSL 'https://go.minimal.dev/unstable' | sh +``` + +This should install Minimal on your system, add "min" to your PATH, and setup shell completions for bash, fish, and zsh. + +Minimal can be unistalled with: +```shell +curl --proto "=https" --tlsv1.2 -fsSL 'https://go.minimal.dev/unstable' | sh -s -- --uninstall +``` + +## Getting Started + +### Create a new project with Minimal + +In this example we'll create a new git repo from within a Minimal sandbox using tools from the [Minimal Public Registry](https://github.com/gominimal/pkgs/) + +```shell +mkdir -p ~/projects/foo +cd ~/projects/foo + +# create and update a minimal.toml file +min init +min add --session git gh claude-code mermaid-cli kittyview less emacs + +# copy a Github PAT to your clipboard +security find-generic-password -w -s "PAT-foo-repo" -a "my-mac-user-namea" | pbcopy + +# start and enter a sandbox, which copies up the CWD file tree into the sandbox +min activate --attach . + +read -sp "paste GH PAT now:" GH_TOKEN && export GH_TOKEN +git init + +claude --dangerously-skip-permissions +# develop specs, generate code etc + +git add -A +git commit -m "initial checkin" + +git remote add origin https@github.com:gominimal/gatehouse.git +git branch -M main +git push -u origin main + +exit + +``` + +We show using a github personal access token (PAT) from the MacOS keychain in the example above. To create fine-grained PATs (e.g. scoped to a specific repo) go to https://github.com/settings/personal-access-tokens. To add a new token to the MacOS keychain use: +```shell +security add-generic-password -s "PAT-foo-repo" -a "my-mac-user-name" -w +``` + +### Work on an existing project in a Minimal sandbox + +In this example we'll work on an existing git repo that already has minimal.toml + +```shell +cd ~/projects/foo + +# get latest files on current branch +git pull + +# copy a Github PAT to your clipboard +security find-generic-password -w -s "PAT-foo-repo" -a "my-mac-user-namea" | pbcopy + +# don't copy any files up we'll git pull in the sandbox +min activate --attach --sync none . + +read -sp "paste GH PAT now:" GH_TOKEN && export GH_TOKEN + +git pull + +claude --dangerously-skip-permissions +# add new features, fix bugs etc + +git add -A +git commit -m "feat: add foozinator CLI option" +git push -u origin main + +exit +``` + +### Add a Minimal Loadout with your preferred tools and configurations + +## Building and Testing + +(To be updated) -### Building the binary Either: `cargo build` for debug (faster build) and `cargo build --release` (slower build, faster execution) ### Ubuntu 24.04+ hosts @@ -29,92 +132,24 @@ loader and prints a hint when the host needs it; run See [docs/reference/linux-host-setup.md](docs/reference/linux-host-setup.md). -## Using minimal - -You can run minimal either via the build binary in `target/{debug,release}/minimal` or using cargo (which will auto-rebuild as you change rust sauce): -```shell -$> cargo run -- -``` +## Contributing -### Minimal commands +We'd love your help! Please [open an Issue](https://github.com/gominimal/minimal/issues/new/choose) (or a [Discussion](https://github.com/gominimal/minimal/discussions/new/choose)( if it's large in scope) to outline the improvments you're seeking -``` -The Minimal CLI - -Usage: minimal [OPTIONS] - -Commands: - run Runs a task specified in `minimal.toml` - update Refreshes local checkouts of upstream packages & the standard library - add Add a new tool or dependency - init Automatically initialize minimal configuration based on your source tree - status Shows the status of Minimal in this codebase - shell Launches a development shell (shorthand for `minimal run shell`) - build Runs the build task. Shorthand for `minimal run build` - test Runs the test task. Shorthand for `minimal run test` - materialize Materializes an output specified in `minimal.toml` - pkg Builds the specified package(s) in a clean room, making them available in the local cache - cache Manipulate the local cache - check Validates minimal configuration including packages, stacks, and profiles - dep Generates Graphviz source code of the dependency graph - completions Generate shell completion script - help Print this message or the help of the given subcommand(s) - -Options: - --minimal-dir - Override the base directory used for operations (default: ~/.cache/minimal) - -C, --repo-dir - Use the given directory as the repository root, instead of searching from the current working directory - --no-cache - Ignore locally-available binary artifacts (results in rebuilds unless present in a remote cache) - --no-fetch - Do not fetch binary artifacts from the internet - --offline - Use only what's already in the local cache; fail on any network call - -n, --num-parallel-builds - Configure the number of parallel builds - -h, --help - Print help - -V, --version - Print version -``` +If you want to contribute code, docs, etc please head over to [CONTRIBUTING.md](./CONTRIBUTING.md) for the development workflow and what we look for in a contribution. -You'll probably use the subcommands `build` and `pkg` most of the time. -Switches for the local & remote cache: +### Contributor License Agreement - * `--no-fetch`: Do not fetch anything from the "remote cache" (the GCP bucket). - * `--no-cache`: Rebuild everything thats needed: do not use anything that was built in an earlier invocation nor anything fetched in an earlier invocation. +Before we can merge your first pull request, you'll need to accept our **Individual Contributor License Agreement (ICLA)**. This is a one-time, ~30 second step: [CLA Assistant](https://cla-assistant.io/) will post a link on your PR, you click through, sign in with GitHub, and you're done — you're then covered for all future contributions to this repository. -These args apply to planning as well. +If you're contributing on your employer's time, or with code your employer might own, your employer will also need a **Corporate CLA (CCLA)** on file listing you as an authorized contributor. See [CONTRIBUTING.md](./CONTRIBUTING.md) for details, or email **security@minimal.dev** if you need help getting one set up. -## CI/CD +Full text: [ICLA](./legal/ICLA.md) · [CCLA](./legal/CCLA.md) -### ci.yml — Build pipeline +## License -Runs on every push and PR to `main`. On pushes to `main`, builds static -musl binaries for amd64 and arm64, creates a GitHub release, and uploads -CLI archives to `gs://minimal-shim/archives/`. +This project is licensed under the [Apache License Version 2.0](LICENSE) +- see the [LICENSE](LICENSE) file for details. -### promote.yml — CLI version promotion - -Manual `workflow_dispatch` with inputs: -- `sha` (optional): short SHA to promote (defaults to latest archive in bucket) -- `platforms` (optional): comma-separated list or `"all"` (default: `"amd64-linux,arm64-linux"`) -- `dry_run` (optional, boolean, default `false`): when `true`, opens the approval issue and logs what would be written but skips the actual GCS config write - -Verifies the archive exists in GCS, then writes per-platform config files -under `gs://minimal-shim/config/`. - -### GCS permissions - -CI workflows authenticate via Workload Identity Federation (WIF). The WIF -principal for this repo requires `roles/storage.objectUser` on the -`gs://minimal-shim` bucket, which grants create, delete, get, list, and -update on objects. This is the minimum predefined role that supports -uploading archives and overwriting config files during promotion. - -``` -principal://iam.googleapis.com/projects/289724348228/locations/global/workloadIdentityPools/github/subject/repo:gominimal/minimal:ref:refs/heads/main -``` diff --git a/legal/CCLA.md b/legal/CCLA.md new file mode 100644 index 0000000000..d4e870a708 --- /dev/null +++ b/legal/CCLA.md @@ -0,0 +1,81 @@ +# Corporate Contributor License Agreement ("Agreement") v1.0 + +Thank you for your interest in contributing to software projects made available by **Minimal.dev Software Inc.** ("We" or "Us"). + +This Corporate Contributor License Agreement ("Agreement") documents the rights granted by contributors to Us. This is a legally binding document, so please read it carefully before agreeing to it. This Agreement covers Contributions submitted to Us by employees of the entity signing this Agreement ("Corporation"), including without limitation those designated on Schedule A as the initial employees authorized to submit Contributions. + +## 1. Definitions + +**"Corporation"** means the entity identified below which is making this Agreement with Us. + +**"You"** means the Corporation and any of its Affiliates. "Affiliate" means any entity that controls, is controlled by, or is under common control with the Corporation, where "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. + +**"Contribution"** means any original work of authorship, including any modifications or additions to an existing work, that is intentionally submitted by You to Us for inclusion in, or documentation of, any of the products owned or managed by Us (the "Work"). "Submitted" means any form of electronic, verbal, or written communication sent to Us or our representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, Us for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by You as "Not a Contribution." + +## 2. Grant of Copyright License + +Subject to the terms and conditions of this Agreement, You hereby grant to Us and to those who receive the Contributions directly or indirectly from Us a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable license to reproduce, prepare derivative works of, publicly display, publicly perform, publish, sublicense, and distribute Your Contributions and such derivative works. + +**You further grant to Us the right to relicense Your Contributions, in whole or in part, under any license terms, including proprietary license terms, at Our sole discretion.** This grant includes the right to incorporate Your Contributions into works distributed under licenses different from the license under which the Work was originally distributed. + +## 3. Grant of Patent License + +Subject to the terms and conditions of this Agreement, You hereby grant to Us and to recipients of software distributed by Us a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by You that are necessarily infringed by Your Contribution(s) alone or by combination of Your Contribution(s) with the Work to which such Contribution(s) was submitted. If any entity institutes patent litigation against You or any other entity (including a cross-claim or counterclaim in a lawsuit) alleging that your Contribution, or the Work to which you have contributed, constitutes direct or contributory patent infringement, then any patent licenses granted to that entity under this Agreement for that Contribution or Work shall terminate as of the date such litigation is filed. + +## 4. Representations + +You represent that: + +(a) You are legally entitled to grant the above license. + +(b) Each employee of the Corporation designated on Schedule A below (or in a subsequent written amendment) is authorized to submit Contributions on behalf of the Corporation. + +(c) Each Contribution is either Your original creation or You have sufficient rights in the Contribution to grant the licenses conferred by this Agreement. + +(d) Each Contribution submission includes complete details of any third-party license or other restriction (including, but not limited to, related patents and trademarks) of which You are aware and which are associated with any part of Your Contributions. + +## 5. Support + +You are not expected to provide support for Your Contributions, except to the extent You desire to provide support. You may provide support for free, for a fee, or not at all. Save as otherwise expressly provided for in section 4 (Representations), or unless required by applicable law or agreed to in writing, You provide Your Contributions on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. + +## 6. Notification of Changes + +It is Your responsibility to notify Us when any change is required to the list of designated employees authorized to submit Contributions on behalf of the Corporation, or to the Corporation's Point of Contact with Us. You also agree to notify Us of any facts or circumstances of which You become aware that would make the representations in section 4 (Representations) inaccurate in any respect. + +## 7. Third-Party Submissions + +Should You wish to submit work that is not Your original creation, You may submit it to Us separately from any Contribution, identifying the complete details of its source and of any license or other restriction (including, but not limited to, related patents, trademarks, and license agreements) of which You are aware, and conspicuously marking the work as "Submitted on behalf of a third-party: [named here]". + +## 8. Miscellaneous + +This Agreement is governed by the laws of the Province of British Columbia and the federal laws of Canada applicable therein, without regard to its conflict-of-laws principles. The parties attorn to the exclusive jurisdiction of the courts of the Province of British Columbia in respect of any dispute arising out of or in connection with this Agreement. This Agreement sets forth the entire understanding between You and Us regarding Contributions made by the Corporation and supersedes all prior agreements or understandings on the subject. + +--- + +## Corporate Signatory + +| Field | Value | +|--------------------------|----------------------------------------| +| Corporation Name | ______________________________________ | +| Corporation Address | ______________________________________ | +| Point of Contact (Name) | ______________________________________ | +| Point of Contact (Email) | ______________________________________ | +| Signatory Name | ______________________________________ | +| Signatory Title | ______________________________________ | +| Signature | ______________________________________ | +| Date | ______________________________________ | + +--- + +## Schedule A — Authorized Employees + +Initial list of employees authorized to submit Contributions on behalf of the Corporation. Updates to this list shall be provided to Us in writing (email to the Point of Contact at security@minimal.dev is sufficient). + +| Full Name | GitHub Username | Email | +|-----------|-----------------|-------| +| | | | +| | | | +| | | | +| | | | + +*Use an additional page if needed.* diff --git a/legal/ICLA.md b/legal/ICLA.md new file mode 100644 index 0000000000..5608437c85 --- /dev/null +++ b/legal/ICLA.md @@ -0,0 +1,67 @@ +# Individual Contributor License Agreement ("Agreement") v1.0 + +Thank you for your interest in contributing to software projects made available by **Minimal.dev Software Inc.** ("We" or "Us"). + +In order to clarify the intellectual property license granted with Contributions from any person or entity, We must have a Contributor License Agreement ("CLA") on file that has been signed by each Contributor, indicating agreement to the license terms below. This license is for Your protection as a Contributor as well as the protection of Us and Our users; it does not change Your rights to use Your own Contributions for any other purpose. + +This is a legally binding document, so please read this document carefully before signing, ensuring that you understand all of the terms, and keep a copy for your records. + +By signing below (or by indicating acceptance via the electronic signing process provided by Us, including by clicking an "I Agree" control clearly referencing this Agreement), You accept and agree to the following terms and conditions for Your present and future Contributions submitted to Us. Except for the license granted herein to Us and recipients of software distributed by Us, You reserve all right, title, and interest in and to Your Contributions. + +## 1. Definitions + +**"You"** (or **"Your"**) shall mean the copyright owner or legal entity authorized by the copyright owner that is entering into this Agreement with Us. For legal entities, the entity making a Contribution and all other entities that control, are controlled by, or are under common control with that entity are considered to be a single Contributor. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. + +**"Contribution"** shall mean any original work of authorship, including any modifications or additions to an existing work, that is intentionally submitted by You to Us for inclusion in, or documentation of, any of the products owned or managed by Us (the "Work"). For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to Us or our representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, Us for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by You as "Not a Contribution." + +## 2. Grant of Copyright License + +Subject to the terms and conditions of this Agreement, You hereby grant to Us and to those who receive the Contributions directly or indirectly from Us a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute Your Contributions and such derivative works. + +**You further grant to Us the right to relicense Your Contributions, in whole or in part, under any license terms, including proprietary license terms, at Our sole discretion.** This grant includes the right to incorporate Your Contributions into works distributed under licenses different from the license under which the Work was originally distributed. + +## 3. Grant of Patent License + +Subject to the terms and conditions of this Agreement, You hereby grant to Us and to recipients of software distributed by Us a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by You that are necessarily infringed by Your Contribution(s) alone or by combination of Your Contribution(s) with the Work to which such Contribution(s) was submitted. If any entity institutes patent litigation against You or any other entity (including a cross-claim or counterclaim in a lawsuit) alleging that your Contribution, or the Work to which you have contributed, constitutes direct or contributory patent infringement, then any patent licenses granted to that entity under this Agreement for that Contribution or Work shall terminate as of the date such litigation is filed. + +## 4. Representations + +You represent that: + +(a) You are legally entitled to grant the above license. If Your employer(s) has rights to intellectual property that You create that includes Your Contributions, You represent that You have received permission to make Contributions on behalf of that employer, that Your employer has waived such rights for Your Contributions to Us, or that Your employer has executed a separate Corporate CLA with Us. + +(b) Each of Your Contributions is Your original creation (see section 7 for submissions on behalf of others). + +(c) Your Contribution submissions include complete details of any third-party license or other restriction (including, but not limited to, related patents and trademarks) of which You are personally aware and which are associated with any part of Your Contributions. + +## 5. Support + +You are not expected to provide support for Your Contributions, except to the extent You desire to provide support. You may provide support for free, for a fee, or not at all. Save as otherwise expressly provided for in section 4 (Representations), or unless required by applicable law or agreed to in writing, You provide Your Contributions on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. + +## 6. Notification of Changes + +You agree to notify Us of any facts or circumstances of which You become aware that would make the representations in section 4 (Representations) inaccurate in any respect. + +## 7. Third-Party Submissions + +Should You wish to submit work that is not Your original creation, You may submit it to Us separately from any Contribution, identifying the complete details of its source and of any license or other restriction (including, but not limited to, related patents, trademarks, and license agreements) of which You are personally aware, and conspicuously marking the work as "Submitted on behalf of a third-party: [named here]". + +## 8. Miscellaneous + +This Agreement is governed by the laws of the Province of British Columbia and the federal laws of Canada applicable therein, without regard to its conflict-of-laws principles. The parties attorn to the exclusive jurisdiction of the courts of the Province of British Columbia in respect of any dispute arising out of or in connection with this Agreement. This Agreement sets forth the entire understanding between You and Us regarding Your Contributions and supersedes all prior agreements or understandings on the subject. + +--- + +## Acceptance + +By signing below (or by indicating acceptance via the electronic signing process provided by Us, including by clicking an "I Agree" control clearly referencing this Agreement), You agree to the terms of this Agreement for Your present and future Contributions to Us. + +| Field | Value | +|-----------------|----------------------------------------| +| Full Name | ______________________________________ | +| GitHub Username | ______________________________________ | +| Email Address | ______________________________________ | +| Mailing Address | ______________________________________ | +| Country | ______________________________________ | +| Signature | ______________________________________ | +| Date | ______________________________________ | From 51f22f899fb1d5f95201517ed6cacd77411668d7 Mon Sep 17 00:00:00 2001 From: msample <4896732+msample@users.noreply.github.com> Date: Thu, 16 Jul 2026 17:05:23 -0700 Subject: [PATCH 2/7] docs(CONTRIBUTING): fix typo --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f9f33b8025..e0a03099f1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# Contributing to Minimal's Public Registry (https://github.com/gominimal/pkgs) +# Contributing to Minimal (https://github.com/gominimal/minimal) Thank you for your interest in contributing! This project is developed by **Minimal.dev Software Inc.** and released under the [Apache License 2.0](./LICENSE). From 30de4175550b61e24cadd114fdc955239bbd3e8f Mon Sep 17 00:00:00 2001 From: msample <4896732+msample@users.noreply.github.com> Date: Thu, 16 Jul 2026 17:10:10 -0700 Subject: [PATCH 3/7] docs(README): fix typos --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index df931846aa..ae468410dc 100644 --- a/README.md +++ b/README.md @@ -49,7 +49,7 @@ min init min add --session git gh claude-code mermaid-cli kittyview less emacs # copy a Github PAT to your clipboard -security find-generic-password -w -s "PAT-foo-repo" -a "my-mac-user-namea" | pbcopy +security find-generic-password -w -s "PAT-foo-repo" -a "my-mac-user-name" | pbcopy # start and enter a sandbox, which copies up the CWD file tree into the sandbox min activate --attach . @@ -87,7 +87,7 @@ cd ~/projects/foo git pull # copy a Github PAT to your clipboard -security find-generic-password -w -s "PAT-foo-repo" -a "my-mac-user-namea" | pbcopy +security find-generic-password -w -s "PAT-foo-repo" -a "my-mac-user-name" | pbcopy # don't copy any files up we'll git pull in the sandbox min activate --attach --sync none . From 8d5716f14c6ebc9c67cdc0cf92196f7cd190f6fe Mon Sep 17 00:00:00 2001 From: msample <4896732+msample@users.noreply.github.com> Date: Thu, 16 Jul 2026 17:12:42 -0700 Subject: [PATCH 4/7] docs(README): fix typos --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index ae468410dc..833e722aae 100644 --- a/README.md +++ b/README.md @@ -63,7 +63,7 @@ claude --dangerously-skip-permissions git add -A git commit -m "initial checkin" -git remote add origin https@github.com:gominimal/gatehouse.git +git remote add origin https@github.com:.git git branch -M main git push -u origin main @@ -94,7 +94,7 @@ min activate --attach --sync none . read -sp "paste GH PAT now:" GH_TOKEN && export GH_TOKEN -git pull +git pull https@github.com:.git claude --dangerously-skip-permissions # add new features, fix bugs etc From 26b38064875f1e4d85f99e50f7231a8407e4f035 Mon Sep 17 00:00:00 2001 From: msample <4896732+msample@users.noreply.github.com> Date: Fri, 17 Jul 2026 12:37:08 -0700 Subject: [PATCH 5/7] docs(README): example updates, supported platforms --- README.md | 65 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 42 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 833e722aae..159cd38d51 100644 --- a/README.md +++ b/README.md @@ -18,10 +18,15 @@ Sandboxes: pure Rust client, daemon and VM manager. The sandbox VM is powered by [Packages](https://github.com/gominimal/pkgs/): glibc-based packages built frequently on Minimal's build servers from their cannonical sources (GNU, Github, Gitlab, etc.) +## Supported Platforms + +Minimal works on: +- MacOS / ARM64 (Apple Silicon) +- Ubuntu and Debian Linux, ARM64 and X86_64, with a Linux kernel >= 5.10. Rootless user-namespace creation must be enabled for non-VM usage. ## Installation -Minimal works on MacOS/ARM64 and Linux/{ARM64,X86_64}. To get started, install it with the following shell command (stable is coming soon): + To get started, install it with the following shell command (stable is coming soon): ```shell curl --proto "=https" --tlsv1.2 -fsSL 'https://go.minimal.dev/unstable' | sh @@ -38,7 +43,32 @@ curl --proto "=https" --tlsv1.2 -fsSL 'https://go.minimal.dev/unstable' | sh -s ### Create a new project with Minimal -In this example we'll create a new git repo from within a Minimal sandbox using tools from the [Minimal Public Registry](https://github.com/gominimal/pkgs/) +In this example we'll create a new git repo from within a Minimal sandbox using tools from the [Minimal Public Registry](https://github.com/gominimal/pkgs/). In this example we assume your claude code has been granted access to your git repos in order to push your changes there. + +```shell +mkdir -p ~/projects/foo +cd ~/projects/foo + +# create and update a minimal.toml file +min init +min add --session git gh claude-code + +# start and enter a sandbox, which copies up the CWD file tree into the sandbox +min activate --attach . + +git init + +# develop specs, generate & test code etc, push to git, etc +# agents can add sw tools from Minimal Public Registry dynamically with "min add" +claude-code + +exit +``` + +Above we show using Claude Code where you have trusted Claude Github App is Github on your behalf. Below we show using a Github personal access token (PAT) from the MacOS keychain. To create fine-grained PATs (e.g. scoped to a specific repo) go to https://github.com/settings/personal-access-tokens. + +Once you have created the PAT and copied it into your keychain (e.g. `security add-generic-password -s "PAT-foo-repo" -a "my-mac-user-name" -w`), and created the new, empty Github repo, the following example shows populating it the repo from within a sandbox. + ```shell mkdir -p ~/projects/foo @@ -48,13 +78,14 @@ cd ~/projects/foo min init min add --session git gh claude-code mermaid-cli kittyview less emacs -# copy a Github PAT to your clipboard +# copy a Github PAT to your clipboard from your MacOS keychain security find-generic-password -w -s "PAT-foo-repo" -a "my-mac-user-name" | pbcopy # start and enter a sandbox, which copies up the CWD file tree into the sandbox min activate --attach . read -sp "paste GH PAT now:" GH_TOKEN && export GH_TOKEN + git init claude --dangerously-skip-permissions @@ -71,46 +102,34 @@ exit ``` -We show using a github personal access token (PAT) from the MacOS keychain in the example above. To create fine-grained PATs (e.g. scoped to a specific repo) go to https://github.com/settings/personal-access-tokens. To add a new token to the MacOS keychain use: -```shell -security add-generic-password -s "PAT-foo-repo" -a "my-mac-user-name" -w -``` ### Work on an existing project in a Minimal sandbox -In this example we'll work on an existing git repo that already has minimal.toml +In this example we'll work on an existing git repo that already has minimal.toml where we have granted claude code access to our github repos. ```shell cd ~/projects/foo -# get latest files on current branch +# get latest files on current branch - we need the minimal.toml git pull -# copy a Github PAT to your clipboard -security find-generic-password -w -s "PAT-foo-repo" -a "my-mac-user-name" | pbcopy - # don't copy any files up we'll git pull in the sandbox min activate --attach --sync none . -read -sp "paste GH PAT now:" GH_TOKEN && export GH_TOKEN - -git pull https@github.com:.git - -claude --dangerously-skip-permissions -# add new features, fix bugs etc -git add -A -git commit -m "feat: add foozinator CLI option" -git push -u origin main +# tell claude to pull https@github.com:.git +# then add new features, fix bugs etc +# then ask claude to create PR +claude exit ``` ### Add a Minimal Loadout with your preferred tools and configurations -## Building and Testing +TBD -(To be updated) +## Building and Testing Either: `cargo build` for debug (faster build) and `cargo build --release` (slower build, faster execution) From caae2896f859bd0d1d2a52699a4d452fa601b6a8 Mon Sep 17 00:00:00 2001 From: msample <4896732+msample@users.noreply.github.com> Date: Fri, 17 Jul 2026 17:12:50 -0700 Subject: [PATCH 6/7] docs(README): rework, fix typos etc --- README.md | 128 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 83 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index 159cd38d51..afbf0e0f92 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,71 @@ # Minimal -Minimal provides VM-based development sandboxes and a secure package manager the for dev tools used in those sandboxes. +Minimal provides VM-based development sandboxes and a secure package manager for the dev tools used inside them. -# Features -Minimal can repeatably create a Linux, terminal-baseed development environment sandboxes populated with exactly the toolsets and agents you need as specified in your minimal.toml blueprint. - -The tool executables (compilers, agents, shells, etc.) available in these sandboxes come from Minimal's [curated package registry](https://github.com/gominimal/pkgs/) which is refreshed daily. Simply add a minimal.toml to your project's git repo and all your teammates will have identical development environemnts that isolate AI agents from their laptops. Updating the shared minimal.toml to reference the freshest tool versions is just a `min update` away. No more outdated wiki pages for dev-env setup and version drift across your team. - -Per-developer "Loadouts" can be included in each development environment so everyone can work efficiently by using the editors, terminal multiplexers and their configs that match their hard-earned muscle memory. +New here? Welcome! [Installation](#installation) and [Getting Started](#getting-started) will have you working in a sandbox in a few minutes, and we'd love to hear how it goes — questions and ideas are always welcome in [Discussions](https://github.com/gominimal/minimal/discussions). ## Contents +- [Features](#features) +- [Supported Platforms](#supported-platforms) +- [Installation](#installation) +- [Getting Started](#getting-started) + - [Create a new project with Minimal](#create-a-new-project-with-minimal) + - [Work on an existing project in a Minimal sandbox](#work-on-an-existing-project-in-a-minimal-sandbox) + - [Add a Minimal Loadout with your preferred tools and configurations](#add-a-minimal-loadout-with-your-preferred-tools-and-configurations) +- [Tech Stack](#tech-stack) +- [Documentation](#documentation) +- [Building and Testing](#building-and-testing) +- [Contributing](#contributing) + - [Contributor License Agreement](#contributor-license-agreement) +- [Code of Conduct](#code-of-conduct) +- [Security](#security) +- [License](#license) -## Tech Stack +## Features + +Minimal repeatably creates Linux, terminal-based development sandboxes populated with exactly the toolsets and agents you need, as specified in your `minimal.toml` blueprint. -Sandboxes: pure Rust client, daemon and VM manager. The sandbox VM is powered by [libkrun](https://github.com/libkrun/libkrun), a custom Linux kernel image and an Alpine Linux rootfs +The tool executables (compilers, agents, shells, etc.) available in these sandboxes come from Minimal's [curated package registry](https://github.com/gominimal/pkgs/), which is refreshed daily. Simply add a `minimal.toml` to your project's git repo and all your teammates will have identical development environments that isolate AI agents from their laptops. Updating the shared `minimal.toml` to reference the freshest tool versions is just a `min update` away. No more outdated wiki pages for dev-env setup, and no more version drift across your team. -[Packages](https://github.com/gominimal/pkgs/): glibc-based packages built frequently on Minimal's build servers from their cannonical sources (GNU, Github, Gitlab, etc.) +Per-developer [Loadouts](#add-a-minimal-loadout-with-your-preferred-tools-and-configurations) can be included in each development environment, so everyone can work efficiently using the editors, terminal multiplexers, and configs that match their hard-earned muscle memory. ## Supported Platforms Minimal works on: -- MacOS / ARM64 (Apple Silicon) -- Ubuntu and Debian Linux, ARM64 and X86_64, with a Linux kernel >= 5.10. Rootless user-namespace creation must be enabled for non-VM usage. + +- macOS on ARM64 (Apple Silicon) +- Ubuntu and Debian Linux on ARM64 and x86_64, with a Linux kernel >= 5.10. Rootless user-namespace creation must be enabled for non-VM usage. + +Not on one of these platforms yet? Tell us what you'd like to see supported in [Discussions](https://github.com/gominimal/minimal/discussions) — it helps us prioritize. ## Installation - To get started, install it with the following shell command (stable is coming soon): +To get started, install Minimal with the following shell command (a stable channel is coming soon): ```shell curl --proto "=https" --tlsv1.2 -fsSL 'https://go.minimal.dev/unstable' | sh ``` -This should install Minimal on your system, add "min" to your PATH, and setup shell completions for bash, fish, and zsh. +This installs Minimal on your system, adds `min` to your PATH, and sets up shell completions for bash, fish, and zsh. + +Minimal can be uninstalled with: -Minimal can be unistalled with: ```shell curl --proto "=https" --tlsv1.2 -fsSL 'https://go.minimal.dev/unstable' | sh -s -- --uninstall ``` ## Getting Started +The examples below walk through the two most common workflows: starting a brand-new project inside a sandbox, and joining an existing project that already has a `minimal.toml`. + ### Create a new project with Minimal -In this example we'll create a new git repo from within a Minimal sandbox using tools from the [Minimal Public Registry](https://github.com/gominimal/pkgs/). In this example we assume your claude code has been granted access to your git repos in order to push your changes there. +In this example we'll create a new git repo from within a Minimal sandbox, using tools from the [Minimal Public Registry](https://github.com/gominimal/pkgs/). It assumes Claude Code has been granted access to your GitHub repos (via the Claude GitHub App) so it can push changes on your behalf. ```shell mkdir -p ~/projects/foo -cd ~/projects/foo +cd ~/projects/foo # create and update a minimal.toml file min init @@ -58,27 +76,26 @@ min activate --attach . git init -# develop specs, generate & test code etc, push to git, etc -# agents can add sw tools from Minimal Public Registry dynamically with "min add" -claude-code +# develop specs, generate & test code, push to git, etc. +# agents can add tools from the Minimal Public Registry dynamically with "min add" +claude exit ``` -Above we show using Claude Code where you have trusted Claude Github App is Github on your behalf. Below we show using a Github personal access token (PAT) from the MacOS keychain. To create fine-grained PATs (e.g. scoped to a specific repo) go to https://github.com/settings/personal-access-tokens. - -Once you have created the PAT and copied it into your keychain (e.g. `security add-generic-password -s "PAT-foo-repo" -a "my-mac-user-name" -w`), and created the new, empty Github repo, the following example shows populating it the repo from within a sandbox. +Prefer not to install the Claude GitHub App? The next example uses a fine-grained GitHub personal access token (PAT) stored in the macOS keychain instead. To create a fine-grained PAT (e.g. scoped to a specific repo), go to . +Once you have created the PAT, copied it into your keychain (e.g. `security add-generic-password -s "PAT-foo-repo" -a "my-mac-user-name" -w`), and created the new, empty GitHub repo, the following shows how to populate that repo from within a sandbox: ```shell mkdir -p ~/projects/foo -cd ~/projects/foo +cd ~/projects/foo # create and update a minimal.toml file min init min add --session git gh claude-code mermaid-cli kittyview less emacs -# copy a Github PAT to your clipboard from your MacOS keychain +# copy the GitHub PAT to your clipboard from your macOS keychain security find-generic-password -w -s "PAT-foo-repo" -a "my-mac-user-name" | pbcopy # start and enter a sandbox, which copies up the CWD file tree into the sandbox @@ -89,37 +106,34 @@ read -sp "paste GH PAT now:" GH_TOKEN && export GH_TOKEN git init claude --dangerously-skip-permissions -# develop specs, generate code etc +# develop specs, generate code, etc. git add -A git commit -m "initial checkin" -git remote add origin https@github.com:.git +git remote add origin https://github.com//.git git branch -M main git push -u origin main exit - ``` - ### Work on an existing project in a Minimal sandbox -In this example we'll work on an existing git repo that already has minimal.toml where we have granted claude code access to our github repos. +In this example we'll work on an existing git repo that already has a `minimal.toml`, where Claude Code has been granted access to our GitHub repos. ```shell -cd ~/projects/foo +cd ~/projects/foo -# get latest files on current branch - we need the minimal.toml +# get the latest files on the current branch - we need the minimal.toml git pull -# don't copy any files up we'll git pull in the sandbox +# don't copy any files up; we'll git pull inside the sandbox min activate --attach --sync none . - -# tell claude to pull https@github.com:.git -# then add new features, fix bugs etc -# then ask claude to create PR +# tell claude to pull https://github.com//.git +# then add new features, fix bugs, etc. +# then ask claude to create a PR claude exit @@ -129,9 +143,29 @@ exit TBD +## Tech Stack + +Sandboxes: a pure Rust client, daemon, and VM manager. The sandbox VM is powered by [libkrun](https://github.com/libkrun/libkrun), a custom Linux kernel image, and an Alpine Linux rootfs. + +[Packages](https://github.com/gominimal/pkgs/): glibc-based packages built frequently on Minimal's build servers from their canonical sources (GNU, GitHub, GitLab, etc.). + +## Documentation + +- [Architecture overview](docs/architecture.md) — how the crates fit together +- [CLI reference](docs/reference/cli.md) — every `min` command +- [`minimal.toml` reference](docs/reference/minimal-dot-toml.md) — the project blueprint format +- [Linux host setup](docs/reference/linux-host-setup.md) — kernel and namespace requirements +- More guides live in [docs/](docs/) + ## Building and Testing -Either: `cargo build` for debug (faster build) and `cargo build --release` (slower build, faster execution) +Minimal is a Rust workspace. From a checkout: + +```shell +cargo build # debug build (faster to build) +cargo build --release # optimized build (slower to build, faster to run) +cargo test # run the test suite +``` ### Ubuntu 24.04+ hosts @@ -151,13 +185,11 @@ loader and prints a hint when the host needs it; run See [docs/reference/linux-host-setup.md](docs/reference/linux-host-setup.md). - ## Contributing -We'd love your help! Please [open an Issue](https://github.com/gominimal/minimal/issues/new/choose) (or a [Discussion](https://github.com/gominimal/minimal/discussions/new/choose)( if it's large in scope) to outline the improvments you're seeking - -If you want to contribute code, docs, etc please head over to [CONTRIBUTING.md](./CONTRIBUTING.md) for the development workflow and what we look for in a contribution. +We'd love your help, and you don't need to be a Rust expert to pitch in — bug reports, docs fixes, and feature ideas are all valued contributions. Please [open an Issue](https://github.com/gominimal/minimal/issues/new/choose) (or start a [Discussion](https://github.com/gominimal/minimal/discussions/new/choose) if it's large in scope) to outline the improvements you're seeking. +If you want to contribute code, docs, etc., please head over to [CONTRIBUTING.md](./CONTRIBUTING.md) for the development workflow and what we look for in a contribution. ### Contributor License Agreement @@ -167,8 +199,14 @@ If you're contributing on your employer's time, or with code your employer might Full text: [ICLA](./legal/ICLA.md) · [CCLA](./legal/CCLA.md) -## License +## Code of Conduct + +We want everyone to feel welcome here, whatever your background or experience level. This project follows the [Contributor Covenant](./CODE_OF_CONDUCT.md); by participating — contributing code, filing issues, or joining discussions — you agree to uphold it. -This project is licensed under the [Apache License Version 2.0](LICENSE) -- see the [LICENSE](LICENSE) file for details. +## Security + +If you believe you've found a security vulnerability, please email **security@minimal.dev** instead of opening a public issue. We appreciate responsible disclosure and will get back to you quickly. + +## License +This project is licensed under the [Apache License Version 2.0](LICENSE) — see the [LICENSE](LICENSE) file for details. From 5b849756eb3f930ed9f80c7d25334cc1ba072283 Mon Sep 17 00:00:00 2001 From: msample <4896732+msample@users.noreply.github.com> Date: Sun, 19 Jul 2026 08:45:19 -0700 Subject: [PATCH 7/7] docs(README): updated PAT exaple to be more secure - late credential injection --- README.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index afbf0e0f92..6a87a9e3cd 100644 --- a/README.md +++ b/README.md @@ -101,16 +101,19 @@ security find-generic-password -w -s "PAT-foo-repo" -a "my-mac-user-name" | pbco # start and enter a sandbox, which copies up the CWD file tree into the sandbox min activate --attach . -read -sp "paste GH PAT now:" GH_TOKEN && export GH_TOKEN - git init -claude --dangerously-skip-permissions # develop specs, generate code, etc. +claude --dangerously-skip-permissions +# review the generated code first git add -A git commit -m "initial checkin" +# add GH credential after AI Agents are terminated +read -sp "paste GH PAT now:" GH_TOKEN && export GH_TOKEN + +# push to github git remote add origin https://github.com//.git git branch -M main git push -u origin main