Connect your app during development

For AI agents: the documentation index is at llms.txt (full corpus: llms-full.txt). A markdown source for this page is /development/application.md.

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

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

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 → · Full environment reference →