Skip to main content
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.

​
Connect your Mac and pick a folder

1

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.
2

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.
3

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.
4

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.
5

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.
6

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.
7

Give the agent work

Assign a task or message the agent.The run starts on your Mac. The menu bar shows Status: 1 agent(s) running while it works.
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.
On a new workspace, the app first offers to import your coding tool setup. See Import your setup.
The Mac app also puts the pinework command on your PATH. You can register folders from Terminal while the app is running:
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:
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:
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.

Mac app

What the app adds beyond the web dashboard.

Cloud and device

How Pinework decides where a run happens.

Connect a GitHub repo

Link a repo to a folder, or run it in the cloud.