# Develop locally

Run a recipe on your machine, then test uncommitted edits in the cloud before you push.

`introspection local` runs your recipe in Pi with no login. Add
`introspection dev` when you need real bindings, connectors, or your app
calling the agent.

**You need:** a recipe ([Create a recipe](/build)); for `dev`, a login.

## 1. Run it locally

```bash
introspection local                                   # interactive Pi session
introspection local -p "Review order 1842."           # one prompt, then exit
introspection local --agent reviewer -p "Check this draft."
introspection local -p "Triage this." --mode json     # Pi's event stream
introspection local -- --help                         # everything after -- goes to Pi
```

| Flag | Effect |
| --- | --- |
| `-r, --runtime <NAME>` | Pick a runtime manifest when the repository has several. |
| `--agent <NAME>` | Run a non-default agent. |
| `-p, --print <PROMPT>` | Run one prompt and exit. |
| `--mode text\|json` | Final message or Pi's event stream. Requires `--print`. |
| `--work-dir <DIR>` | Where to look for `.introspection/`. |

With a prompt, `--print` ignores piped stdin (CLI 0.54.0 or later), so it never
waits for input in a script: `cat notes.txt | introspection local -p "Summarize."`
does not add the file to the prompt.

Local MCP endpoints come from `.pi/mcp.local.json` ([Connect an MCP server](/build/mcp#3-bind-it-locally)),
and Python is not built for you ([Use Python](/build/package#use-python)).
There is no file flag: put the file in your current directory and name it in
the prompt (`-p "Reconcile ./statement.xlsx against the ledger."`).

## 2. Serve edits to the cloud

```bash
introspection login
introspection dev --logs
```

`dev` uses your login and watches your files. It prints a link to chat with
the development recipe and the `tasks create` command for its runtime id. If
the repository has no runtime yet, it offers to create one.

## 3. Send a prompt

Open the printed link, or call the agent from your app with development
credentials. Development tasks at your current commit pick up your edits:

| You edited | Takes effect |
| --- | --- |
| A skill body or a script the agent runs | The next turn in the same task |
| `SYSTEM.md`, agent YAML, prompts, extensions, MCP declarations | A new task |
| `package.json` or a lockfile | A new task, after dependencies reinstall |
| `.introspection/*.yaml` | A new version only (commit and push) |

To test an upload the way your app sends it, run
`introspection tasks create --runtime-id <version-id> -e development --file @./statement.xlsx`
while `dev` runs.

## `dev` flags

| Flag | Effect |
| --- | --- |
| `--logs [LEVEL]` | Streams sandbox output here (default level `info`). |
| `--check-bindings` | Checks runtime and MCP binding readiness, then exits. |
| `--mcp NAME=URL` | Routes a declared MCP server to a process on your machine. Repeatable. |
| `--as NAME` | Names this machine as a development target (default: `INTROSPECTION_DEV_TARGET`, then your username). Set the same `INTROSPECTION_DEV_TARGET` in your app to route its tasks here. |
| `-r, --runtime` | Pick a runtime slug or id instead of resolving it from the repository. |

## Verify

The `--logs` output shows lines prefixed `[<task-id> <timestamp> stdout]`
after you send a prompt. `introspection open --task <task-id>` opens that
conversation in the dashboard.

## Limits

| Symptom or limit | Fix |
| --- | --- |
| `local` fails at startup on a missing package | Run `pnpm install` in the recipe first. |
| `local` uses the wrong model | Change the agent's `ai.model`; `-- --model` does not override it. |
| `dev_slot_conflict` | You already serve this runtime at this commit from another terminal or machine. Stop it; a crashed session's record expires within about a minute. Teammates on the same commit do not conflict. |
| A dev target in staging or production | Not supported. Use `--as` with development credentials only. |
| Others need to use your change | Open a pull request (it builds a preview version, see [Test before production](/ship/staging)) or merge. |

Or ask your agent: "Run my recipe locally with a refund question, then start introspection dev --logs."

Develop locally

Run a recipe on your machine, then test uncommitted edits in the cloud before you push.

introspection local runs your recipe in Pi with no login. Add introspection dev when you need real bindings, connectors, or your app calling the agent.

You need: a recipe (Create a recipe); for dev, a login.

1. Run it locally


introspection local                                   # interactive Pi session
introspection local -p "Review order 1842."           # one prompt, then exit
introspection local --agent reviewer -p "Check this draft."
introspection local -p "Triage this." --mode json     # Pi's event stream
introspection local -- --help                         # everything after -- goes to Pi

Flag	Effect
`-r, --runtime <NAME>`	Pick a runtime manifest when the repository has several.
`--agent <NAME>`	Run a non-default agent.
`-p, --print <PROMPT>`	Run one prompt and exit.
`--mode text\|json`	Final message or Pi’s event stream. Requires `--print`.
`--work-dir <DIR>`	Where to look for `.introspection/`.

With a prompt, --print ignores piped stdin (CLI 0.54.0 or later), so it never waits for input in a script: cat notes.txt | introspection local -p "Summarize." does not add the file to the prompt.

Local MCP endpoints come from .pi/mcp.local.json (Connect an MCP server), and Python is not built for you (Use Python). There is no file flag: put the file in your current directory and name it in the prompt (-p "Reconcile ./statement.xlsx against the ledger.").

2. Serve edits to the cloud


introspection login
introspection dev --logs

dev uses your login and watches your files. It prints a link to chat with the development recipe and the tasks create command for its runtime id. If the repository has no runtime yet, it offers to create one.

3. Send a prompt

Open the printed link, or call the agent from your app with development credentials. Development tasks at your current commit pick up your edits:

You edited	Takes effect
A skill body or a script the agent runs	The next turn in the same task
`SYSTEM.md`, agent YAML, prompts, extensions, MCP declarations	A new task
`package.json` or a lockfile	A new task, after dependencies reinstall
`.introspection/*.yaml`	A new version only (commit and push)

To test an upload the way your app sends it, run introspection tasks create --runtime-id <version-id> -e development --file @./statement.xlsx while dev runs.

`dev` flags

Flag	Effect
`--logs [LEVEL]`	Streams sandbox output here (default level `info`).
`--check-bindings`	Checks runtime and MCP binding readiness, then exits.
`--mcp NAME=URL`	Routes a declared MCP server to a process on your machine. Repeatable.
`--as NAME`	Names this machine as a development target (default: `INTROSPECTION_DEV_TARGET`, then your username). Set the same `INTROSPECTION_DEV_TARGET` in your app to route its tasks here.
`-r, --runtime`	Pick a runtime slug or id instead of resolving it from the repository.

Verify

The --logs output shows lines prefixed [<task-id> <timestamp> stdout] after you send a prompt. introspection open --task <task-id> opens that conversation in the dashboard.

Limits

Symptom or limit	Fix
`local` fails at startup on a missing package	Run `pnpm install` in the recipe first.
`local` uses the wrong model	Change the agent’s `ai.model`; `-- --model` does not override it.
`dev_slot_conflict`	You already serve this runtime at this commit from another terminal or machine. Stop it; a crashed session’s record expires within about a minute. Teammates on the same commit do not conflict.
A dev target in staging or production	Not supported. Use `--as` with development credentials only.
Others need to use your change	Open a pull request (it builds a preview version, see Test before production) or merge.

Or ask your agent: “Run my recipe locally with a refund question, then start introspection dev —logs.”