Environments

An environment is where an agent loop or tool runs. Choose it according to what the code needs: your application's database connection, a workspace with files, or a browser.

Use your application and Brain together

In the quickstart, the loop runs on Brain and the lookup runs in your app:

agentloop: pi(),
tools: [lookupOrder()],

For explicit placement, pass { env: brainEnv({ name: "brain" }) } to Pi. name identifies the environment within that session. Reuse an environment when tools should share its workspace or resources. Use separate environments when they need separate access.

Application functions have the process's existing permissions and working directory; a named hostEnv does not isolate them. Keep that process alive while its tools are needed; session connection settings control when idle tools disconnect and how later work reconnects. For short-lived app requests, the Application tool extension lets Brain call a separately deployed endpoint. Reuse ordinary Tool declarations and finish with await ctx.finish(value) within the request. The extension handles delivery and completion; it does not keep application work alive after the request ends.

Run a Tool in the user's page

Select clientBrowser({ name: "editor" }) for a Tool such as reading the current selection. It uses the existing host connection. Create the session with sessions.create() as usual; the SDK opens its command stream and sends results automatically. Closing the page makes its Tools unavailable while the stored session remains. A page that only displays session progress does not need an execution Environment.

clientBrowser runs in the existing tab. The Browser extension below runs a separate automation browser. Browser applications also need server-authorized access; the factory does not make account or model-provider secrets safe to put in frontend code.

Use a browser or sandbox

The official extensions include a Docker workspace, browser actions and Modal sandboxes. Follow the chosen package's setup guide; declaring an environment in your app does not deploy its service.

Standalone Brain can connect to your own environment service. For hosted availability and setup, see the Aex docs.

Plan for resource lifetime

Environments use automatic lifecycle for ordinary setup and cleanup by default. Set environment.lifecycle to choose manual when an authorized caller should configure and set up a binding first. Separately, include the ordinary env Tool if the model should inspect or manage environments. See Control environments for the combinations and grants.

Keep the Agentloop and durable session outside disposable execution environments. When a sandbox fails, its tools may stop while the loop remains able to read failures and request authorized repair. An Env can also report the loss of an individual browser tab or job without marking its entire runtime unavailable.

Your app must stay connected for its hostEnv tools to work. Sandbox and browser files follow their environment's lifetime, so save important business data in your own storage. Saved session history does not restore a lost browser or sandbox.

brainEnv denies file, network and secret access by default. Server settings bound any access you request. See environment settings for grants, limits and cleanup behavior.

To connect a runtime of your own, follow Write an environment.