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

# Run agents on your Mac

> Install the Pinework Mac app, sign in so your Mac becomes a device, register a folder and point an agent at it, so its runs edit your local files.

**Running on your Mac** means an agent's runs happen on your own machine, inside a folder you pick. The Pinework Mac app connects your Mac to your workspace as a device. The agent then works on that folder with the harnesses installed on your Mac.

## Before you start

* A Mac with Apple silicon (M1 or later) and macOS 13.0 or later.
* A Pinework account.
* At least one harness installed and signed in on the Mac: Claude Code, Codex, Cursor or OpenCode.
* An agent. See [Create an agent](/guides/create-an-agent).

## Connect your Mac and pick a folder

<Steps>
  <Step title="Download and install the app">
    In the dashboard, open your account menu and click **Download desktop app**. On the download page, click **Download for macOS**.

    Open the downloaded disk image. Drag **Pinework** onto **Applications**, then open Pinework from Applications.
  </Step>

  <Step title="Sign in">
    Sign in with the same account you use on the web.

    **Continue with Google** opens your browser. When the browser shows **Signed in to Pinework**, return to the app.

    Signing in connects the Mac. There is nothing else to install.
  </Step>

  <Step title="Check that your Mac is connected">
    Open **Settings** from your account menu. Under **Connections**, click **Connected devices**.

    Your Mac appears under **Device managers** with a **This device** badge. The Pinework icon in the menu bar shows **Status: Connected**.

    Each harness on the Mac shows **Ready**, **Needs attention** or **Not installed**. **Needs attention** means the harness is installed but not signed in.

    The first device you connect becomes the workspace's default device.
  </Step>

  <Step title="Register a folder">
    On the same page, find **Folders** and click **Add folder**. The **Register local folder** dialog opens.

    * **Device**: your Mac. The Mac app selects it for you.
    * **Folder**: click **Choose folder…** and pick the folder in Finder.
    * **Display name**: filled in from the folder name. Edit it if you like.

    Click **Register**. The folder appears under your Mac in the **Folders** list.

    The web dashboard has no folder picker. There you type an **Absolute path** instead.
  </Step>

  <Step title="Set the repo the folder holds">
    This step is optional. Skip it if the folder is not a clone of a connected GitHub repo.

    In the folder's row, pick the repo. A run on this Mac for that repo then starts in this folder. Leave the row at **None** otherwise.
  </Step>

  <Step title="Point an agent at the folder">
    Open the agent's page on the **Configure** tab. In the **Runtime** section, open **Runs on**.

    Under **On a device**, pick your folder. It shows your Mac's name and the folder path. **Home · no project files** starts runs in your home folder instead.

    Click **Save changes**.
  </Step>

  <Step title="Give the agent work">
    [Assign a task](/guides/assign-a-task) or [message the agent](/guides/message-an-agent).

    The run starts on your Mac. The menu bar shows **Status: 1 agent(s) running** while it works.
  </Step>
</Steps>

<Warning>
  The agent edits the files in the folder itself. Pinework does not copy the folder first. Two agents on one folder can overwrite each other's edits. Commit your own work before a run starts.
</Warning>

<Note>
  On a new workspace, the app first offers to import your coding tool setup. See [Import your setup](/guides/import).
</Note>

The Mac app also puts the `pinework` command on your PATH. You can register folders from Terminal while the app is running:

```bash theme={null}
pinework folder add my-app /Users/you/code/my-app
pinework folder list
pinework folder set-repo <FS_…> <repo-id>
```

`pinework folder add` registers the folder on the Mac you run it on. `pinework folder list` shows each folder's short id, which starts with `FS_`.

## Set how many runs your Mac takes at once

Each Mac takes up to 3 runs at once by default. Extra runs wait and show **At capacity**.

To change the limit, open the device's **More actions** menu and click **Edit max runs**. Or run this on the Mac:

```bash theme={null}
pinework device set --max-concurrent 2
```

The CLI accepts a value from 1 to 10.

## Keep your Mac available

Closing the window does not stop Pinework. The app stays in the menu bar and keeps taking runs. **Quit Pinework** in the menu bar menu stops it.

A run for an offline Mac waits and shows **No device available**. It starts when the Mac connects again.

To start the device manager at login without opening the app, run:

```bash theme={null}
pinework device install-service
```

A Mac offline for 7 days shows **Retired**. Sign in on that Mac again to reconnect it.

You can get a notification when a run waits for an offline device. It is off by default. Turn it on in **Settings** under **Notifications**.

## Troubleshooting

**The menu bar shows Sign in to connect.** Sign in in the app. The device manager then starts by itself.

**The menu bar shows Not running or Disconnected.** Open the menu bar menu and click **Start Device Manager**.

**Runs go to a different Mac.** A device run goes to the agent's own device if it has one. Otherwise it goes to the workspace's default device. On the right Mac's row in **Connected devices**, open **More actions** and click **Set as default device**.

**A harness shows Needs attention.** Sign in to that harness on the Mac. Pinework checks again on its own. To check right away, run `pinework device refresh`.

<CardGroup cols={2}>
  <Card title="Mac app" href="/apps/mac">
    What the app adds beyond the web dashboard.
  </Card>

  <Card title="Cloud and device" href="/concepts/cloud-and-device">
    How Pinework decides where a run happens.
  </Card>

  <Card title="Connect a GitHub repo" href="/guides/connect-github">
    Link a repo to a folder, or run it in the cloud.
  </Card>
</CardGroup>


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