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

# Mock mode

> Run the full draft to insights loop with no real API calls by starting pendpost in mock mode.

Mock mode is the adoption unlock. Start pendpost with `PENDPOST_MODE=mock` and a stranger can run the complete pendpost loop, draft, approve, schedule, publish, and insights, with no credentials and no real platform traffic. Nothing leaves your machine.

## When mock mode is active

Mock mode is an explicit, global opt-in, not an automatic fallback:

* **live** (the default): with no `PENDPOST_MODE` set, every lane is live. A lane with no credential is live-but-unauthenticated; it waits for you to connect it and never fakes a publish, so nothing posts by accident.
* **mock**: set `PENDPOST_MODE=mock` to route every lane through the credential-free mock driver, regardless of which credentials are present.

So to explore the whole loop freely, start pendpost with `PENDPOST_MODE=mock`:

```bash theme={null}
PENDPOST_MODE=mock npx pendpost
```

## Where mock data lives

Mock mode never runs against your real workspace. With no `PENDPOST_ROOT` set, pendpost uses a private demo workspace in your temp folder (`pendpost-mock-<your user id>` under the OS temp directory) and fills it with the example Acme campaign on first start. Your real data, and the install folder, are never touched. Delete that folder to start the demo over.

If you set `PENDPOST_ROOT` yourself, it has to point inside your temp folder (for example `/tmp/pendpost-demo`), or pendpost refuses to start in mock mode. That fence exists because mock publishes write fake platform ids, which must never land in real client data.

> [!NOTE]
>
> On pendpost 2.8.0 and earlier, mock mode needs that `PENDPOST_ROOT` set explicitly, so use `PENDPOST_MODE=mock PENDPOST_ROOT=/tmp/pendpost-demo npx pendpost`. The command works on every version.

## What the mock driver does

The mock driver (`lib/drivers/mock-driver.mjs`) stands in for the real publish engines. Instead of calling a platform API, it:

* Fabricates post ids that look like real platform ids.
* Fabricates realistic metrics so the insights view has something to show.
* Records every action to a `.mock-ledger.json` under the active client's data root.

It covers every lane: the mock driver fabricates ids and metrics for all of them, so every platform (Facebook, Instagram, LinkedIn, X, YouTube, Telegram, Discord, Mastodon, WordPress, Ghost, Nostr, Reddit, Pinterest, TikTok, and Google Business Profile) is exercisable credential-free.

Because the mock driver records to the ledger, your runs are inspectable after the fact. The ledger is your audit trail for what the loop did while no real account was touched.

## The full loop

The same loop runs in mock and live; only the driver at the end differs. Walk it from the dashboard or from any MCP client (both drive the same contract).

**1. Draft**

Create a post. Every created post starts as a `draft`. The agent tool `plan_create_post` always creates a draft, never an approved post.

**2. Approve**

A human approves the draft with `approve_post`, flipping its approval state to `approved`. The actor who created a post cannot approve it (the owner is exempt). A post with no approval will not publish: the gate is fail-closed. You can also `reject_post`.

**3. Schedule**

Set the post's `scheduledAt`. Where a platform supports native scheduling, pendpost uses it. In mock, the scheduler tick drives the lane just as it would live.

**4. Publish**

On the scheduler tick (or on demand) the lane runs through the mock driver, which fabricates an id and records the publish to the ledger. No real API call is made.

**5. Insights**

Read back the fabricated metrics the mock driver produced. This exercises the same insights path you would use with real data.

## The example Acme campaign

So that the dashboard shows content on first run, pendpost ships an example `Acme Launch` campaign. A git checkout and the mock demo workspace both open on it; a fresh live workspace you point `PENDPOST_ROOT` at starts empty. It lives under `data/clients/default/data/plans/acme-launch/post-plan.json`, registered in that folder's `active-plans.json`.

The campaign includes a mix of states so you can see the gate at work right away:

* A LinkedIn text post in `draft` (created by an agent, awaiting approval).
* An Instagram and Facebook reel in `draft`.
* An Instagram reel already `approved` by the owner, ready to publish.

Everything in the example runs through the mock driver while you have `PENDPOST_MODE=mock` set: no real posting. Delete the `acme-launch` folder and its manifest entry once you start adding your own campaigns.

## The mock ledger

Every mock action is appended to a `.mock-ledger.json` in the active client's data folder, for the default client `data/clients/default/data/.mock-ledger.json`. Each client has its own ledger, so the audit trail stays isolated per client. This file is created at runtime and grows as you run the loop. Read it to confirm exactly what each step did, including the fabricated ids and metrics, without trusting the dashboard view alone.

> [!NOTE]
>
> Because mock mode never touches a real account, it is the safest place to learn the approval gate, the circuit breakers, and the brand-lint flow before you add any credentials.


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