> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blacksmith.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Machine definitions

> Let [code]smith run your tests before it opens a PR

> [!NOTE]
>
> Machine definitions are in private beta. [Join the waitlist](https://app.blacksmith.sh/machine-definitions).

## Overview

Every \[code]smith session starts in a fresh sandbox with your repository cloned but none of your toolchain installed: no pinned runtime, no package manager, no system packages or browsers your tests need. Without them, \[code]smith can write a change but often can't run it, so it learns whether the change works the way you would: push, wait for CI, read the failure, and try again.

![A \[code\]smith change timeline with and without a machine definition](https://mintcdn.com/blacksmith/fIh5FNAouRm6ygOj/images/embeds/machine-definitions-codesmith.png?fit=max\&auto=format\&n=fIh5FNAouRm6ygOj\&q=85\&s=329397f6d3abeb5d886a42944ebeb528)

**A \[code]smith change timeline with and without a machine definition**

A machine definition describes the machine your code needs, once: an Ubuntu base, x64 or ARM, the setup script your CI jobs keep repeating, and the environment variables they expect, with secrets kept secret. Blacksmith builds it into a machine image, and \[code]smith's sandbox starts from that image, so a session begins with your dependencies already installed. You don't have to write the definition from scratch: Blacksmith drafts one from what your recent jobs installed and what your workflows set up, and you review it before you publish it.

A few examples of what a session can do with one:

* In a Next.js storefront, change a checkout component and rerun the Playwright end-to-end suite, with Node 22, pnpm, Chromium, WebKit and the screenshot fonts already in place.
* In a Rust service, add a database migration and run `sqlx migrate` and `cargo nextest` on the pinned nightly toolchain.
* In a Python data pipeline, change a transform and run its tests on the right Python with uv and the Google Cloud SDK it calls.

## How it changes a session

Without a machine definition, CI is \[code]smith's only way to check its work, and every attempt costs a push and a full CI run. With one, it runs your test suite, linters and build in the sandbox before it opens a pull request, fixes what breaks, and hands you a PR that already passes.

When CI fails on a pull request, \[code]smith reproduces the failure in a sandbox that matches CI and tests its fix there, rather than guessing from the logs and pushing to find out.

## How it speeds up CI jobs

Setup steps cost the same on every job, so they add up fastest where you run the most jobs: a test suite split across 20 shards pays for the same installs 20 times. With a machine definition, each job starts on an image that already has its toolchain and goes straight to checkout, build and test.

Fewer downloads also mean fewer failures that have nothing to do with your code. Every package fetched from npm, PyPI, crates.io or an apt mirror is a chance for a rate limit or an outage to fail the job. When those packages are already in the image, a registry having a bad day doesn't block your merge.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.