# Docs - **Get started** - [Introduction](/docs): One build definition that runs the same way on your laptop, in CI and in a coding agent's sandbox. - [Why hammerkit](/docs/why-hammerkit): What hammerkit gives you that a plain task runner doesn't. - [Installation](/docs/installation): Install hammerkit, write a build file and run your first cached task. - [Getting started](/docs/getting-started): Short introduction to get started with your first build file - [Tutorial](/docs/tutorial): Build, test and cache a real Node + TypeScript project end to end. - [Concepts](/docs/concepts): The vocabulary you meet all at once when you start with hammerkit. - **Build** - Build file - [Build file](/docs/build-file): A summary of all build file configuration options - [Environment Variables](/docs/build-file/environment-variables): Environment variables come from three sources: the shell environment, .env files and values defined in the build file. - [References](/docs/build-file/references): References allow the usage of tasks defined in other build files. They can be used to split up tasks into separate files. - [Includes](/docs/build-file/includes): Includes are similar to references, with one key difference: the working directory. An included build file runs in the directory of the file that includes it. - [Caches](/docs/build-file/caches): Caches describe how a task decides if it can be skipped and where its results are stored. With pluggable backends the cache can be shared across machines and CI runs. - [Build file reference](/docs/build-file/reference): Every key the build-file schema accepts. - Task - [Task](/docs/task): A task is a piece of work with dependencies that reads input files and generates output files. - [Dependencies](/docs/task/dependencies): A task can depend on other tasks, which run first (unless they are cached). - [Needs](/docs/task/needs): A task can declare needs on services. Hammerkit starts the services and waits until they are ready before the task runs. - [Caching](/docs/task/caching): A task can be skipped if none of its inputs have changed. This saves a lot of time and resources. - [Container](/docs/task/container): A task can run inside a container. This improves cross-platform support for your build files and reduces the number of locally installed tools required to run your tasks. - [Running on Kubernetes](/docs/task/kubernetes): Run your tasks and services on a Kubernetes cluster instead of the local docker daemon by selecting an environment. - [Watching](/docs/task/watching): For tasks whose source files change frequently and should re-run on every change. - [Extending](/docs/task/extending): A task can be used as a base template and extended. This is intended to reduce duplicate task definitions. - Service - [Service](/docs/service): A service is a long-running process, such as a database, that a task needs in order to do its work. - [Container service](/docs/service/container) - [Kubernetes service](/docs/service/kubernetes) - Labels - [Labels](/docs/labels): Labels let you group and categorize your tasks. - **Guides** - Guides - [Local vs. container tasks](/docs/guides/local-vs-container): When a task should run in a container and when it should run on the host. - [Caching strategy in CI](/docs/guides/ci-caching): Reuse build results across CI runs — backends vs. store/restore. - [Agents, workspaces and CI](/docs/guides/agents-and-ci): Share one cache between coding-agent sandboxes, developer workspaces and CI, so work done in one place is never repeated in another. - [Services & networking](/docs/guides/services-networking): How tasks reach services — connection strings, ports and lifecycle. - [Monorepo layout](/docs/guides/monorepo): Lay out a multi-package repo with shared task templates and build order. - [Development workflow](/docs/guides/development-workflow): A tight local loop with watch, services and dependency-aware restarts. - AI agents - [Migrate your CI with a coding agent](/docs/llm): Let a coding agent rewrite your existing CI pipeline into a hammerkit build file, following a guide written for it. - [CI migration guide (for coding agents)](/docs/llm/migrate-ci): Step-by-step guide for a coding agent migrating an existing CI pipeline to hammerkit: inventory, build file, CI rewrite, verification, report. - [Recipes](/docs/recipes): Ready-made task templates for common tools. - **Reference** - CLI - [CLI](/docs/cli): All about the options that the hammerkit cli offers. - [Init](/docs/cli/init): Create a starter build file in the current directory. - [ls](/docs/cli/ls): Inspect the tasks and services available in a build file. - [Execute](/docs/cli/execute): Run the tasks in your build file. - [Up](/docs/cli/up): Start the services of your build file and keep them running. - [Down](/docs/cli/down): Stop services that were started with up. - [Explain](/docs/cli/explain): Explain why a task is a cache hit or a cache miss — without running anything. - [Graph](/docs/cli/graph): Print the build graph — tasks, services and their deps/needs — as mermaid or graphviz dot. - [Cache](/docs/cli/cache): Move cache entries between a machine and a remote cache without running anything, and inspect or prune what a cache holds. - [Store / Restore](/docs/cli/store-restore): Store and restore generated files and folders to speed up your CI. - [Package](/docs/cli/package): Bake your services and their build dependencies into self-contained Docker images and push them to a registry. - [Clean](/docs/cli/clean): Clear all generated files and folders to start from a clean state. - [Validate](/docs/cli/validate): Verify the build file is well-formed and spot mistakes early on. - [FAQ & Troubleshooting](/docs/faq): Common questions and the gotchas behind them. - **Project** - Release notes - [Release 1.4.0](/docs/release-blog/release-1.4.0) - [Release 1.5.0](/docs/release-blog/release-1.5.0) - [Release 1.6.0](/docs/release-blog/release-1.6.0) - [Release 1.7.0](/docs/release-blog/release-1.7.0) - Contribution - [Roadmap](/docs/contribution/roadmap) - [Secret managers (planned)](/docs/contribution/secret-managers) - [Release procedure](/docs/contribution/publish) - Architecture decisions - [Local cache with an explicit remote bridge (no read-through tier)](/docs/adr/0001-local-cache-with-explicit-remote-bridge) - [What participates in cache identity](/docs/adr/0002-cache-identity-participation) - [Container options must be runtime-portable](/docs/adr/0003-container-options-must-be-runtime-portable) - [Remote includes: git-only, mutable refs, cache-pinned, no lockfile](/docs/adr/0004-remote-includes-git-cache-pinned) - [Registry cache entries are single-layer OCI image manifests](/docs/adr/0005-registry-cache-single-layer-image-manifest) - [Cache identity is checkout-independent; runtime state is checkout-scoped](/docs/adr/0006-portable-cache-identity)