---
sidebar_position: 3
title: 3. Run it locally
pagination_prev: get-started/your-first-workflow
pagination_next: get-started/deploy
---

# Run an agent locally

```bash
zibby agent run my-agent
```

One-shot: loads `graph.mjs`, instantiates your `WorkflowAgent` class, runs the graph against a real agent, prints results, exits. Output lands in `.zibby/output/sessions/<sessionId>/`:

- `result.json` — the final structured output (Zod-validated)
- `raw_stream_output.txt` — every byte the agent emitted
- `events.json` — JSONL execution log: which node ran when, what it received, what it returned, retries
- `.session-info.json` — session metadata

The flag surface mirrors `zibby agent trigger` (cloud) on purpose: the call you make locally is the same call you make against the cloud, just with the verb flipped.

## Pass input

Most agents take input. Edit `graph.mjs` to define an input schema and reference `state.input`:

```js
graph.addNode('plan', {
  prompt: ({ input }) => `Triage this ticket: ${input.ticket}`,
  outputSchema: z.object({ tasks: z.array(z.string()) }),
  agent: 'claude',
});
```

Then pass input via `--input`:

```bash
zibby agent run my-agent --input '{"ticket":"BUG-123"}'
```

Or `--param key=value` (repeatable, dot-notation supported):

```bash
zibby agent run my-agent -p ticket=BUG-123 -p priority=high
zibby agent run my-agent -p user.name=Alice -p user.role=admin
```

Or `--input-file payload.json` for larger payloads.

Precedence: `--param` > `--input` > `--input-file`. Same as `trigger`.

## Iterating

Each run is a fresh process — re-edit `graph.mjs` or any node file and re-run. There's no daemon to restart; tool errors and crashes don't leave a server hanging on port 3848.

If you want auto-rerun on file change, run it under `nodemon`:

```bash
npx nodemon --ext mjs,js --exec "zibby agent run my-agent -p ticket=BUG-123"
```

Or add it to your agent's `package.json`:

```json
{
  "scripts": {
    "dev": "nodemon --ext mjs,js --exec \"zibby agent run my-agent\""
  }
}
```

Then `npm run dev`.

## Inspect a run

After a run finishes, the CLI prints the session ID. Open the session folder to inspect every step:

```bash
ls .zibby/output/sessions/<sessionId>/
cat .zibby/output/sessions/<sessionId>/result.json | jq
```

## Studio (long-lived server, optional)

Studio is a desktop UI for browsing live + past runs. It connects to a local HTTP server, so when you use Studio you start that instead:

```bash
zibby agent start my-agent   # long-lived server on :3848 (Studio talks to this)
zibby studio                       # launch the desktop app
```

For CLI-only iteration, stick with `zibby agent run`.

→ Next: [Deploy to cloud](./deploy)