Run tools in the user’s browser tab

Authorize one composition

Authenticate your application user before issuing scoped access for an exact HTTPS frontend origin. Local HTTP origins are supported for development.

const descriptor = { name: "selection", description: "Read selected text", input_schema: { type: "object", properties: {}, additionalProperties: false } };
const access = await aex.clients.grant({
  origin: "https://your-app.example", tools: [descriptor],
  session: {
    harness: "pi", config: { model: "openai/gpt-4.1-mini", tools: [] },
    model_credential: { api_key: process.env.OPENAI_API_KEY },
  },
});
// Return only access to your authorized frontend, with Cache-Control: no-store.

Attach from the tab

import { Aex, Tool } from "@aexhq/sdk";
const client = new Aex({ clientAccess: access });
const tools = [Tool({ ...descriptor, run: () => window.getSelection()?.toString() ?? "" })];
button.addEventListener("click", () => {
  client.attachTab({ create: { ...access.session, runtime_tools: tools } }).then(attached => {
    // Use attached.session; await attached.detach() to disconnect.
  });
});

Create within five minutes. The model credential stays private and is absent from the grant response. A backend restart before creation requires fresh authorization.

After creation, read await client.clients.composition() for its bound session. A later user gesture explicitly calls client.attachTab({session:id,tools}). An uncertain creation is never silently repeated.

Disconnect and revoke

Use detach() or client.close() explicitly. Closing the tab removes callbacks and keeps the session. There is no automatic idle disconnect or hidden callback replay. Grant expiry, parent-key revocation and account suspension deny reconnects and close active streams.

Use an Application endpoint for backend work, or an account-authorized managed remote browser for automation. See the browser guide.