Punch CLI

Punch CLI is the public command-line interface for the invite-only Punch Compute network.

It provides a guided punch entry point and two role-specific commands:

• punch-buyer — discover offers, order compute, inspect jobs, open brokered SSH sessions, and download output.
• punch-provider — join as a provider and run the supervised setup that verifies the host, enrolls narrow access, proves the execution surface, and starts the resident provider service.

The documented preview configuration uses the public Punch HTTPS endpoint. Buyers are not given a provider IP address, Docker socket, or host credential. Providers connect outbound to Punch.

Public preview: The repository is public, but the network remains invitation-only. A public repository does not make the service, payments, or capacity generally available.

Current published CLI: v0.1.0-preview.19.6, published 13 September 2026, is the current Ubuntu 24.04 LTS Linux/x64 public prerelease. Verify punch-cli-0.1.0-preview.19.6-linux-x64.tar.gz against the same-release SHA256SUMS; its archive SHA-256 is 1b6b2c4b99b66e9b811be3d67e185de904769e81535736f33aee32af975754ab. A source checkout is not an installable release.

The later AWS payment deployment uses separately versioned Control, Provider, and native services. Installing the published CLI does not install those later service fixes or wallet custody. See Livepeer production operations for the architecture, pricing, payment proof, and upgrade boundary.

Preview.19.5 was the preceding public candidate; its retained archive SHA-256 is d18f8e6586f6333610f3ef33e13c27c571dbc30bdbf34f7038908283069892ae. The historical v0.1.0-preview.19.4 remains published with archive SHA-256 ae7bfbb5c9e9b278e45e025853f35833997525b595a5ab6abaef54544f7450ac. Old release archives, checksums, and version-specific guides remain immutable.

v0.1.0-preview.18 is historical release provenance, not the current install target. Its archive SHA-256 is d144fd266328c022ef2601feb871ff62396a293d5e35e7130a3880cc0cdaf423. Preview.18 preserved guided Provider and Buyer onboarding from punch, adds explicit Provider offer selection and sequential replacement, and prepares a contract-bound, copy-ready Buyer SSH command without spawning SSH. Optional OSC 52 clipboard delivery requires explicit consent and always retains the visible command. Publication alone is not OWNER-READY; that requires the separate clean Provider and Buyer acceptance in the Preview.18 flow.

v0.1.0-preview.17, v0.1.0-preview.16, v0.1.0-preview.15, v0.1.0-preview.14, v0.1.0-preview.13, v0.1.0-preview.12, and v0.1.0-preview.11 remain immutable historical releases. Preview.16 lacks the guided Buyer sudo -n true capability probe before interactive fallback; use Preview.18 for guided Buyer join. Preview.15 lacks the equivalent guided Provider probe repaired in Preview.16. Preview.12 must not be used for Provider serving because its archive contains the documented ESM/CommonJS packaging defect. Use only release assets together with the matching immutable image set in Release and verification policy.

What is public

• Installation and update tooling.
• Buyer and provider command documentation.
• Public configuration and protocol boundaries.
• Security model and operational requirements.
• Release checksums and verification instructions.

What is not in this repository

• Punch Control, marketplace, database, or administrator code.
• Invitation minting, settlement, payout, or custody logic.
• Provider signing keys, buyer sessions, invitations, or credentials.
• Deployment infrastructure, internal endpoints, proof artifacts, or production configuration.
• The proprietary Buyer CLI and Provider Agent implementations distributed in release artifacts.

Quick start

1. Read the published Preview.19.6 release notes and its bundled RELEASE-CONTRACT.json.
2. Download its archive and same-release SHA256SUMS, then verify the checksum.
3. Install the matching role from that verified release; see Installation.
4. Run punch for the normal guided Provider or Buyer journey and follow the version-matched Provider guide or Buyer guide.
5. Cross the documented identity/join/setup boundary only after supervised onboarding is approved.

punch-buyer --help
punch-provider --help

The invitation determines the authorized role. Selecting a different command locally cannot change server-side permissions.

If the Releases page has no compatible published asset, the public CLI is not yet installable on that platform. Do not build or copy proprietary CLI artifacts from another repository.

Documentation

• Installation and updates
• Invitations and credentials
• Buyer guide
• Provider guide
• Future compute staging note (staging-only, unreleased)
• Livepeer production operations (separately deployed services)
• Livepeer staging compatibility (historical 19.5 baseline)
• Conditional multi-GPU orders
• Command reference
• Autonomous agent runbook
• Architecture
• Security model
• Platform support
• Troubleshooting
• Release and verification policy
• Preview.19.2 Ubuntu Provider candidate
• Preview.9 clean-v4 supervised pilot
• Preview.11 supervised Buyer bootstrap (gated and unreleased)
• Preview.12 guided Punch home (superseded for Provider serving)
• Preview.13 Provider serve packaging correction
• Preview.14 Provider readiness and release flow
• Preview.15 historical guided Provider onboarding
• Preview.16 historical guided Provider sudo repair
• Preview.18 Provider lifecycle, Buyer SSH handoff, and owner-readiness flow (historical)
• Preview.17 guided Buyer sudo repair and historical flow
• Provider offer lifecycle (published in Preview.14; unavailable in Preview.9)
• NetBird connectivity
• Preview.8 Provider offer and whole-node GPU UX contract
• Targeted zero-price test contract (supervised Preview.9 only)
• Executable public-docs boundary (gated and unreleased)
• Preview.7 GPU validation and setup recovery contract
• Preview.6 Docker-store compatibility contract
• Preview.5 atomic multi-GPU contract

Licensing

The public documentation, installer, and launcher source in this repository are licensed under Apache-2.0. Proprietary Punch Buyer CLI and Provider Agent bundles are not covered by Apache-2.0. Their archives carry PROPRIETARY-ARTIFACT-NOTICE.txt; authorization and use are governed by the applicable Punch invitation or pilot agreement delivered separately.

Security reports

Do not open a public issue for a suspected vulnerability or leaked invitation. Follow SECURITY.md.