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

# Access modes and provider keys

> A run pays for its model with a credential you connect, either an API key (byok) or a subscription, and Pinework sets the access mode from the credential it picks.

An **access mode** says how a run pays for its model. In `byok` mode, the run spends an API key you added. In `subscription` mode, it spends a plan you already pay for, such as Claude or ChatGPT. A **provider key** is the saved credential behind either mode.

## The credential sets the access mode

You do not pick an access mode directly. Pinework picks a credential for each run. An API key makes the run `byok`. A subscription makes it `subscription`. Cursor is the exception: a Cursor API key also counts as `subscription`. Each run records its access mode and the provider key it used.

## A subscription comes in two kinds

A **device sign-in** is a harness you signed in to on your own machine. Claude Code's `/login` is one example. It stays on that machine. Only runs on that device use it.

A **saved subscription** is one you connect under **Settings** > **Providers** > **Connect a subscription**. You sign in on the provider's own site. Pinework stores the credential encrypted. It belongs to you alone. It is the only kind of subscription a cloud run can use.

```bash theme={null}
pinework provider login anthropic --browser
```

## An API key serves the whole workspace

You add an API key under **Settings** > **Providers** > **Your API keys**. Pick the **Provider**, paste the **API key**, and choose **Connect**. A workspace holds one active API key per provider. **Import from this device** copies the API keys OpenCode already stores on your machine.

```bash theme={null}
pinework provider set-key openai --api-key sk-...
```

## A subscription runs only through its own tool

A Claude subscription runs only through Claude Code. A ChatGPT subscription runs only through Codex. A Cursor subscription runs only through Cursor. Pinework refuses any other pairing. Using a consumer plan through another tool breaks the provider's terms.

Some harnesses cannot spend an API key in the cloud. Codex in the cloud needs a ChatGPT subscription.

## Pinework picks a credential in a fixed order

The model decides the provider. An agent with no model uses the workspace **Default model**.

On a device, Pinework tries three sources in order:

1. A harness signed in on that machine.
2. An API key that OpenCode holds on that machine.
3. The provider keys saved in the workspace.

A cloud run uses saved provider keys only. Among saved keys, subscriptions come before API keys. A saved subscription serves only agents its owner owns. With several subscriptions, Pinework spreads runs across them. It favors the one with fewer live runs and more allowance left.

In a conversation, the model picker can pin one account. Runs in that conversation then use only that account.

## A limit pauses the key, not your work

A short rate limit makes the run retry after a brief wait. A spent usage limit pauses the key until the limit resets. The **Providers** page shows `Paused until <time>` on that key. **Reopen now** lifts the pause early.

Pinework then moves the run to another connected account for the same provider, if one is free. The run shows "Moved from" one account to the other. With no free account, the run parks. It resumes on its own when the limit resets.

A key that stops working shows **Credential invalid**, **Credential expired** or **Credential revoked**. Remove it and connect it again.

## No credential means the run waits

A run with no usable credential does not start. It says what is missing, such as "No AI model is connected yet." Pinework retries a few times. After that, add a key and retry the run.

## Pinework sets no spend limit

Your provider bills your key or plan directly. Pinework does not cap what a run spends. These limits do exist:

* **Max turns** caps the turns in one run.
* **Max concurrent runs** caps how many runs one device takes at once.
* A run stops at a wall-clock ceiling just under 24 hours.

<CardGroup cols={2}>
  <Card title="Add a provider key" href="/guides/add-a-provider-key">
    Connect an API key or a subscription.
  </Card>

  <Card title="Run on your Mac" href="/guides/run-on-your-mac">
    Use the harness sign-in already on your machine.
  </Card>

  <Card title="Cloud and device" href="/concepts/cloud-and-device">
    Why a cloud run needs a saved credential.
  </Card>

  <Card title="Agents" href="/concepts/agents">
    Where the model and harness are set.
  </Card>
</CardGroup>


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