Title: Your first runner · Codemany docs
URL: https://codemany.com/docs/get-started/first-runner
Description: Point a workflow at Codemany with runs-on: [self-hosted, codemany], watch the job run on your machine, and what happens to the runner before and after each job.
All pages as Markdown: https://codemany.com/llms.txt

---

[Get started](https://codemany.com/docs#get-started)

# Your first runner

Once Codemany is set up, one line in a workflow sends its jobs to your machine. GitHub still schedules the jobs and shows the logs.

## Change one line

Set the job's `runs-on` to the labels Codemany's runners carry:

```
name: codemany-test
on:
  workflow_dispatch:
  push:
    branches: [main]
jobs:
  hello:
    runs-on: [self-hosted, codemany]
    steps:
      - uses: actions/checkout@v4
      - name: Hello from your Mac
        run: |
          echo "Runner:  $RUNNER_NAME"
          echo "macOS:   $(sw_vers -productVersion) ($(uname -m))"
```

Download it: [codemany-test.yml](https://codemany.com/codemany-test.yml). Push it to the default branch, or run it from the repo's Actions tab.

macOS

```
runs-on: [self-hosted, codemany]
```

Add `macOS` to keep a job on a Mac when Linux machines share the pool label.

Linux

```
runs-on: [self-hosted, Linux, codemany]
```

Keep `Linux` in `runs-on`: without it, a job can land on your Mac too.

GitHub gives a job to a runner that has every label it lists: see [Runner labels](https://codemany.com/docs/runner-labels).

No workflow handy? The sample above runs on a push to `main`, or from the repo's Actions tab.

## What happens on your machine

- **One runner per job.** For each runner, Codemany asks GitHub for a just-in-time registration. The runner takes exactly one job and exits. Its directory is wiped and a fresh runner registers.
- **Sized to the machine.** Each runner budgets 4 GB of memory, 15 GB of disk and 2 cores, with room kept for the system. `codemany capacity` prints how many fit, and why.
- **Several repos share the runners.** Each repo keeps a warm runner while there are runners to spare, and idle runners move to the repo whose jobs are waiting. Busy runners are never touched.
- **Jobs use your tools.** Xcode, Homebrew packages, Docker and so on: whatever is installed. See [Tools and caching](https://codemany.com/docs/runners/tools).

## Watch it run

The app lists workflows, runs, jobs and steps the way GitHub models them, with live step logs for jobs on your machine. From any browser on your network, open the dashboard at `http://codemany.local:8825`. In a terminal, `codemany status` shows the runners.

## If the job waits in queued

- **Labels.** Every label in `runs-on` must be on the runner. A typo, or a label only another machine has, keeps the job waiting.
- **All runners are busy.** New jobs wait on GitHub. Codemany lists them oldest first and highlights waits over 15 minutes.
- **Health.** `codemany doctor` checks the service, the licence, GitHub and the runners, one line each.

## Next

- Add more machines to [the fleet](https://codemany.com/docs/machines): a [Linux server](https://codemany.com/docs/machines/linux-server) or a [cloud machine](https://codemany.com/docs/machines/cloud).
- Decide how far jobs are kept apart: [Isolation](https://codemany.com/docs/runners/isolation).

[Previous Connect GitHub](https://codemany.com/docs/get-started/github)[Next How it works](https://codemany.com/docs/get-started/how-it-works)