Skip to content

Arete documentation

Develop your app against a dev environment

For the complete documentation index optimized for AI agents, see llms.txt or llms-full.txt. A markdown version of this page is available by appending .md to the URL or sending Accept: text/markdown.

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.

Your app uses the SDKs you installed with a4 install: programs, stacks and protocols. One switch decides where they go:

  • Production (the default): the generated files exactly as installed.
  • Dev: your project’s cloud dev environment, a fork of mainnet. The same generated files read and send through the fork, read program accounts against it, stream the environment’s stacks and call the environment’s deployment of your protocol.

Nothing is regenerated for the switch, and no generated file contains a dev URL. The app you develop is the app you ship.

Start the environment, then run the app with a4 dev run:

Terminal window
a4 dev up # in one terminal; it keeps running
a4 dev run -- npm run dev # in another

a4 dev run sets ARETE_ENVIRONMENT=dev and ARETE_DEV_URL, the edge a4 dev up serves on 127.0.0.1. The edge holds your key and attaches every token itself, so the app needs no Arete credential at all.

Browsers read no process variables, so a4 dev run also sets copies under the prefixes browser frameworks expose (VITE_, NEXT_PUBLIC_, EXPO_PUBLIC_). Pass them to the client:

const environment =
import.meta.env.VITE_ARETE_ENVIRONMENT === "dev"
? { kind: "dev" as const, url: import.meta.env.VITE_ARETE_DEV_URL }
: "production";
<AreteProvider environment={environment}>…</AreteProvider>

Set the prefixes your framework uses in arete.toml:

[dev]
public-env-prefixes = ["VITE_"]

Servers, scripts and tests outside a browser read ARETE_ENVIRONMENT themselves. CI and agents with a secret key can skip the edge: set ARETE_ENVIRONMENT=dev and ARETE_DEV_ENV=<environment name or id>, and the SDKs resolve the environment’s targets directly.

SettingMeans
unset, or productionproduction, exactly as installed
ARETE_ENVIRONMENT=dev + ARETE_DEV_URLdev, through the edge (browsers, local apps)
ARETE_ENVIRONMENT=dev + ARETE_DEV_ENVdev, direct (servers and CI with a secret key)

A client decides once, when it’s created, and client.environment says which: 'production' or 'dev'.

What changes in dev mode, and what doesn’t

Section titled “What changes in dev mode, and what doesn’t”
SurfaceIn dev mode
Chain reads and transactionsthe environment’s fork
Program account readsthe fork, decoded with the installed program release
Stacksthe environment’s copy of each installed stack
Your protocolthe environment’s deployment, which a4 dev up keeps current
Typesunchanged: they follow the installed SDKs

Browser wallets sign only: their own RPC is mainnet, so the SDK sends the signed transaction through the environment itself. An adapter that can only sign-and-send is refused with devenv-wallet-send-unsupported.

a4 dev up loads every registry stack in arete.lock into the environment. An environment’s stacks start empty: a stack streams only the accounts the environment touches from the slot it was loaded at, and a4 dev status names that slot. Read current program state through program reads (always complete), and use stacks for what changed. To put an account into a stack, touch it with a transaction or a scenario.

When the environment can’t serve something

Section titled “When the environment can’t serve something”

The SDKs never fall back to production. A surface the environment can’t serve fails with a code and a fix:

CodeMeansFix
devenv-not-configureddev mode, but no edge or environmentrun with a4 dev run, or set ARETE_DEV_ENV
devenv-edge-unreachablenothing answers as the edgestart a4 dev up
devenv-stack-not-loadedthe environment has no copy of the stacka4 dev up loads every stack in arete.lock
devenv-program-release-mismatchthe environment runs a changed program with no registered releaserun a4 dev up with the program’s local IDL, or reset the environment
devenv-protocol-not-deployedthe environment has no deployment of the protocolrun a4 dev up in the protocol’s project
devenv-protocol-not-ownedanother account’s protocolcall it in production
devenv-surface-unavailablethe environment can’t serve this surfacenamed per case
environment-token-refuseda production object, or another environment’sunset the switch to use it in production

Fund buttons, dev wallets and test faucets belong in dev builds only. Gate them on the client, never on a URL or a deployment id:

if (client.environment === "dev") {
// fund button, dev wallet picker, …
}

Load dev-only code lazily behind that check, so production clients never load it. A bundler can still emit the lazy chunk; to keep the code out of the production build entirely, put it behind a build-time check as well (for example import.meta.env.DEV in Vite).

An environment serves one project at a time. a4 dev up holds a lease on it while it runs. A second project gets devenv-environment-leased with the holder’s name; run it in its own copy with a4 dev branch, or take the environment over with a4 dev up --take-over. A takeover removes the first project’s deployments and overrides, and the first a4 dev up stops.

Your plan’s dev tier sets how many stacks an environment holds. a4 dev up checks before it loads any: when the lock needs more than remain, it lists each stack and stops. a4 auth whoami and a4 doctor show the dev tier.

Inspect the same workflow from several surfaces

Section titled “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.

.arete/dev/session.json names the edge (edgeUrl) and holds no key or token. Keep it out of version control anyway: it names your environment.

Terminal window
a4 dev promote --check # what exists only in the environment
a4 install --locked # back to the published pins

a4 dev promote --check lists each thing your app uses that production doesn’t have yet, with the command that publishes it: a protocol client from a local build (a4 protocol deploy), a local SDK extension, a program the environment runs at another release, a project stack under a dependency’s alias. It exits non-zero while any remain, so CI can gate a deploy on it.

When it’s clean, run a4 install --locked and deploy the app with ARETE_ENVIRONMENT unset. A protocol client with no production deployment yet fails in production with “not deployed to production yet”.

Production deployment → · Full environment reference →