Skip to main content
An agent is a named teammate in your workspace that runs on a model and follows your instructions. This guide creates one and sets its model, access mode and instructions.

​
Before you start

  • You have a Pinework workspace and can sign in to the dashboard.
  • For the CLI tab, you have run pinework login.
  • The agent can run somewhere. That means a Mac with a signed-in harness such as Claude Code, or a provider key for cloud runs. See Add a provider key or subscription.

​
Create the agent

1

Open the new agent form

Click Agents in the sidebar, then click New agent. The New agent page opens.
2

Fill in the identity

Under Identity, type a Name and pick a Role. Both are required. Reports to is optional.
3

Pick where it runs

Under Execution, pick a Harness: Claude, OpenCode, Cursor or Codex. Then pick Device or Cloud. Device runs on your own computer with your local CLI. Cloud runs in Pinework’s cloud sandbox.
4

Describe what it is for

Write a Description. You and Pinework read it to pick an agent for a piece of work. It gives the agent no extra access.
5

Hire it

Click Hire agent. You see an “Agent created” toast. The agent’s page opens on the Configure view.

​
Set the model

A model set on the task, the conversation or the routine wins first. Next comes the model you set on the agent. Without one, the agent uses the workspace Default model. With no default, Pinework picks the best ready route. A Cursor or Codex agent skips both steps. Without its own model, it runs on that harness’s own default model.
1

Open the model picker

On the agent’s Configure view, find the Runtime section. Click the control on the Model row, then open Model.
2

Pick a model

Search with Search models… and click a model. Each model shows how it will run, such as “via Claude Code · Subscription”. The Effort row sets how hard the model thinks.
3

Save

Click Save changes in the bar at the bottom. You see “Saved just now” next to the view switcher.
Fallback model on the same section names a second model. Leave it on Workspace default if you have no preference.

​
Choose the access mode

The access mode says how a run pays the model vendor. It is subscription (shown as Subscription) or byok (shown as API key). You do not type it in. Pinework picks it at the start of each run from what you have connected.
  • On a device, a harness signed in on that computer goes first. It counts as a subscription.
  • Among the credentials saved in Pinework, a subscription goes before an API key.
  • A saved subscription serves only agents owned by the person who saved it. You own the agents you create.
  • An API key serves every agent in the workspace.
To steer the choice, open the model picker. When a model has more than one route, click the icon stack at the end of its row. The list shows each route, such as “Claude Code · Subscription” or “Claude Code · API key”. Click a ready route to pin its harness. The access mode still follows the order above. A route that is not ready shows its state, such as “Add API key”. To connect a key or a subscription, see Add a provider key or subscription.

​
Write the instructions

An instruction is the agent’s standing guidance. It reaches the agent at the start of every run. Each agent has one instructions file, AGENT.md, plus any number of named rules.
1

Open AGENT.md

In the Instructions section, click the AGENT.md row. The Instructions dialog opens.
2

Write it

Write it the way you would brief a new teammate. Click Done, then click Save changes. The row shows the first line of what you wrote and its token count.
3

Add a rule (optional)

Click New rule. Type a Name, such as never-force-push, and the Rule text. Click Save. The rule appears under the agent’s own rules.
Workspace rules in the same section apply to every agent. To turn one off for this agent, open its menu and click Disable for this agent.

​
Troubleshooting

The model control reads “No model on the agent, no workspace default, and no ready route.” A Cursor or Codex agent shows this hint whenever it has no model of its own. It still runs on the harness’s default model. On any other agent, nothing can run it yet. Connect a provider key or subscription, or sign in to a harness on your Mac. A model shows “Add API key → set up” or “Add subscription → set up”. The vendor has no credential that this agent can use. Add one on the Providers settings page, then pick the model again.

Assign a task

Hand your new agent its first piece of work.

Rules and instructions

How workspace, project and agent rules combine.