---
title: "Connect your app during development"
description: "Use the protocol client generated by a4 dev, keep wallets on the fork, and restore published dependencies before shipping."
editUrl: true
head: []
template: "doc"
sidebar: {"hidden":false,"attrs":{}}
pagefind: true
draft: false
---

> For the complete documentation index optimized for AI agents, see [llms.txt](https://docs.arete.run/llms.txt) or [llms-full.txt](https://docs.arete.run/llms-full.txt). A markdown version of this page is available at [/development/application.md](https://docs.arete.run/development/application.md) or by sending `Accept: text/markdown`.
Develop your application alongside `protocol.ts`. After each successful
release change, `a4 dev up` regenerates your protocol's client from the local
build and points it at the deployment in your cloud dev environment.

## Find the generated client

The client is written where `a4 install protocol` would put it:
`generated/<lang>/protocols/<alias>/`. Read its generated `README.md` for the
actual export and import path. There is no separate hand-maintained dev client.

Before the first publication, `a4 dev up` adds the protocol dependency to
`arete.toml`. After publication, it keeps the published pins in `arete.lock`
and marks the generated override with `local_build`. Use `a4 dev sdk --ts`
to regenerate explicitly; `[dev] sdk` selects targets for automatic generation.

The generated definition contains the dev deployment id. You do not need to
construct an endpoint or replace ids by hand. A new deployment means you must
reload code that imported the previous generated definition.

## Connect a server or script

Import the generated definition and call `createProtocolClient` from
`@usearete/sdk`. The [integration guide](/integrating-protocols/overview/)
shows the client setup and session alternative.

The private dev deployment needs your account's credentials. For scripts,
use `ARETE_API_KEY` or the CLI login as supported by the SDK. A restricted agent
credential does not substitute for an owner's access to the environment.
Never copy a secret into browser code.

## Connect a browser

Keep your frontend's public reads and public steps on an origin-bound
publishable key from the owning account. Use an authenticated backend for
`secret` steps. The scaffold's create and recipient-role steps default to
`secret`, so a frontend needs that backend path unless you deliberately
change the protocol's access model.

Point the browser wallet and chain client at the local RPC URL printed by
`a4 dev up`, normally `http://127.0.0.1:48700`. That endpoint forwards to
the hosted fork and handles its environment tokens. It must be running while
the wallet uses it. A local frontend on another loopback port can access it.

```ts
const connection = new Connection("http://127.0.0.1:48700", "confirmed");
```

This example uses `Connection` from `@solana/web3.js`. The protocol API and
chain RPC are different endpoints: do not point a protocol client at the RPC.
Fund the test wallet with `a4 dev fund <pubkey>` and keep its signing network
aligned with the environment.

## Inspect the same workflow from several surfaces

- The dev UI shows the session and its event feed.
- `a4 dev instance <id> --wallet <name>` reads state and permitted steps.
- `a4 stream --dev --instance <id>` follows protocol data.
- MCP protocol tools accept `dev: true` to target the project's deployment.
- React's protocol hooks follow the client supplied by your app.

The session file contains connection information and a stack session token.
Keep `.arete/dev/session.json` and token-bearing stream URLs private; do not
bundle them into a frontend or commit them.

## Return to published dependencies

```sh
a4 install --locked
a4 install --check
```

`--locked` restores the published client and removes the local-build override.
It fails if the protocol has never been published. `--check` fails while a
protocol client is marked `local_build`; run it in CI to catch accidental dev
clients. Neither command deploys the protocol or publishes a package.

[Production deployment →](/deploying-protocols/overview/) ·
[Full environment reference →](/cli/local-development/)