# Harmont

> Harmont is a headless CI platform. Developers push local, uncommitted code
> straight into CI pipelines with `hm run` — no commit or remote push first.
> Pipelines are written as Python or TypeScript programs using the high-level
> Pipeline SDK.

For an orientation written for AI agents — including how to fetch any page as
Markdown — read /agents. For the canonical do/don't patterns when writing
pipelines, read /pipeline-sdk/patterns.

- [Harmont](/): Headless CI for engineers who push code, not pixels.
- [Getting started](/getting-started): Install hm, scaffold a pipeline with hm init, and run it.
- CLI
  - [hm CLI](/cli): The hm command line — scaffold, run, and inspect pipelines from local code.
  - [hm init](/cli/init): Scaffold a starter pipeline into .hm/.
  - [hm run](/cli/run): Run a pipeline against your local working tree, in Docker.
  - [hm pipelines](/cli/pipelines): Print the discovered pipelines as JSON.
  - [Configuration](/cli/config): How hm resolves configuration — files, layering, and environment overrides.
- Pipeline SDK
  - [Pipeline SDK](/pipeline-sdk): Define Harmont pipelines in code — Python or TypeScript.
  - [Chains & steps](/pipeline-sdk/chains): How a pipeline is built from chained shell steps, forks, and waits.
  - [Toolchains](/pipeline-sdk/toolchains): Install a language, warm its cache, and run build/test/lint in one call.
  - [Patterns & anti-patterns](/pipeline-sdk/patterns): Write pipelines with the high-level toolchain APIs. Reach for hm.sh only when no toolchain covers your case.
  - [Caching](/pipeline-sdk/caching): TTL, on-change, forever, and composed cache policies for pipeline steps.
  - [Triggers](/pipeline-sdk/triggers): Run a pipeline on push or pull request.
  - Reference
    - [Reference](/pipeline-sdk/reference): Every public function, class, and toolchain in the harmont pipeline SDK.
    - [Cache policies](/pipeline-sdk/reference/cache): Generated reference for the harmont Cache policies API.
    - [Chains & steps](/pipeline-sdk/reference/chains): Generated reference for the harmont Chains & steps API.
    - [Pipeline](/pipeline-sdk/reference/pipeline): Generated reference for the harmont Pipeline API.
    - [Triggers](/pipeline-sdk/reference/triggers): Generated reference for the harmont Triggers API.
    - Toolchains
      - [Base images](/pipeline-sdk/reference/toolchains/base): Generated reference for the harmont Base images API.
      - [CMake](/pipeline-sdk/reference/toolchains/cmake): Generated reference for the harmont CMake API.
      - [Composer](/pipeline-sdk/reference/toolchains/composer): Generated reference for the harmont Composer API.
      - [Dotnet](/pipeline-sdk/reference/toolchains/dotnet): Generated reference for the harmont Dotnet API.
      - [Elm](/pipeline-sdk/reference/toolchains/elm): Generated reference for the harmont Elm API.
      - [Go](/pipeline-sdk/reference/toolchains/go): Generated reference for the harmont Go API.
      - [Gradle](/pipeline-sdk/reference/toolchains/gradle): Generated reference for the harmont Gradle API.
      - [Haskell](/pipeline-sdk/reference/toolchains/haskell): Generated reference for the harmont Haskell API.
      - [Npm](/pipeline-sdk/reference/toolchains/npm): Generated reference for the harmont Npm API.
      - [Ocaml](/pipeline-sdk/reference/toolchains/ocaml): Generated reference for the harmont Ocaml API.
      - [Perl](/pipeline-sdk/reference/toolchains/perl): Generated reference for the harmont Perl API.
      - [Python](/pipeline-sdk/reference/toolchains/python): Generated reference for the harmont Python API.
      - [Ruby](/pipeline-sdk/reference/toolchains/ruby): Generated reference for the harmont Ruby API.
      - [Rust](/pipeline-sdk/reference/toolchains/rust): Generated reference for the harmont Rust API.
      - [Zig](/pipeline-sdk/reference/toolchains/zig): Generated reference for the harmont Zig API.
- Examples
  - [Examples](/examples): Complete, runnable starter projects grouped by what you're building.
  - [Rust](/examples/rust): A Cargo project: build, test, clippy, and fmt fork from one toolchain install.
  - [Go](/examples/go): A Go module: build, test, vet, and fmt.
  - [CMake (C / C++)](/examples/cmake): A CMake project wired to Harmont — configure, build, test, and format.
  - [Zig](/examples/zig): A Zig project: build, test, and fmt.
  - [Next.js](/examples/nextjs): A Next.js app via the js toolchain: build, test, and lint.
  - [Python (uv)](/examples/python-uv): A uv-managed project: test (pytest), lint (ruff), fmt, and typecheck (mypy).
  - [Elixir](/examples/elixir): A mix project: compile, test, format, Credo, Dialyzer, plus deps_audit/hex_audit.
- API
  - [API](/api): REST. JSON. Bearer-token auth. Stable codes on every error.
  - Errors
    - [Errors](/api/errors): One JSON envelope for every failure — stable code, human message, and a link to the fix.

    - **Passkey & auth**
    - [passkey_token_invalid](/api/errors/passkey_token_invalid): A sign-up or recovery link has expired or was already used.
    - [passkey_challenge_invalid](/api/errors/passkey_challenge_invalid): The passkey ceremony expired before it completed.
    - [passkey_assertion_failed](/api/errors/passkey_assertion_failed): The passkey signature did not validate.
    - [passkey_registration_failed](/api/errors/passkey_registration_failed): The passkey could not be registered.
    - [passkey_unknown_credential](/api/errors/passkey_unknown_credential): The passkey you presented is not registered on this account.
    - [passkey_user_verification_required](/api/errors/passkey_user_verification_required): The authenticator signed in without user verification.
    - [passkey_signup_email_taken](/api/errors/passkey_signup_email_taken): An account already exists for this email.
    - [passkey_last_credential](/api/errors/passkey_last_credential): You cannot remove your only remaining sign-in method.
    - [passkey_email_send_failed](/api/errors/passkey_email_send_failed): We could not send the verification email.
    - [email_unconfigured](/api/errors/email_unconfigured): This deployment has no email provider configured.

    - **API keys**
    - [api_token_not_found](/api/errors/api_token_not_found): No such API key. It may have already been revoked; reload and try again.

    - **Access**
    - [signup_cap_reached](/api/errors/signup_cap_reached): Sign-ups are paused because Harmont is at capacity during early access.
    - [signup_failed](/api/errors/signup_failed): Sign-up could not be completed due to an unexpected server error.

    - **Billing**
    - [billing_insufficient_balance](/api/errors/billing_insufficient_balance): Your account balance is too low to run this build.
    - [billing_unconfigured](/api/errors/billing_unconfigured): Billing is not configured for this deployment.
    - [billing_provider_error](/api/errors/billing_provider_error): The upstream billing provider returned an error.

    - **Pipelines**
    - [pipeline_manual_disabled](/api/errors/pipeline_manual_disabled): Manual builds are turned off for this pipeline.
  - Reference
    - [Reference](/api/reference): Every endpoint, grouped by tag.
    - [Auth](/api/reference/auth)
    - [Billing](/api/reference/billing)
    - [Builds](/api/reference/builds)
    - [Jobs](/api/reference/jobs)
    - [Organizations](/api/reference/organizations)
    - [Pipelines](/api/reference/pipelines)
    - [User](/api/reference/user)
- Cloud SDK
  - [Cloud SDK](/sdk): A typed TypeScript client for the Harmont API, generated from the OpenAPI spec.
  - [Authentication](/sdk/authentication): Construct a client and attach your bearer token.
  - [Making calls](/sdk/usage): Call typed functions, read responses, and handle errors.
  - [Streaming logs](/sdk/logs): Follow a job's logs over Server-Sent Events.
  - [End-to-end example](/sdk/example): Create a client, create a build, poll it, and stream its logs.
  - Reference
    - [Reference](/sdk/reference): Every public @harmont/cloud function, generated from the OpenAPI spec.
    - [Auth](/sdk/reference/auth): Generated @harmont/cloud reference for the Auth endpoints.
    - [Billing](/sdk/reference/billing): Generated @harmont/cloud reference for the Billing endpoints.
    - [Builds](/sdk/reference/builds): Generated @harmont/cloud reference for the Builds endpoints.
    - [Jobs](/sdk/reference/jobs): Generated @harmont/cloud reference for the Jobs endpoints.
    - [Organizations](/sdk/reference/organizations): Generated @harmont/cloud reference for the Organizations endpoints.
    - [Pipelines](/sdk/reference/pipelines): Generated @harmont/cloud reference for the Pipelines endpoints.
    - [User](/sdk/reference/user): Generated @harmont/cloud reference for the User endpoints.
- [Architecture](/architecture): How a pipeline becomes a running build, under the hood.