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.mdto the URL or sendingAccept: 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.
Run the app in dev mode
Section titled “Run the app in dev mode”Start the environment, then run the app with a4 dev run:
a4 dev up # in one terminal; it keeps runninga4 dev run -- npm run dev # in anothera4 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.
| Setting | Means |
|---|---|
unset, or production | production, exactly as installed |
ARETE_ENVIRONMENT=dev + ARETE_DEV_URL | dev, through the edge (browsers, local apps) |
ARETE_ENVIRONMENT=dev + ARETE_DEV_ENV | dev, 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”| Surface | In dev mode |
|---|---|
| Chain reads and transactions | the environment’s fork |
| Program account reads | the fork, decoded with the installed program release |
| Stacks | the environment’s copy of each installed stack |
| Your protocol | the environment’s deployment, which a4 dev up keeps current |
| Types | unchanged: 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:
| Code | Means | Fix |
|---|---|---|
devenv-not-configured | dev mode, but no edge or environment | run with a4 dev run, or set ARETE_DEV_ENV |
devenv-edge-unreachable | nothing answers as the edge | start a4 dev up |
devenv-stack-not-loaded | the environment has no copy of the stack | a4 dev up loads every stack in arete.lock |
devenv-program-release-mismatch | the environment runs a changed program with no registered release | run a4 dev up with the program’s local IDL, or reset the environment |
devenv-protocol-not-deployed | the environment has no deployment of the protocol | run a4 dev up in the protocol’s project |
devenv-protocol-not-owned | another account’s protocol | call it in production |
devenv-surface-unavailable | the environment can’t serve this surface | named per case |
environment-token-refused | a production object, or another environment’s | unset the switch to use it in production |
Show dev-only features only in dev
Section titled “Show dev-only features only in dev”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).
One project per environment
Section titled “One project per environment”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: trueto 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.
Ship it
Section titled “Ship it”a4 dev promote --check # what exists only in the environmenta4 install --locked # back to the published pinsa4 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”.