offbox 0.1.0__tar.gz

offbox-0.1.0/.dockerignore

@@ -0,0 +1,6 @@
+**
+!images/universal/Dockerfile
+!images/universal/offbox-init
+!images/universal/offbox-run
+!tests/smoke/Dockerfile
+!tests/smoke/host.sh

offbox-0.1.0/.gitignore

@@ -0,0 +1,230 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+*.lcov
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# uv
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi/*
+!.pixi/config.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule*
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs/Zensical documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore that
+#   can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, you
+#   could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Local agent task snapshots and results
+.agent/
+
+# Generated provider workspaces can contain private cloud-init data.
+.terraform/
+*.tfstate
+*.tfstate.*
+*.tfplan
+offbox.auto.tfvars.json

offbox-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,13 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-format
+        name: ruff format
+        entry: uv run --frozen ruff format
+        language: system
+        types_or: [python, pyi]
+      - id: ruff-check
+        name: ruff check
+        entry: uv run --frozen ruff check
+        language: system
+        types_or: [python, pyi]

offbox-0.1.0/AGENTS.md

@@ -0,0 +1,26 @@
+# Repository instructions
+
+## Commands
+
+Use uv for Python tooling. Run `uv sync --frozen` to install locked dependencies. Before pushing, run `make check` and `make test`. Use `make fmt` for formatting and lint fixes and `uv build` for distributions. Validation uses deterministic unit tests, static checks, builds and one focused Linux Docker/SSH smoke job. Do not create billable resources or add real-cloud tests.
+
+## Code rules
+
+- No comments by default. A comment explains why, never what, and only if deleting it would lose a fact. Prefer better names. Short docstrings only on public functions whose contract is not obvious.
+- No `print` outside `src/offbox/console.py`. That module owns stdout/stderr; use module loggers elsewhere: `logger = logging.getLogger(__name__)`. Human messages go to stderr, parseable results to stdout.
+- Annotate every signature, including `-> None`. No `Any` in annotations. `# type: ignore[code]` is allowed only with a reason.
+- Use typed Pydantic models at boundaries: config files, state files, provider outputs and `--json` output. Do not pass raw dicts between modules.
+- Raise `OffboxError` subclasses, never bare `Exception`. No broad `except` that hides a failure. When catching to add context, use `raise ... from e`.
+- All subprocesses go through `Runner`. Use argv lists, never `shell=True`.
+- No speculative abstractions, feature flags for unused features, or compatibility shims. Fix root causes.
+- Tests are deterministic. No `time.sleep` in unit tests; inject `Clock`/`Runner`. No `pytest.skip()` without a reason. No assertions that cannot fail. Do not end a test on `assert x is not None`; assert the actual value.
+- Define `DEFAULT_IMAGE` only in `src/offbox/__init__.py`. Other defaults and generated documentation refer to that constant.
+- Package root `host/`, `images/` and `providers/` resources under `offbox/_data/`; access them using `importlib.resources`.
+
+## Git and PRs
+
+- Use conventional commit messages: `feat:`, `fix:`, `docs:`, `test:`, `chore:`.
+- Keep each PR focused on one change, targeting `master`. The PR description says what changed and how it was verified, including the commands run.
+- `make check` and `make test` must pass locally before pushing.
+- Never commit secrets; tests never need real credentials. Do not create billable resources for tests.
+- Keep local agent task scratch under the ignored `.agent/` directory.

offbox-0.1.0/CHANGELOG.md

@@ -0,0 +1,107 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-26
+
+First public release.
+
+### Added
+
+- Hetzner/OpenTofu provisioning and existing-SSH host initialization with pinned SSH host keys and recoverable local provider state.
+- Per-worktree privileged environments with separate Docker daemons, resource limits, persistent data, ownership checks and garbage collection.
+- Public universal amd64 image with pinned development tools, Docker Compose, browser dependencies and execution/readiness shims.
+- Two-way-safe Mutagen synchronization, mandatory Git exclusion, dependency-file hashing and explicit project setup commands.
+- Streaming command execution with scoped environment variables, stdin/TTY modes, preserved exit codes and bounded signal cleanup.
+- Stable loopback port allocation, SSH forward restoration and port swaps across environments.
+- Typed health reports, scoped logs, guided setup and local uninstall that preserves remote hosts.
+- Configuration, architecture, provider, security and troubleshooting guides, plus FastAPI/Postgres and Vite/Playwright examples.
+- Focused Linux Docker/SSH smoke validation without cloud credentials or billable cloud resources.
+- Google Cloud provisioning with a dedicated per-host network, Ubuntu cloud-init, no attached VM service account, standard Google authentication and mocked Terraform contract tests.
+- A Google Cloud benchmark of both sample apps and a same-VM comparison measuring a 12.2% median command latency reduction from batching checks, with verified cloud cleanup.
+- Opt-in `--timings` summaries for provisioning, synchronization, setup, forwarding and command execution, without changing stdout or exit codes.
+- A real Hetzner benchmark of both sample applications, including timings, resource observations, billing estimates and verified cleanup.
+- Committed provider lock files for Hetzner and Google Cloud with Terraform and OpenTofu checksums for Linux and macOS on amd64/arm64.
+- A mocked Hetzner provider contract test, plus OpenTofu validation and contract tests in CI.
+- Package metadata (authors, classifiers, keywords, documentation and changelog links) and upper bounds for runtime dependencies.
+- Issue and pull request templates and a code of conduct.
+- A one-line installer (`install.sh`) for macOS, Linux and WSL2 that installs uv if needed, installs offbox and starts `offbox setup`, and an installation guide with step-by-step platform and provider instructions.
+- `offbox setup` downloads pinned, SHA-256-verified Mutagen 0.18.1 when no Mutagen 0.18.x is installed, and offers to create a dedicated `~/.ssh/offbox_ed25519` key when no key exists.
+- `host init --host-key-fingerprint` (also on `setup`) verifies an existing server's key against a fingerprint obtained out of band.
+- `host destroy --forget` removes the local record of an unreachable existing-SSH host.
+- `exec.env` names are approved by `offbox up`; `exec` refuses names that changed since and refuses provider credential variables.
+- Help text for every CLI option, and `exec --help` shows the `-- COMMAND` form.
+- A git mirror pushes `HEAD`, the remote's default branch and `git.refs` into `/work/.git` so git-based tooling works in the environment, and `[files] copy` copies named home-directory files such as gcloud credentials into it; new copies and refs need approval by `offbox up`.
+- Commands run by offbox see `OFFBOX_ENV` set to the environment name.
+- Project settings can also come from `[project]` tables in the user `config.toml`, an uncommitted `offbox.local.toml` and `OFFBOX_<SECTION>_<KEY>` environment variables, merged per key with later sources winning.
+- `offbox config [--json]` shows every effective project setting with its source and variable name.
+- Auto-managed hosts: `auto = true` on a host preset creates the VM on the first `offbox up` that needs it and destroys it when its last environment is removed or after `idle` (default `2h`) without use, guarded by a shared usage lock so running commands never lose their host. `offbox host reap [--dry-run] [--json]` reaps idle hosts and abandoned creations, `--install-timer` schedules it every 15 minutes, and `env.host` selects a project's host by name.
+
+### Changed
+
+- The git mirror is on by default and also mirrors the remote's default branch (`origin/HEAD`); set `git.mirror = false` to opt out. Environments without a recorded mirror approval accept the default mirror without a new `up`; others need one `offbox up`.
+- Fix lines that named `offbox.toml` now point to `offbox config`, because a value can come from any settings source.
+- The state file gains host lifecycle fields; after upgrading, older offbox versions can no longer read it.
+- Host bootstrap waits up to 10 minutes for apt/dpkg locks, enables unattended upgrades last, and keeps installed containerd and Docker plugin versions when rerun so `host init` does not restart Docker.
+- The universal image base is pinned by digest, upgrades Ubuntu packages during the build and is rebuilt weekly without layer cache.
+- The README describes the problem offbox solves, measured results, comparisons and common questions; development details moved to CONTRIBUTING.md.
+- `host destroy` always runs the cloud destroy, treating local Mutagen and SSH cleanup failures as warnings, and reinitializes the provider workspace first so a cleared cache cannot block it.
+- `uninstall --yes` refuses while cloud hosts remain unless `--abandon-cloud-hosts` is given; existing-SSH host teardown also removes the `offbox` sudoers entry and authorized key.
+- `up --fresh` requires confirmation or `--yes`, `doctor` fails when no host is configured, and `setup --action check` no longer edits SSH configuration.
+- Warm `exec` runs one remote preflight instead of three probes and restores port forwards alongside the command; readiness polling is faster.
+- `up` warns when CPU, memory, shared-memory or image settings differ from the running container.
+- Automatic Compose forwards are capped at 32 per environment.
+- State and cache directories are private (0700), and the previous state file is kept as `state.json.bak`.
+
+### Fixed
+
+- Ctrl-C, SIGTERM and SIGHUP relay into remote process groups works again: `offbox-run` used a `kill -s NAME -- -PGID` form that the image's procps-ng rejects.
+- A non-TTY `offbox exec` killed without a chance to relay (SIGKILL, lost network) no longer leaves its remote command running.
+- Changing `install.command` reinstalls dependencies on the next `exec`, not only changes to the `install.when` files.
+
+- Interrupting provisioning no longer kills OpenTofu mid-apply; Ctrl-C after a VM exists prints the `host destroy` command and exits 130.
+- An unreadable state file reports the backup and the manual `tofu destroy` commands for each provider workspace.
+- Generated SSH configuration disables agent and X11 forwarding and offers only the configured key, so user-wide `Host *` settings no longer apply to offbox hosts; `host init` quotes the known-hosts path.
+- Every `--env` and `exec.env` value is redacted from logs and verbose output as `NAME=value`, regardless of the variable name; secret-named and long values are also redacted on their own.
+- `exec` no longer waits for another worktree's `up`, concurrent `exec` calls in one worktree wait for a running installation instead of failing, and port-restore errors no longer prevent the command from running.
+- Closing the terminal relays termination to the remote command instead of orphaning it.
+- Concurrent invocations no longer fail while pruning old log files; `logs --follow` reads incrementally.
+- `ports --swap` works when the port's current owner is stopped.
+- The image freshness check recognises Docker's containerd image store digests.
+- Fix lines on non-terminal stderr are no longer wrapped at 80 columns.
+- `uninstall` stops a Mutagen daemon started from the downloaded copy before removing it.
+- A failed host bootstrap writes `/var/lib/offbox/failed`, and `host create` reports it immediately with the end of the cloud-init log instead of waiting for the 15-minute readiness timeout.
+- Host bootstrap and the image verify the Docker apt signing key fingerprint before trusting it.
+- Host bootstrap reloads SSH with `try-reload-or-restart`, which works with Ubuntu 24.04 socket activation, and no longer locks the `offbox` account, which sshd rejects when `UsePAM` is off.
+- Commands run through `offbox exec` use umask 022 instead of inheriting 077, so build outputs are no longer owner-only.
+- The inner Docker daemon log is capped at 10 MiB with one rotated file.
+- Wheels and host provider workspaces no longer include local `.terraform/` directories, Terraform state, editor swap files or provider tests.
+- Existing-host teardown validates resource ownership, preserves adopted networks and refuses foreign network members before deletion; environment cleanup handles root-owned source directories.
+- Environment shutdown forwards signals to dockerd and waits within the outer stop deadline.
+- Routine command and forwarding lock contention uses bounded waits; unconfirmed SSH completion includes per-run recovery guidance.
+- Public contribution workflows use restricted credentials and publication jobs; release tags remain blocked while publishing is deferred.
+- Batched port discovery streams large responses instead of passing them as process arguments; empty install markers report the correct recovery action.
+- Cloud host creation refreshes early SSH connections and verifies Docker access before reporting readiness, so bootstrap's Docker-group changes take effect.
+- `up` no longer holds the host lock while waiting for another installation, a busy host lock no longer prints a port-restore warning during `exec`, and an interrupted `exec` waits at most one second for port restore.
+- `up` no longer reports a settings change for containers created before settings were recorded; `host create` and `host init` default to `~/.ssh/offbox_ed25519` when `~/.ssh/id_ed25519` is missing, matching `setup`.
+- The installer prints the PATH line to add when it cannot update the shell profile, finds uv in `UV_INSTALL_DIR` or `XDG_BIN_HOME`, and reports an unfinished `offbox setup` without failing.
+- Execution combines dependency hash/marker reads and owned-container/Compose port discovery into fresh probes, removing two sequential SSH round trips without skipping checks.
+
+## [0.0.1] - 2026-10-23
+
+Initial source skeleton; not published to PyPI.
+
+### Added
+
+- Typed Python CLI skeleton with `offbox --version`, `offbox version` and `python -m offbox`.
+- Locked uv dependencies, formatting, linting, strict type checks and unit tests.
+- Linux/macOS CI and trusted-publisher release workflow.
+- Contributor instructions and packaging configuration for future host, image and provider resources.
+
+[Unreleased]: https://github.com/o-avdieiev/offbox/compare/v0.1.0...master
+[0.1.0]: https://github.com/o-avdieiev/offbox/releases/tag/v0.1.0
+[0.0.1]: https://github.com/o-avdieiev/offbox/tree/37ba5be5c132161441ca045def3edb5da26e9065

offbox-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,9 @@
+# Code of conduct
+
+This project follows the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). Everyone taking part in issues, pull requests and discussions is expected to uphold it.
+
+## Reporting
+
+Report unacceptable behavior to the maintainer, [@o-avdieiev](https://github.com/o-avdieiev), through a private channel. For a report that should not be public, use [GitHub's private reporting form](https://github.com/o-avdieiev/offbox/security/advisories/new) and say that it concerns conduct. All reports are reviewed and kept confidential.
+
+The maintainer may remove, edit or reject comments, commits, code, issues and other contributions that do not follow this code of conduct, and may temporarily or permanently restrict participation, following the enforcement guidelines of the Contributor Covenant.

offbox-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,101 @@
+# Contributing
+
+Open a pull request from a fork for changes; no cloud credentials are needed. Fork CI requires maintainer approval before it runs. See [repository safeguards](docs/repository-safety.md) and [private security reporting](SECURITY.md).
+
+## Development
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/) and Python 3.12 or newer, then run:
+
+```sh
+uv sync --frozen
+make check
+make test
+```
+
+`uv.lock` is committed. Change dependencies with uv and include the updated lockfile.
+
+| Command | Purpose |
+| --- | --- |
+| `make fmt` | Format Python and apply Ruff lint fixes |
+| `make check` | Check formatting, lint and strict mypy/Pyright types |
+| `make test` | Deterministic unit tests; excludes the subprocess marker |
+| `uv build` | Build the source distribution and wheel |
+
+Unit CI covers Ubuntu and macOS with Python 3.12 and 3.13. Validation also runs lint, strict type checks, distribution builds, ShellCheck, provider schema validation with mocked Terraform and OpenTofu tests, image builds and one focused native Linux Docker smoke job. Do not add real-cloud tests or require real cloud credentials for tests. Cloud API provisioning and VM bootstrap are not exercised by CI; browser, OOM and performance tests are outside its scope.
+
+Provider checks run without cloud credentials:
+
+```sh
+terraform fmt -check -recursive providers
+terraform -chdir=providers/hetzner init -backend=false
+terraform -chdir=providers/hetzner validate
+terraform -chdir=providers/hetzner test
+terraform -chdir=providers/gcp init -backend=false
+terraform -chdir=providers/gcp validate
+terraform -chdir=providers/gcp test
+```
+
+Each provider commits a `.terraform.lock.hcl` covering Linux and macOS on amd64/arm64. The file holds entries for both `registry.terraform.io` and `registry.opentofu.org`; `init` drops the other tool's entry, so restore the file before committing. After changing a provider version constraint, refresh both entries with `terraform providers lock` and `tofu providers lock` for `linux_amd64`, `linux_arm64`, `darwin_amd64` and `darwin_arm64`, then combine them. CI checks providers with both Terraform and OpenTofu.
+
+Separately approved [Hetzner](docs/benchmarks/2026-10-23-hetzner.md) and [Google Cloud](docs/benchmarks/2026-10-23-gcp.md) benchmarks exercised provisioning and both sample apps, including browser tests, then verified cloud cleanup. Measurements and comparison limits are recorded in the reports.
+
+The Docker smoke job builds and loads the universal image from the current checkout. It uses disposable SSH keys and containers to exercise real SSH, Mutagen, stream/status/signal handling, forwarding and two isolated Compose stacks. It does not create cloud resources or establish VM bootstrap or browser behavior. Its cleanup uses fixture ownership labels and markers; failure logs are retained as a short-lived Actions artifact. The fixture is intended for a disposable native amd64 Linux runner with a Docker daemon and `/srv/offbox/envs` available. Its commands are in [smoke.yaml](.github/workflows/smoke.yaml); do not run it on an existing Offbox host. Unit tests remain independent of Docker and network access.
+
+Runtime tool checks target OpenSSH >=8.0, Git >=2.30 and Mutagen 0.18.x. Provisioning uses OpenTofu >=1.8 or Terraform >=1.6, with a checksum-verified OpenTofu 1.10.6 fallback for macOS/Linux on amd64/arm64. Unit tests inject tool results and downloads; they do not require these tools or network access. See [the agent guide](docs/agents.md) for diagnostics and exit codes.
+
+Local pre-commit hooks use the locked Ruff installation:
+
+```sh
+uvx pre-commit install
+uvx pre-commit run --all-files
+```
+
+## Pull requests
+
+Read [AGENTS.md](AGENTS.md) for code rules. Use conventional commits (`feat:`, `fix:`, `docs:`, `test:`, `chore:`) and keep each PR focused on one change, targeting `master`. Describe what changed and how you verified it, including the commands you ran and relevant output. Run `make check` and `make test` before pushing. Never commit secrets. Tests never need real credentials or billable cloud resources.
+
+The repository keeps host scripts, image files and provider definitions at the root. Hatch maps them into wheels under `offbox/_data/host`, `offbox/_data/images` and `offbox/_data/providers`, excluding local `.terraform/` directories, state files, editor swap files and provider tests; runtime code must use `importlib.resources` to locate them. The universal image is built separately from the Python wheel.
+
+## Future one-time PyPI setup
+
+The package is not yet published to PyPI, and `v*` release tags are blocked until the maintainer enables publishing. Source installs, wheel builds and master-branch GHCR publication are available. The following setup applies to the first release.
+
+The maintainer must configure a [pending trusted publisher](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/) before the first release. A pending publisher does not reserve the project name; the first successful upload creates it.
+
+1. Sign in to the maintainer's PyPI account with two-factor authentication enabled.
+2. Open [PyPI publishing settings](https://pypi.org/manage/account/publishing/) and add a pending publisher with these exact values:
+
+   | Field | Value |
+   | --- | --- |
+   | PyPI project name | `offbox` |
+   | GitHub owner | `o-avdieiev` |
+   | Repository | `offbox` |
+   | Workflow filename | `release.yaml` |
+   | Environment name | `pypi` |
+
+3. The `pypi` environment is restricted to `v*` tags. Review its approval policy and explicitly update the release-tag ruleset that currently blocks those tags before the first release.
+4. Ensure GitHub Actions is enabled. Only the artifact-consuming publish job requests `id-token: write` for OIDC and `contents: write` for the GitHub release; build/test jobs use read-only permissions. No PyPI API token or password is needed.
+
+For later releases, manage the publisher under the existing PyPI project's Publishing settings. See [PyPI's trusted-publisher documentation](https://docs.pypi.org/trusted-publishers/adding-a-publisher/).
+
+## Release
+
+1. Set `__version__` in `src/offbox/__init__.py` and add the matching dated section in `CHANGELOG.md`.
+2. Run `uv sync --frozen`, `make check`, `make test` and `uv build`. Install the wheel in an isolated environment and check both version forms.
+3. Merge the release PR after CI succeeds. For the first release, confirm that the PyPI setup above is complete.
+4. Once publishing is enabled, create and push a tag matching the package version. This starts `.github/workflows/release.yaml`.
+5. The workflow checks the tag against the package version, extracts that version's changelog section, builds and smoke-tests the wheel, then runs `uv publish --trusted-publishing always`. It creates the GitHub release using the same changelog section and attaches the distributions.
+6. Verify `uvx --refresh offbox --version` prints the released version and inspect the release on PyPI and GitHub.
+
+Release publication requires the maintainer's PyPI account setup; building and testing locally does not publish anything. See the GHCR setup below before the first universal-image publication.
+
+
+## Universal image and one-time GHCR setup
+
+The image workflow builds `linux/amd64` from `images/universal/Dockerfile`. Pull requests build without pushing. Changes to the image, its workflow or the package image constant on `master` publish the compatibility tag from `DEFAULT_IMAGE` and `sha-<short commit>`. Release tags also publish the corresponding semantic version. The workflow reads the repository name and compatibility tag from the package constant, so an image default changes in one place.
+
+After the first successful publication, open the repository's linked `offbox-universal` package on GitHub, choose **Package settings → Change visibility → Public**, and confirm the change. This is a one-time maintainer action; hosts need anonymous pull access. Ensure the package is linked to this repository and its Actions access allows this repository to write. The workflow uses only `GITHUB_TOKEN` with `packages: write`; no cloud credential or registry password is needed. See [GitHub's package visibility instructions](https://docs.github.com/en/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility).
+
+Image compatibility series `1` is distinct from the CLI release number. A future CLI `v0.1.0` release publishes image aliases `:0.1.0` and `:1.0.0` in addition to the compatibility and commit tags. A weekly scheduled run on `master` rebuilds and republishes the compatibility and commit tags so the image picks up Ubuntu security updates.
+
+Each successful build writes the actual compressed OCI image size to its Actions summary and an `image-size` artifact. Include the measured result in PRs that change the image; the target is below 3 GB. The report sums the compressed layer and configuration descriptors for the amd64 image and excludes attestations. Build/static checks do not prove nested Docker, browser or signal behavior at runtime. See [the image build guide](docs/universal-image.md) for contents and process contracts.

offbox-0.1.0/LICENSE

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

offbox-0.1.0/Makefile

@@ -0,0 +1,14 @@
+.PHONY: fmt check test
+
+fmt:
+	uv run --frozen ruff format
+	uv run --frozen ruff check --fix
+
+check:
+	uv run --frozen ruff format --check
+	uv run --frozen ruff check
+	uv run --frozen mypy
+	uv run --frozen pyright
+
+test:
+	uv run --frozen pytest -m "not subprocess"