Portals

Portals are embedded windows that live right on your canvas. A browser portal lets you browse websites and preview local files. A device portal runs a real iOS or Android device. In both cases, your AI agents can interact with what's inside them directly.

Creating a portal

Click the Portal button in the toolbar (globe icon) or press P to add a new portal to your canvas. Enter a URL — any website like https://example.com.

Each portal runs an isolated WebKit (Safari) instance with its own storage. Chrome support is planned for the future.

Connecting portals

You can connect a portal to another portal so they share the same storage session. This is useful when one portal needs to access cookies or authentication state from another.

Use the connection tool to link portals together, just like all other nodes on the canvas.

Agent automation

When a portal is connected to an agent's terminal, the agent can control it programmatically using the maestri CLI. No external dependencies, no MCP servers, no configuration — just connect and go. Like everything in Maestri, it's plug and play.

Portal automation is a custom-designed browser-use tool built for speed and token efficiency. Agents can:

• Click, type, and scroll — interact with any element on the page
• Navigate — go to URLs, go back, refresh
• Take screenshots — see the page visually, just like you do
• Run JavaScript — execute custom scripts in the page context
• Read the DOM — inspect the page structure
• See the browser console — catch errors and debug output

Agents can also create new portals on their own — they don't need you to place one manually.

To allow an agent to control a portal, connect them using the connection tool. Agents can see chained portals and control all of them.

Device portals

A portal can hold a mobile device instead of a web page: an iOS Simulator, an Android emulator, or a physical Android phone plugged into your machine. It's the same node, with the same connections and the same agent automation, so everything you already know about portals still applies.

Opening a device

Open the New Portal sheet and switch to Devices, or use the @New Device Portal action in the Prompt Composer.

You'll see every simulator, emulator, and phone your machine can drive, grouped by OS version, with a search field and filters for iOS, iPadOS, and Android. Already-running devices are marked as Booted. Pick one and Maestri boots it if needed, connects it, and places it on your canvas.

Need a device you don't have yet? New iOS Simulator… creates one from a searchable model list without leaving Maestri. Android emulators are created and deleted in Android Studio's Device Manager, and a physical Android phone shows up as soon as it's plugged in.

Device portals run on a device runtime built from scratch. The portal draws the device's own display buffer straight to the GPU and sends your clicks and keystrokes through the device's native input pipeline, so it stays as smooth and immediate as the device itself instead of crawling through screenshots and shell commands.

Several device portals can run at once, and each one survives workspace and floor switches. Two portals pointing at the same device share one screen, so reach for a second device when you want to run two apps side by side.

Driving a device by hand

Click into a device portal to control it directly with your mouse and keyboard: click to tap, type to send keystrokes, drag to swipe, and click and hold for a long press. Rotate the device to switch between portrait and landscape. These gestures work the same way on Android devices as they do on iOS.

Automating a device

Connect a device portal to an agent's terminal and the agent drives it with the same maestri CLI. No XCUITest, no Appium, no extra tooling. Instead of the DOM, agents read the running app's real element tree, with true labels and exact positions, so a tap lands on the button rather than a guessed coordinate. Agents can:

• Tap, type, scroll, and swipe anywhere on screen
• Press hardware buttons like home, lock, and side, plus Android's back and recents keys
• Launch and terminate apps by bundle id or package name
• Open URLs through the device's own URL handler
• Read the element tree, including any web view embedded in the app
• Take screenshots, and boot or shut down the device

Embedded web content joins the same element tree, so an agent testing a native app can walk straight through a web-based login or checkout screen without switching tools.

Building and running your app

Point your build at the portal's device and the app you test is the app you just built. An agent can read the device's identifier from the portal, build the project, install it, launch it, and then tap through the result, all from the same terminal.