Environments

An environment is where an agent loop or tool runs. Pick one based on what the code needs: your app's database connection, a workspace with files, or a browser.

Use your app and Brain together

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

tools: [lookupOrder()],

To be explicit, pass { env: brainEnv({ name: "brain" }) } to Pi. name identifies the environment within the session. Reuse an environment when tools should share a workspace or resources, and use separate ones when they need separate access.

Application functions run with your process's existing permissions and working directory; a named hostEnv does not isolate them. Keep the process alive while its tools are needed. 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 your ordinary Tool declarations and finish with await ctx.finish(value) inside the request. The extension handles delivery and completion, but it doesn't keep application work alive after the request ends.

Run a tool in the user's page

Choose clientBrowser({ name: "editor" }) for a tool like "read the current selection". It reuses the existing host connection: create the session with sessions.create() as usual, and the SDK opens its command stream and sends results for you. Closing the page makes its tools unavailable; the stored session stays. A page that only displays session progress doesn't need an execution Environment.

clientBrowser runs in the user's existing tab, while the Browser extension below drives a separate automation browser. Browser apps still need server-authorized access: this factory does not make account or model-provider secrets safe in frontend code.

Use a browser or sandbox

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

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

Plan for resource lifetime

• Setup is automatic by default. Environments use the automatic lifecycle for ordinary setup and cleanup. Set environment.lifecycle to 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. Control environments covers the combinations and grants.
• Failures stay contained. Keep the Agentloop and durable session outside disposable execution environments. When a sandbox fails, its tools may stop while the loop can still read the failure and request authorized repair. An Env can also report the loss of a single browser tab or job without marking its whole runtime unavailable.
• Files live as long as their environment. Your app must stay connected for its hostEnv tools to work, and sandbox and browser files follow their environment's lifetime. Save important business data in your own storage; session history doesn't restore a lost browser or sandbox.
• brainEnv is locked down. It denies file, network and secret access by default, and server settings bound any access you request. See environment settings for grants, limits and cleanup.

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