brr-cli 0.1.0__tar.gz

brr_cli-0.1.0/.brr/aws/cluster.yaml

@@ -0,0 +1,50 @@
+cluster_name: brr-cluster
+max_workers: 4
+
+provider:
+  type: aws
+  region: us-east-1
+  availability_zone: us-east-1a, us-east-1b, us-east-1c, us-east-1d
+  cache_stopped_nodes: True
+
+auth:
+  ssh_user: ubuntu
+  ssh_private_key: {{AWS_SSH_KEY}}
+
+head_node_type: ray.head.default
+
+available_node_types:
+  ray.head.default:
+    resources: {}
+    node_config:
+      InstanceType: t3.2xlarge
+      ImageId: {{AMI_UBUNTU}}
+      KeyName: {{AWS_KEY_NAME}}
+      SecurityGroupIds: ["{{AWS_SECURITY_GROUP}}"]
+      BlockDeviceMappings:
+        - DeviceName: /dev/sda1
+          Ebs:
+            VolumeSize: 100
+            VolumeType: gp3
+  ray.worker.default:
+    min_workers: 0
+    max_workers: 4
+    resources: {}
+    node_config:
+      InstanceType: g6.4xlarge
+      ImageId: {{AMI_DL}}
+      KeyName: {{AWS_KEY_NAME}}
+      SecurityGroupIds: ["{{AWS_SECURITY_GROUP}}"]
+      BlockDeviceMappings:
+        - DeviceName: /dev/sda1
+          Ebs:
+            VolumeSize: 200
+            VolumeType: gp3
+
+head_start_ray_commands:
+  - source $HOME/.venv/bin/activate && ray stop
+  - source $HOME/.venv/bin/activate && ray start --head --port=6379 --object-manager-port=8076 --autoscaling-config=~/ray_bootstrap_config.yaml --dashboard-host=0.0.0.0
+
+worker_start_ray_commands:
+  - source $HOME/.venv/bin/activate && ray stop
+  - source $HOME/.venv/bin/activate && ray start --address=$RAY_HEAD_IP:6379 --object-manager-port=8076

brr_cli-0.1.0/.brr/aws/dev.yaml

@@ -0,0 +1,36 @@
+cluster_name: brr-dev
+max_workers: 0
+
+provider:
+  type: aws
+  region: us-east-1
+  availability_zone: us-east-1a, us-east-1b, us-east-1c, us-east-1d
+  cache_stopped_nodes: True # If not present, the default is True.
+
+auth:
+  ssh_user: ubuntu
+  ssh_private_key: {{AWS_SSH_KEY}}
+
+head_node_type: ray.head.default
+
+available_node_types:
+  ray.head.default:
+    resources: {}
+    node_config:
+      InstanceType: gr6.4xlarge # L4 GPU https://aws.amazon.com/ec2/instance-types/g6/
+      ImageId: {{AMI_DL}}
+      KeyName: {{AWS_KEY_NAME}}
+      SecurityGroupIds: ["{{AWS_SECURITY_GROUP}}"]
+      BlockDeviceMappings:
+        - DeviceName: /dev/sda1
+          Ebs:
+            VolumeSize: 200
+            VolumeType: gp3
+
+head_start_ray_commands:
+    - source $HOME/.venv/bin/activate && ray stop
+    - source $HOME/.venv/bin/activate && ray start --head --port=6379 --object-manager-port=8076 --autoscaling-config=~/ray_bootstrap_config.yaml --dashboard-host=0.0.0.0
+
+worker_start_ray_commands:
+    - source $HOME/.venv/bin/activate && ray stop
+    - source $HOME/.venv/bin/activate && ray start --address=$RAY_HEAD_IP:6379 --object-manager-port=8076

brr_cli-0.1.0/.brr/aws/setup.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+# Project setup — runs after global setup on every node boot.
+set -Eeuo pipefail
+
+# Sync project dependencies (uses locked versions from uv.lock)
+if [ -d "$HOME/code/brr" ]; then
+  cd "$HOME/code/brr"
+  # Pre-fetch the Python version required by the project so uv sync doesn't hang.
+  uv python install
+  uv sync --group brr
+fi
+
+# Add extra project-specific dependencies below:
+# uv pip install torch

brr_cli-0.1.0/.brr/config.env

@@ -0,0 +1,6 @@
+# Project config — overrides ~/.brr/config.env for this project.
+# Uncomment and edit values as needed.
+
+# IDLE_SHUTDOWN_TIMEOUT_MIN="20"
+# DOTFILES_REPO="https://github.com/user/dotfiles"
+# PYTHON_VERSION="3.11"

brr_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,17 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

brr_cli-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.claude
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+build/
+.DS_Store

brr_cli-0.1.0/CLAUDE.md

@@ -0,0 +1,89 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Setup
+
+```bash
+# Install dependencies (uses uv + hatchling)
+uv sync
+
+# Install CLI in editable mode
+uv tool install --editable .
+
+# Run the CLI
+brr --help
+```
+
+There are no tests, linters, or CI pipelines configured.
+
+## Architecture
+
+brr is a CLI for managing GPU/CPU compute clusters across AWS and Nebius. It uses Click for commands, Rich for terminal output, InquirerPy for interactive prompts, PyYAML for config templating, and Ray for cluster orchestration.
+
+### Command Flow
+
+All cluster commands (`up`, `down`, `attach`, `list`, `clean`, `vscode`) live in `brr/cluster.py` and follow this pattern:
+
+1. **Provider parsing** — `state.py:parse_provider()` splits `provider:name` syntax (e.g. `nebius:h100`). Default provider is `aws`.
+2. **Config loading** — `state.py:read_merged_config()` layers: `CONFIG_DEFAULTS` → `~/.brr/config.env` → `.brr/config.env` (project).
+3. **Template resolution** — `templates.py:resolve_template()` finds a YAML: project templates (`.brr/{provider}/{name}.yaml`) take precedence when inside a project; explicit `provider:name` prefix bypasses project and uses built-in (`brr/{provider}/templates/{name}.yaml`).
+4. **Rendering** — `{{VAR}}` placeholders replaced with config values; `???` marks required fields that must be overridden.
+5. **Overrides** — CLI args like `instance_type=t3.xlarge` applied via alias system (`_brr` YAML section), `GLOBAL_ARGS` mapping, or raw dot-notation paths.
+6. **Staging** — `prepare_staging()` writes setup scripts and config to `~/.brr/staging/{name}/`, then `inject_brr_infra()` adds file_mounts and setup_commands to the Ray YAML.
+7. **Execution** — `ray up`/`ray down` called via subprocess.
+8. **SSH config sync** — `nodes.py:update_ssh_config()` writes `brr-{cluster}` host entries to `~/.ssh/config`.
+
+### Project System
+
+Projects are repos with a `.brr/` directory (created by `brr init`):
+
+```
+.brr/
+  aws/dev.yaml         # Project template (standard Ray YAML)
+  aws/cluster.yaml
+  aws/setup.sh         # Runs after global setup on every node
+  config.env           # Overrides ~/.brr/config.env
+```
+
+Key behaviors:
+- `state.py:find_project_root()` walks up from CWD looking for `.brr/` with YAML files (skips `~/.brr`).
+- `resolve_project_provider()` infers provider from project: single provider → automatic; multiple → requires `DEFAULT_PROVIDER` or explicit prefix.
+- Setup layering: global `~/.brr/setup.sh` runs first, then project `.brr/{provider}/setup.sh`.
+- uv-managed projects: `templates.py:rewrite_ray_commands_for_uv()` replaces venv activation with `uv run --group brr` in Ray start commands.
+
+### Key Modules
+
+- **`brr/cli.py`** — Click command group, version from `importlib.metadata`.
+- **`brr/cluster.py`** — Cluster lifecycle. Uses `_find_ray()` to locate the Ray binary and `_run_ray()` to exec it.
+- **`brr/state.py`** — Config parsing (`read_config`/`write_config`), state dirs, project discovery, provider checks.
+- **`brr/templates.py`** — Template resolution, rendering, override system, staging, baked image substitution.
+- **`brr/commands/init.py`** — `brr init` scaffolds `.brr/{provider}/` with templates + setup.sh. Maps project template names to built-in ones (`_TEMPLATE_MAP`).
+- **`brr/commands/configure.py`** — Interactive wizard: cloud provider, AI tools, general settings. Uses InquirerPy for menus.
+- **`brr/commands/bake.py`** — Pre-bakes global setup into AMIs/images. Strips secrets (`_BAKE_STRIP_KEYS`) before baking. Tracks staleness via setup.sh hash.
+- **`brr/commands/nuke.py`** — Destructive teardown. Multi-region parallel cleanup with ThreadPoolExecutor (AWS) or async SDK (Nebius).
+- **`brr/data/setup.sh`** — Node bootstrap: mounts, AWS CLI, GitHub SSH keys, AI tools, Python venv, Ray, idle shutdown daemon.
+- **`brr/data/idle-shutdown.sh`** — Systemd daemon monitoring CPU/GPU/SSH activity.
+
+#### AWS
+
+- **`brr/aws/configure.py`** — Creates key pairs, security groups, EFS, stores secrets in Secrets Manager.
+- **`brr/aws/nodes.py`** — EC2 queries (`query_ray_clusters`), SSH config management.
+- **`brr/aws/templates/`** — Ray YAML templates: `cpu.yaml`, `l4.yaml`, `h100.yaml`, `cpu-l4.yaml`.
+
+#### Nebius
+
+- **`brr/nebius/configure.py`** — Project selection, subnet, SSH keys, shared filesystem, GitHub SSH.
+- **`brr/nebius/nodes.py`** — Instance queries (`query_clusters`, `query_head_ip`), SSH config management.
+- **`brr/nebius/node_provider.py`** — Custom Ray NodeProvider for autoscaling. Stop-instead-of-delete for cached nodes. Restarts stopped instances before creating new ones.
+- **`brr/nebius/templates/`** — Ray YAML templates: `cpu.yaml`, `h100.yaml`, `cpu-h100.yaml`.
+
+### Known Pitfalls
+
+- `textwrap.dedent` with f-strings breaks when interpolated values have different indentation. Build shell scripts as concatenated string parts instead.
+- `config.env` keys can contain digits (e.g. `EC2_SSH_SECRET`), so the parsing regex must be `[A-Z0-9_]+`.
+- Nebius `recovery_policy` is immutable after instance creation — must use `InstanceRecoveryPolicy.FAIL` to prevent auto-restart after idle shutdown.
+- Nebius instance state 8 is ERROR (not DELETED) — `_TERMINAL_STATES` must include it.
+- External providers (Nebius) need explicit `resources: {CPU: N}` in Ray YAML templates — Ray can't auto-detect.
+- Unresolved `{{VAR}}` placeholders in provider config must be guarded (e.g. `"{{" in value` check in node_provider).
+- InquirerPy `Choice` class doesn't have a `disabled` parameter. Use dict syntax `{"value": ..., "name": ..., "disabled": "reason"}` for disabled items.

brr_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jon Carter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

brr_cli-0.1.0/PKG-INFO

@@ -0,0 +1,287 @@
+Metadata-Version: 2.4
+Name: brr-cli
+Version: 0.1.0
+Summary: Research infrastructure management tooling.
+Project-URL: Homepage, https://github.com/joncarter1/brr
+Project-URL: Repository, https://github.com/joncarter1/brr
+Project-URL: Issues, https://github.com/joncarter1/brr/issues
+Author: Jon Carter
+License-Expression: MIT
+License-File: LICENSE
+Keywords: aws,cloud,cluster,gpu,infrastructure,ray
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Clustering
+Requires-Python: >=3.11
+Requires-Dist: click
+Requires-Dist: inquirerpy
+Requires-Dist: pyyaml
+Requires-Dist: rich
+Provides-Extra: aws
+Requires-Dist: boto3; extra == 'aws'
+Requires-Dist: ray[default]; extra == 'aws'
+Provides-Extra: nebius
+Requires-Dist: nebius; extra == 'nebius'
+Requires-Dist: ray[default]; extra == 'nebius'
+Description-Content-Type: text/markdown
+
+# ❄️ brr ❄️
+
+Opinionated research infrastructure tooling. Launch clusters, get SSH access, start building.
+
+## Features
+- **Shared filesystem** — All nodes share `~/code/` via EFS (AWS) or virtiofs (Nebius).
+- **Coding tools** — Install Claude Code, Codex, or Gemini. Connect with e.g. `brr attach dev claude`
+- **Autoscaling** — Ray-based cluster scaling with cached instances.
+- **Project-based workflows** — Per-repo cluster configs and project-specific dependencies.
+- **Auto-shutdown** — Monitors CPU, GPU, and SSH activity. Shuts down idle instances to save costs.
+- **Dotfiles integration** — Take your dev environment (vim, tmux, shell config) to every cluster node via GNU Stow.
+
+## Prerequisites
+
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/) (for installation)
+
+## Quick Start
+
+```sh
+# Install (AWS only)
+uv tool install brr-cli[aws]
+
+# Install (both providers)
+# uv tool install brr-cli[aws,nebius] 
+
+# Configure (interactive wizard)
+brr configure      # or: brr configure nebius
+
+# Launch an H100
+brr up aws:h100
+
+# brr up nebius:h100
+
+# Connect
+brr attach aws:h100              # SSH
+brr attach aws:h100 claude       # Claude Code on the cluster
+brr vscode aws:h100              # VS Code remote
+```
+
+Built-in templates use `provider:name` syntax (e.g. `aws:h100`). Inside a [project](#projects), short names like `brr up dev` work automatically.
+
+Supported clouds: [AWS](#aws-setup) · [Nebius](#nebius-setup)
+
+## Projects
+
+For per-repo cluster configs, initialize a project:
+
+```sh
+cd my-research-repo/
+brr init
+```
+
+This creates:
+
+```
+.brr/
+  aws/
+    dev.yaml        # Single GPU for development
+    cluster.yaml    # CPU head + GPU workers
+    setup.sh        # Project-specific dependencies
+  config.env        # Project config (overrides global)
+```
+
+Templates are standard Ray YAML — edit them or add your own. Inside a project, use short names:
+
+```sh
+brr up                  # launches DEFAULT_TEMPLATE (set in .brr/config.env)
+brr up dev              # launches .brr/aws/dev.yaml
+brr up cluster          # launches .brr/aws/cluster.yaml
+brr attach dev          # SSH into dev cluster
+brr down dev            # tear down
+```
+
+If your project uses `uv`, `brr init` automatically adds `brr-cli` and `ray` to a `brr` dependency group. The cluster uses your project-locked versions — no manual setup needed.
+
+Project config (`.brr/config.env`) overrides global settings (`~/.brr/config.env`). Use it for project-specific settings like idle timeouts or dotfiles.
+
+## Templates
+
+### Built-in templates
+
+| Template | Instance | GPU | Workers |
+| :--- | :--- | :--- | :--- |
+| `aws:cpu` | t3.2xlarge | — | 0-2 |
+| `aws:l4` | gr6.4xlarge | 1x L4 | — |
+| `aws:h100` | p5.4xlarge | 8x H100 | — |
+| `aws:cpu-l4` | t3.2xlarge + g6.4xlarge | 1x L4 | 0-4 |
+| `nebius:cpu` | 8vcpu-32gb | — | 0-2 |
+| `nebius:h100` | 1gpu-16vcpu-200gb | 1x H100 | — |
+| `nebius:cpu-h100` | 8vcpu-32gb + 8gpu-128vcpu-1600gb | 8x H100 | 0-4 |
+
+### Overrides
+
+Override template values inline:
+
+```sh
+brr up aws:cpu instance_type=t3.xlarge max_workers=4
+brr up aws:h100 spot=true
+brr up dev region=us-west-2
+```
+
+Preview the rendered config without launching:
+
+```sh
+brr up dev --dry-run
+```
+
+See available overrides for a template:
+
+```sh
+brr templates show dev
+```
+
+### Multi-provider
+
+Use the provider prefix for built-in templates:
+
+```sh
+brr up aws:h100
+brr up nebius:h100
+brr attach nebius:h100
+brr down nebius:h100
+```
+
+Both providers can run simultaneously.
+
+## Customization
+
+### Node setup
+
+`~/.brr/setup.sh` runs on every node boot. It installs packages, mounts shared storage, sets up Python/Ray, GitHub SSH keys, AI coding tools, dotfiles, and the idle shutdown daemon.
+
+Edit it to customize:
+```sh
+vim ~/.brr/setup.sh
+```
+
+Project-specific dependencies go in `.brr/{provider}/setup.sh` (created by `brr init`), which runs after the global setup.
+
+### AI coding tools
+
+Install AI coding assistants on every cluster node:
+
+```sh
+brr configure tools    # select Claude Code, Codex, and/or Gemini CLI
+```
+
+Then connect and start coding:
+
+```sh
+brr attach dev claude
+```
+
+### Dotfiles
+
+Set a dotfiles repo to sync your dev environment to every node:
+
+```sh
+brr config set DOTFILES_REPO "https://github.com/user/dotfiles"
+```
+
+The repo is cloned to `~/dotfiles` and installed via `install.sh` (if present) or GNU Stow.
+
+### Image baking
+
+Bake the global setup into AMIs/images for fast boot:
+
+```sh
+brr bake aws          # bake both CPU + GPU AMIs
+brr bake status       # check if baked images are up to date
+```
+
+After baking, clusters boot from the pre-built image. Only project-specific deps need to install. `brr up` warns when `setup.sh` has changed since the last bake.
+
+### Idle shutdown
+
+A systemd daemon monitors CPU, GPU, and SSH activity. When all signals are idle for the configured timeout, the instance shuts down.
+
+Configure in `~/.brr/config.env`:
+
+```
+IDLE_SHUTDOWN_ENABLED="true"
+IDLE_SHUTDOWN_TIMEOUT_MIN="30"
+IDLE_SHUTDOWN_CPU_THRESHOLD="10"
+IDLE_SHUTDOWN_GRACE_MIN="15"
+```
+
+The grace period prevents shutdown during initial setup. Monitor on a node with `journalctl -u idle-shutdown -f`.
+
+## Commands
+
+| Command | Description |
+| :--- | :--- |
+| `brr up TEMPLATE [OVERRIDES...]` | Launch or update a cluster (`aws:h100`, `dev`, or `path.yaml`) |
+| `brr up TEMPLATE --dry-run` | Preview rendered config without launching |
+| `brr down TEMPLATE` | Stop a cluster (instances preserved for fast restart) |
+| `brr down TEMPLATE --delete` | Terminate all instances and remove staging files |
+| `brr attach TEMPLATE [COMMAND]` | SSH into head node, optionally run a command (e.g. `claude`) |
+| `brr list [--all]` | List clusters (project-scoped by default, `--all` for everything) |
+| `brr clean [TEMPLATE]` | Terminate stopped (cached) instances |
+| `brr vscode TEMPLATE` | Open VS Code on a running cluster |
+| `brr templates list` | List built-in templates |
+| `brr templates show TEMPLATE` | Show template config and overrides |
+| `brr init` | Initialize a project (interactive provider selection) |
+| `brr configure [cloud\|tools\|general]` | Interactive setup (cloud provider, AI tools, settings) |
+| `brr config [list\|get\|set\|path]` | View and manage configuration |
+| `brr bake [aws\|nebius]` | Bake setup into cloud images |
+| `brr bake status` | Check if baked images are up to date |
+| `brr completion [bash\|zsh\|fish]` | Shell completion (`--install` to add to shell rc) |
+| `brr nuke [aws\|nebius]` | Tear down all cloud resources |
+
+## Cloud Setup
+
+### AWS Setup
+
+1. Attach the [IAM policy](brr/aws/iam-policy.json) to your IAM user
+2. Install the [AWS CLI](https://aws.amazon.com/cli/) and run `aws configure`
+3. *(Optional)* For GitHub SSH access on clusters, authenticate the [GitHub CLI](https://cli.github.com/):
+   ```sh
+   gh auth login
+   gh auth refresh -h github.com -s admin:public_key
+   ```
+4. Run the setup wizard:
+   ```sh
+   brr configure aws
+   ```
+
+### Nebius Setup
+
+1. Install the [Nebius CLI](https://docs.nebius.com/cli/install) and run `nebius init`
+2. Create a service account with editor permissions:
+   ```sh
+   TENANT_ID="<your-tenant-id>"  # from console.nebius.com → Administration
+
+   SA_ID=$(nebius iam service-account create \
+     --name brr-cluster --format json | jq -r '.metadata.id')
+
+   EDITORS_GROUP_ID=$(nebius iam group get-by-name \
+     --name editors --parent-id $TENANT_ID --format json | jq -r '.metadata.id')
+
+   nebius iam group-membership create \
+     --parent-id $EDITORS_GROUP_ID --member-id $SA_ID
+   ```
+3. Generate credentials:
+   ```sh
+   mkdir -p ~/.nebius
+   nebius iam auth-public-key generate \
+     --service-account-id $SA_ID --output ~/.nebius/credentials.json
+   ```
+4. Run the setup wizard:
+   ```sh
+   brr configure nebius
+   ```
+
+## Acknowledgments
+
+This project started as a fork of [aws_wiz](https://github.com/besarthoxhaj/aws_wiz) by [Bes](https://github.com/besarthoxhaj) and has been inspired by discussions with colleagues from the [Encode: AI for Science Fellowship](https://encode.pillar.vc/).