clouddeck 0.1.0__tar.gz

clouddeck-0.1.0/.env.example

@@ -0,0 +1,56 @@
+# CloudDeck / ddc: the name of every setting that comes from a file or from the environment. Placeholders only; never commit real values.
+#
+# CloudDeck does NOT read a ".env" file. This file only documents the names:
+#   * Part 1 lists the keys of secrets.env (same KEY=value syntax). `ddc init` creates the real file for you, owner-only
+#     (mode 0600 on Linux/macOS), in the secrets directory (default ~/.config/clouddeck/, see Part 2).
+#   * Part 2 lists process environment variables (all optional, all commented out here) that move files or change behaviour.
+# Everything else (limits, repos, profiles) lives in config.toml: see config.example.toml.
+
+# ---------------------------------------------------------------------------------------------------------------------------------
+# Part 1: keys of secrets.env (read from that FILE only, never from the process environment)
+# ---------------------------------------------------------------------------------------------------------------------------------
+
+# Akash Console API key (https://console.akash.network, API Keys). Required. It can spend your Akash balance: use a dedicated,
+# low-balance account. It stays on this PC and is never sent to any rented box.
+AKASH_API_KEY=
+
+# Passphrase that encrypts checkpoints (gpg AES256). `ddc install` generates it if missing. It IS copied to the dev box so that the
+# box can encrypt checkpoints. Keep a copy in a password manager: if it is lost, every checkpoint is unrecoverable.
+DDC_BACKUP_PASSPHRASE=
+
+# Optional. Claude Code login token for the dev box. Only sent when `push_claude_credentials = true` in config.toml (default: false).
+CLAUDE_CODE_OAUTH_TOKEN=
+
+# ---------------------------------------------------------------------------------------------------------------------------------
+# Part 2: process environment variables (all optional)
+# ---------------------------------------------------------------------------------------------------------------------------------
+
+# Where things live. Defaults: config in %APPDATA%\clouddeck (Windows) or ~/.config/clouddeck (Linux, macOS, WSL; honours
+# XDG_CONFIG_HOME); secrets in ~/.config/clouddeck; state in %LOCALAPPDATA%\clouddeck (Windows) or ~/.local/state/clouddeck
+# (honours XDG_STATE_HOME). DDC_CONFIG is a file path, the other two are directories.
+# DDC_CONFIG=/path/to/config.toml
+# DDC_SECRETS_DIR=/path/to/secrets-dir
+# DDC_STATE_DIR=/path/to/state-dir
+
+# Path of the gpg binary (default: gpg on PATH; on Windows also the gpg bundled with Git for Windows).
+# DDC_GPG=/path/to/gpg
+
+# Akash Console API base URL (default https://console-api.akash.network). Only change it to point at a test double.
+# DDC_AKASH_API=https://console-api.akash.network
+
+# CloudDeck: akash (default), demo (simulated, touches nothing) or a plugin name; the same as `clouddeck -p NAME`.
+# CLOUDDECK_PROVIDER=demo
+# CloudDeck: any non-empty value shows full tracebacks instead of a one-line error.
+# CLOUDDECK_DEBUG=1
+
+# `clouddeck-remote`, the client that `clouddeck serve --tunnel` installs on the dev box (set these on the BOX, not on your PC).
+# URL default: http://127.0.0.1:8765 (the end of the SSH reverse tunnel). Token default: the file ~/.config/clouddeck/token
+# that `clouddeck serve --tunnel` pushed.
+# CLOUDDECK_URL=http://127.0.0.1:8765
+# CLOUDDECK_TOKEN=cdk_example
+
+# Test seams, used by the test suite and the simulated provider. Do not set these in normal use.
+# DDC_STATE_URL=            git URL used to verify checkpoints
+# DDC_STATE_REMOTE=         state repo URL on the lease
+# CLOUDDECK_DEMO_LATENCY=0  seconds of fake latency in the demo provider
+# CLOUDDECK_DEMO_SSH_FAIL=1 make the demo provider's interactive ssh fail

clouddeck-0.1.0/.gitleaks.toml

@@ -0,0 +1,27 @@
+title = "CloudDeck gitleaks config"
+
+# Start from gitleaks' built-in rules (GitHub/AWS/GCP tokens, private keys, generic API keys, ...) and add project-specific ones.
+[extend]
+useDefault = true
+
+[[rules]]
+id = "akash-api-key-assignment"
+description = "Akash console API key assigned a real-looking value"
+regex = '''(?i)AKASH_API_KEY["']?\s*[=:]\s*["']?[A-Za-z0-9._\-]{16,}'''
+keywords = ["akash_api_key"]
+
+[rules.allowlist]
+description = "placeholders and obviously fake values"
+regexes = ['''(?i)(your|xxx|example|placeholder|changeme|redacted|dummy|fake|sample|test|\$\{)''']
+
+[[rules]]
+id = "akash-address"
+description = "Akash account address (identifies the owner's wallet; not a secret, but must not ship in examples)"
+regex = '''\bakash1[0-9a-z]{38}\b'''
+keywords = ["akash1"]
+
+# No broad allowlist. The one entry below is a verified false positive: the fixture is a trimmed capture of Akash's public provider
+# listing, whose attribute keys (capabilities/gpu/vendor/nvidia/<model>, ...) look like generic API keys. It holds no credentials.
+[allowlist]
+description = "public Akash provider attribute keys in the hardware test fixture"
+paths = ['''^tests/fixtures/hardware/providers_sample\.json$''']

clouddeck-0.1.0/CHANGELOG.md

@@ -0,0 +1,90 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and the project uses [Semantic Versioning](https://semver.org/); while the version is `0.x`, minor releases may change behaviour and say so here.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-18
+
+First public release (alpha).
+
+### Added
+
+* **`ddc`, the controller** (`ddc init`, `install`, `uninstall`, `start`, `attach`, `scale`, `status`, `bench`, `checkpoint`, `verify`,
+  `stop`, `heal`, `reconcile`, `watchdog`, `ssh`, `run`): provisions a dev box and disposable workers on Akash through the Console API
+  (create, bids, lease, close), with a price cap and `runtimeLimitHours` in every order.
+* **`clouddeck`, a terminal UI** with five tabs (Compute, Workers, Projects, Monitor, Recovery), a command palette, a provider catalogue
+  and GPU market view, live utilisation and spend, typed confirmations for destructive actions, a summary-line warning when the Akash API is
+  unreachable (the last known data stays on screen), and a simulated provider (`-p demo`).
+  Also `clouddeck status`, `doctor`, `providers`, `install`, `serve` and `remote`.
+* **Hardware picker** (`h` on the Compute tab): choose any CPU architecture or GPU vendor, model, memory variant and interface in any count,
+  a region, audited providers only or pinned providers, from lists built from Akash's public data at run time (nothing is hard-coded, offline
+  falls back to the last saved list), with advertised, screened and confirmed availability kept apart. Needs no new limit: price cap and
+  runtime limit still go into every order, and `max_price_usd_hr` (default 2.0, at most 100) is the explicit ceiling for one price cap.
+* **Encrypted checkpoints** (gpg AES256, split into 45 MiB parts) in a private GitHub repository you own, taken periodically and before
+  every stop, verified on the PC (part hashes, decryption, entry counts, git HEADs), restored on the next start.
+* **Spending protection:** budget and reserve guard (on by default: $25 / $5), lease and worker caps, hard ceilings that hold with the guard off
+  (8 leases, 7 workers, $2.00/h price cap per profile by default, 24 h, 8 per call), `unsafe_disable_limits` as the only override, worst-case accounting that counts
+  creations whose outcome is unknown, and a lifetime ledger.
+* **Watchdog** registered by `ddc install` (Windows scheduled task, Linux and WSL systemd user timer or cron): idle shutdown of the dev box
+  and workers, runtime and budget enforcement, cleanup of leases that never became ready, alerts (desktop notification, `alert_command`, log).
+* **Ownership safety:** only leases recorded in `state.json` and named `ddc-*` (and owned by your account) can be closed; other
+  deployments are read-only.
+* **Failure handling:** atomic state and ledger writes with a backup, damaged state or ledger blocks new leases but never blocks status or stop,
+  create requests are sent once and reconciled when the outcome is unknown, `ddc reconcile` repairs and adopts.
+* **Remote controller API** for a terminal on the dev box: loopback only, SSH reverse tunnel, `read` / `fleet` / `admin` scopes, expiring
+  hashed tokens, rate and size limits, audit log.
+* **Lease scripts** for the box (checkpoint, restore, activity agent, benchmark, worker fan-out) that fail safe: restore verifies before it
+  renames, checkpoints refuse truncated workspaces, foreign repositories and second writers, and pushes are atomic and lease-checked.
+* **Configuration** with validated, safe defaults (`config.example.toml`), custom hardware profiles, projects, named environments, reusable
+  workloads, an optional pinned Claude Code install (`install_claude_code`) and opt-in credential push (`push_claude_credentials`, off by default).
+* **Provider plugin contract** (`clouddeck.providers` entry points) with a mandatory spend-guard seam.
+* **`ddc job`** (also `python -m clouddeck.job`): a generic runner for batch workloads on one short-lived lease (role `job`) with minimal paid
+  idle time: preflight, bid early / lease late, parallel local preparation, resumable detached steps, sha256-verified transfers, verified
+  close, per-phase telemetry. Docs: [docs/JOBS.md](docs/JOBS.md), a prebuilt-image guide, examples under `examples/` (in the repository and the
+  sdist, not in the wheel), a toolchain `docker/Dockerfile`, and an old-vs-new simulation (assumed, synthetic inputs) in the test suite.
+  Safety rules: artifact retrieval is capped (`max_artifact_gb`) and bound by the job's own cost and wall-clock limits, ssh host keys are kept
+  per lease, `env.secrets` refuses `AKASH_*` / `DDC_*`, downloads need a sha256 (or an explicit `allow_unverified`) and an http(s) URL, the GPU
+  vendor must be named, one run per job name, and a signal during the close never aborts it.
+* **One creation path for every lease.** `check_budget` is now a thin wrapper around `check_spend(label, n, hours, cap_usd_hr, role)`, and
+  `launch_lease` (write-ahead record, one create request, promotion) is used by both `create_box` and `ddc job`: job leases are subject to
+  the lease caps, the hard ceilings (including the per-lease price cap), the budget guard and the unknown-outcome handling like any other lease.
+  Behaviour and messages of the existing commands are unchanged.
+* **Orphaned job protection:** the runner records a heartbeat; `ddc watchdog` closes an owned job lease whose runner has been silent for
+  `job_orphan_minutes` (new optional config key, default 30) or that is past its own deadline, and alerts. The budget stop closes job leases
+  too. `ddc status`, `ddc stop`, `ddc reconcile` and the TUI handle role `job` (not resizable from the TUI). A plain `ddc stop` (and the TUI's
+  stop-everything) also closes owned job leases, as the user's kill switch; `--only` / `--workers-only` and the watchdog's idle stop keep their
+  narrower meaning. `job_orphan_minutes` has a floor of 10.
+* `ssh_args` takes an optional `known_hosts` path (default unchanged); `close_box` no longer books a lease that another process already
+  recorded as closed.
+* Documentation: quickstart, architecture, costs and safety, checkpoints, platforms, security policy, contributing guide.
+* CI (tests on Linux for Python 3.11 and 3.13 and on Windows for 3.12, lint, shellcheck, wheel smoke test on Linux and Windows, secret
+  scanning, dependency audit), a tag-triggered release workflow (PyPI Trusted Publishing, GitHub release with SHA256SUMS) and a
+  release-hygiene checker (`scripts/release_check.py`).
+* Preflight loads the ssh access key the way ssh does before any lease is created (a key other accounts can read, for example after
+  copying `secrets.env` and `keys\` to a new Windows PC, is refused locally with the `icacls` / `chmod` fix instead of a paid lease that
+  never answers ssh); on Windows `ddc install` makes the keys it generates owner-only. `clouddeck doctor` counts a scheduled watchdog only
+  when it runs this config.
+
+### Upgrading from the pre-release `ddc.py`
+
+* The command lock is an OS lock on `ddc.flock`; `ddc.lock` is left to the pre-release tool, and `ddc` waits while a pre-release
+  `ddc.lock` (holding `<pid> <time>`) younger than 3 h exists. Disable the pre-release watchdog task before the first `ddc` command: the
+  pre-release tool does not see `ddc.flock`. `ddc install --migrate` replaces the old watchdog task and also rewrites a
+  `%USERPROFILE%\bin\clouddeck.cmd` that points elsewhere (`--dry-run` lists the shims).
+* Scheduled watchdogs (Windows task, systemd, cron) are registered with `--config`, and a watchdog run that cannot load its config or finds
+  conflicting state dirs raises an alert instead of failing silently.
+* Every checkpoint first re-sends the lease env, so a changed `state_repo` (for example after the state repository moved to another owner) takes effect without
+  restarting the box; restored push repos get `origin` set to their configured `github`; the checkpoint verification clone never prompts
+  and fails closed after 600 s.
+
+### Known limitations
+
+See [SECURITY.md](SECURITY.md#known-limitations) and [docs/COSTS-AND-SAFETY.md](docs/COSTS-AND-SAFETY.md#what-is-not-bounded). In short:
+the platform runtime limit was observed working once (not a guarantee), the watchdog needs your PC, SSH host keys are trusted on first use, deploy keys are
+not per-lease, checkpoint verification is not a content digest, macOS is unsupported (no watchdog installer), and a native Linux host has not been used against real
+leases (WSL2 has). What was checked against real leases: README, "Verified and not verified".
+
+[Unreleased]: https://github.com/trexchery/clouddeck/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/trexchery/clouddeck/releases/tag/v0.1.0

clouddeck-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,131 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement through GitHub's
+private reporting form for this repository:
+<https://github.com/trexchery/clouddeck/security/advisories/new> (start the title
+with "Conduct:"). Please do not use public issues for conduct reports.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+<https://www.contributor-covenant.org/version/2/1/code_of_conduct.html>.
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+<https://www.contributor-covenant.org/faq>. Translations are available at
+<https://www.contributor-covenant.org/translations>.
+
+[homepage]: https://www.contributor-covenant.org
+[Mozilla CoC]: https://github.com/mozilla/diversity

clouddeck-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,181 @@
+# Contributing to CloudDeck
+
+Thanks for helping. CloudDeck is alpha software that moves real money, so the bar for changes is "boring, tested and safe". Small,
+focused pull requests are easiest to review. Please read the [Code of Conduct](CODE_OF_CONDUCT.md); report security problems privately
+(see [SECURITY.md](SECURITY.md)), not as issues.
+
+By contributing you agree that your contribution is licensed under the [MIT license](LICENSE). Much of this code base was written with
+AI assistance and contributions may be too; you are responsible for understanding, testing and standing behind what you submit.
+
+## The one rule
+
+> **Tests never spend real money and never touch real state.**
+> No Akash API key, no real lease, no real `secrets.env`, `state.json` or keys directory, no network call to the Akash API (not even a
+> read-only one) from a test.
+
+Tests use the simulated provider (`DemoProvider`, `clouddeck -p demo`) and the in-memory Akash and lease fake in `tests/fake_akash.py`
+(the `fake` fixture in `tests/conftest.py`). External responses are saved fixtures. Use neutral names in tests, fixtures and docs
+(`prod-box`, `web-app`, `my-project`, `provider-a.example`), and never real deployment numbers, account addresses, host names or paths.
+
+## Development setup
+
+You need Python 3.11+ and git. For the lease-script tests you also want bash, GnuPG, `flock` and `tar` (Linux or WSL; they are
+skipped with a reason elsewhere).
+
+```bash
+git clone https://github.com/trexchery/clouddeck.git && cd clouddeck
+python -m venv .venv && . .venv/bin/activate          # Windows: .venv\Scripts\Activate.ps1
+pip install -e ".[dev]"
+pip install ruff==0.17.1                               # the version CI uses
+```
+
+Optional: `pip install -e ".[pty-tests]"` for the terminal smoke test (`python tests/pty_smoke.py`), `pip install shellcheck-py` for
+the lease scripts, `pip install pre-commit && pre-commit install` for the same checks as CI before every commit.
+
+## Running the tests
+
+```bash
+python -m pytest -p no:cacheprovider
+```
+
+The suite is offline and takes a few minutes. Run plain `pytest` or a single file; mixing `tests/...` paths with the root `test_ddc.py`
+in an unusual order can lose the per-test isolation fixture (there are two `conftest.py` files). The TUI tests are timing-sensitive on a
+heavily loaded machine: rerun a lone failure before investigating.
+
+The `ddc job` tests (`tests/test_job_*.py`) run the real runner on virtual time against a stubbed Akash API and a fake box
+(`tests/job_fakes.py`, `tests/job_helpers.py`; the `jw` fixture) inside the same isolated state as every other test. `tests/job_sim.py` is the
+old-vs-new simulation with assumed, synthetic inputs (from a checkout with the dev extra, `python tests/job_sim.py` runs it standalone in a throw-away state dir). `tests/test_job_scripts.py` runs the real
+`jobremote/*.sh` scripts under bash and skips cleanly where bash (or curl, or shellcheck) is missing.
+
+Opt-in extras:
+
+* `CLOUDDECK_TEST_WHEEL=1 python -m pytest tests/test_packaging.py` builds a wheel in a temp copy and runs it in a clean venv (needs
+  network for the build backend).
+* `python tests/pty_smoke.py` drives the real TUI through a pseudo-terminal.
+
+### Redirect the environment first (and why)
+
+The controller reads its config, state and secrets locations from the environment **when it is imported**. A test run once resolved the
+real directories and overwrote a live `state.json`: the file that records which leases are billing. Two protections exist now:
+
+1. the root `conftest.py` points `DDC_STATE_DIR`, `DDC_SECRETS_DIR` and `DDC_CONFIG` at fresh temp directories before anything is
+   imported, and the controller **refuses to load under pytest** unless `DDC_STATE_DIR` and `DDC_SECRETS_DIR` are both set;
+2. *you*, every time you run pytest, a script that imports `clouddeck`, or the CLI during development, should also redirect the
+   environment, so that a mistake cannot reach your real directories.
+
+```bash
+# Linux / macOS / WSL
+S=$(mktemp -d)
+export HOME=$S/home XDG_CONFIG_HOME=$S/xdg/config XDG_STATE_HOME=$S/xdg/state XDG_DATA_HOME=$S/xdg/data TMPDIR=$S/tmp
+export DDC_STATE_DIR=$S/state DDC_SECRETS_DIR=$S/secrets PYTHONDONTWRITEBYTECODE=1
+mkdir -p "$HOME" "$TMPDIR"
+python -m pytest -p no:cacheprovider
+```
+
+```powershell
+# Windows PowerShell
+$S = Join-Path $env:TEMP ("clouddeck-" + [guid]::NewGuid()); New-Item -ItemType Directory $S\home, $S\local, $S\roaming, $S\tmp | Out-Null
+$env:USERPROFILE = "$S\home"; $env:HOME = "$S\home"; $env:LOCALAPPDATA = "$S\local"; $env:APPDATA = "$S\roaming"
+$env:TEMP = "$S\tmp"; $env:TMP = "$S\tmp"
+$env:DDC_STATE_DIR = "$S\state"; $env:DDC_SECRETS_DIR = "$S\secrets"; $env:PYTHONDONTWRITEBYTECODE = "1"
+python -m pytest -p no:cacheprovider
+```
+
+Do the same in a throwaway shell when you try `ddc` or `clouddeck` by hand, unless you really mean to use your real setup.
+
+## Adding or changing things
+
+* **Every behaviour change gets an offline test**, and a bug fix gets a test that fails without the fix. Spending, ownership,
+  checkpoint and watchdog paths are the most important to cover: look at `tests/test_safety_*.py` for the pattern.
+* **Keep the compatibility promises** ([ARCHITECTURE.md](docs/ARCHITECTURE.md#compatibility-promises)): the `ddc-` lease prefix and `ours`
+  semantics, the `state.json` / `ledger.jsonl` / `custom_profiles.json` formats, the checkpoint layout, the lease-side paths, and the
+  `DDC_*`, `AKASH_API_KEY` and `CLOUDDECK_*` names. If a change must break one, say so in the PR and in the changelog.
+* **Fail closed.** When something is unknown (an empty API answer, a damaged file, an unreadable balance), do not assume the safe-looking
+  answer; refuse to spend and keep close/stop paths working.
+* **No new runtime dependency** without a discussion: the controller and the lease scripts are standard-library only on purpose.
+* **Lease scripts** (`lease/`): every file in that directory is uploaded to every lease, so no subdirectories; LF line endings; bash
+  (`set -euo pipefail`); `shellcheck -x -S warning -P lease lease/*.sh` must be clean; document new environment variables in
+  `lease/README.md`. Most tests for them need bash, `gpg`, `flock` and `python3` (Linux/WSL).
+* **Job scripts** (`jobremote/`): the same rules as lease scripts (LF, executable bit in git: `git update-index --chmod=+x`, shellcheck clean);
+  `boot.sh` is inlined into the SDL, `step.sh` / `fetch.sh` are uploaded. Anything that creates or closes a lease must go through
+  `launch_lease` / `close_box`, never a direct API call (a test greps for it).
+* **A new provider**: see [Extension points](docs/ARCHITECTURE.md#extension-points). It must route spending through `Provider.require`.
+* **Docs**: update the relevant file under `docs/`, the README command table and `config.example.toml` when behaviour or configuration
+  changes. Do not document a flag you have not run `--help` on.
+
+## Style
+
+* Python: `ruff check .` must pass (configuration in `pyproject.toml`: rules E, F, W, I, B, UP, target 3.11, long lines are allowed).
+  `ruff format` is enforced only for `scripts/` and `tests/test_release_check.py`; elsewhere match the surrounding code (the code base
+  is compact), and do not reformat files you are not changing.
+* Prefer the shortest change that works; no abstractions for a single caller, no speculative configuration.
+* Error messages say what happened and what to do next. Never print secrets, tokens or key material, not even in debug output.
+
+## Release hygiene checks
+
+```bash
+python scripts/release_check.py --no-history   # working tree: tracked and untracked-not-ignored files
+python scripts/release_check.py                # plus every commit, every blob, every commit message
+python scripts/release_check.py --strict       # also fail on placeholders and commit identities (before publishing)
+```
+
+It fails on real-looking secrets, API keys, account addresses, personal absolute paths, private Claude session links, forbidden file
+names and missing required files. It prints locations and rule names only, never the matched text. With `--strict` it also fails on an
+`OWNER` placeholder left in this project's own GitHub URL and on unfilled release-manager markers (the README's live-verification
+table); placeholders meant for the user, such as `OWNER/your-private-state-repo`, are fine. Private words (names, private project
+names, deployment ids) are never written into the public script: maintainers keep them in `scripts/release_denylist.local.txt`
+(gitignored; one case-insensitive regex per line, `#` comments) or point `CLOUDDECK_RELEASE_DENYLIST` at such a file. The few legacy
+compatibility strings that are allowed live in `scripts/release_allowlist.toml`, and every entry needs a `reason`: keep it small. The
+allowlist is scanned too, except inside its own `contains` values.
+
+Secret scanning uses [gitleaks](https://github.com/gitleaks/gitleaks) (CI pins version 8.30.1):
+
+```bash
+gitleaks dir --config .gitleaks.toml --redact --no-banner .
+gitleaks git --config .gitleaks.toml --redact --no-banner --log-opts="--all" .
+```
+
+`pre-commit` runs gitleaks, ruff, shellcheck, `detect-private-key` and the tree-only release check.
+
+Building and checking the artifacts (CI does this too):
+
+```bash
+pip install build twine && python -m build && python -m twine check --strict dist/*
+python scripts/check_dist.py dist/*.whl dist/*.tar.gz
+```
+
+Remove `build/`, `dist/` and `*.egg-info/` afterwards; they are ignored by git but should not linger.
+
+With `SOURCE_DATE_EPOCH` set to the commit time (`git log -1 --format=%ct`), the wheel is bit-for-bit reproducible. The sdist is
+content-reproducible only: the same members, order and contents, but tar and gzip timestamps differ between builds. Release artifacts
+are built on Linux (`.github/workflows/release.yml`) so the sdist keeps the executable bits of the shell scripts.
+
+## Running the CI gates locally
+
+```bash
+python scripts/ci_local.py              # ruff, pytest (redirected env, -n auto with pytest-xdist), release_check --no-history,
+                                        # build + twine check + check_dist, shellcheck if installed
+python scripts/ci_local.py --release    # the same with release_check --strict over tree + history, as the release workflow runs it
+python scripts/ci_local.py --no-build   # skip the build
+```
+
+It needs `pip install -e ".[dev]" ruff==0.17.1 build twine` (and optionally `pytest-xdist`, `shellcheck-py`). It does not run the
+Windows/Linux matrix, the clean-venv wheel smoke test, actionlint, gitleaks or pip-audit; CI does.
+
+## Releasing
+
+Push a `vX.Y.Z` tag on a commit that is green on `main`, after moving the `[Unreleased]` entries of `CHANGELOG.md` into a dated `[X.Y.Z]`
+section, setting the version in `pyproject.toml` and `clouddeck/__init__.py` and filling in the README's live-verification table.
+`.github/workflows/release.yml` checks that the tag, the version and the changelog agree, runs `release_check.py --strict`, builds and
+checks the artifacts, publishes to PyPI through Trusted Publishing when the repository variable `PYPI_PUBLISH` is `true`, and creates the
+GitHub release with the wheel, the sdist, `SHA256SUMS` and that changelog section as notes.
+
+## Pull request checklist
+
+- [ ] Offline tests added or updated, and `python -m pytest -p no:cacheprovider` passes (with the redirected environment above)
+- [ ] `ruff check .` is clean (and `shellcheck` for `lease/` changes)
+- [ ] `python scripts/release_check.py --no-history` passes: no secrets, personal paths, account names or real host names
+- [ ] No test, fixture or doc depends on real money, real credentials or real state
+- [ ] Compatibility kept, or the break is called out
+- [ ] Docs, `config.example.toml` and `CHANGELOG.md` updated if behaviour or configuration changed
+- [ ] The change is as small as it can be

clouddeck-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CloudDeck contributors
+
+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.

clouddeck-0.1.0/MANIFEST.in

@@ -0,0 +1,14 @@
+include LICENSE README.md SECURITY.md CONTRIBUTING.md CODE_OF_CONDUCT.md CHANGELOG.md THIRD_PARTY_NOTICES.md
+include .env.example .gitleaks.toml
+include config.example.toml sdl.yaml.tmpl ddc.py conftest.py test_ddc.py requirements.txt
+recursive-include lease *
+recursive-include jobremote *
+recursive-include docker *
+recursive-include examples *
+recursive-include tests *
+recursive-include scripts *
+recursive-include windows *
+recursive-include bin *
+recursive-include docs *
+global-exclude __pycache__ *.py[cod]
+exclude scripts/release_denylist.local*