Run your app and try it

6 minute read · Projects & Git

Start the intended project from its Local app card and use Preview to inspect its actual running address. A successful start tells you that a process is available; try the requested user flow before calling the feature complete.

• Choose the project and open its app
• Start, inspect, stop and restart
• Inspect the page at different sizes
• Let the agent verify the flow
• Keep terminals and services in the right folder
• Diagnose the right layer

Choose the project and open its app#

Open Workspace settings → Local app, or type /run in a project chat, to see a card for every project in the workspace. Confirm the project before starting, stopping or opening an app. Choosing a project here does not redirect an existing chat or running agent to another checkout.

Open Browser from the toolbar to use the app and reference websites in one Browser panel and tab strip. App pages are ordinary editable, closable tabs: there is no reserved App Preview tab. Use Open app for the intended project, then check the returned address and selected page. An app opened from its Local app card belongs to that project. An empty tab offers Recently visited pages and Workspace apps; the Browser menus include History for the profile's last 30 days and Downloads, and the address bar has Site information.

Switching projects or workspaces keeps the relevant browser pages and their state. A deliberate reload can discard unsaved form input. A standalone chat can use websites without a configured project app, and a non-web project does not need browser-specific controls. Opening a browser page does not start a project process.

Start, inspect, stop and restart#

Open Startup settings on the card and review Local server, Run app, Local address, Run tests and Build. Choose Start app: it saves these settings and prepares the app automatically, showing progress and errors in the same card. Stop app stops it and Retry start continues after a correction. If a step fails, inspect its output and continue from that failure after correcting the cause. Reopening a prepared project should reuse completed setup rather than scaffold a second copy.

Vortex starts the app's Run app command. It has no separate background-process settings, so a queue worker, scheduler or WebSocket service that a feature needs must be started another way, for example in a project terminal. Inspect each required process; a running frontend alone can still have broken data requests. There is no Restart button on the card; stop and start the app, or ask the agent to restart it.

For an app already served by Herd or another local server, choose Already running (Herd / local server) and enter its address. Check address confirms it responds and Disconnect Preview stops using it; Vortex's controls do not stop or restart the external server. For managed processes, use the selected project's runtime controls. Do not stop an unrelated process to obtain its port.

Use the actual address Vortex reports. Automatically assigned ports can change, and an isolated worktree may need a different address from the main checkout. Never assume a framework's default port is the current running port.

Inspect the page at different sizes#

Choose Responsive, Phone, Tablet or Desktop from the viewport menu. Rotate applies to a fixed-size preset. Responsive uses available panel space; a fixed viewport gives a repeatable layout check. Resize or expand the panel for more room.

Use Console and Network to inspect errors and requests, DevTools for deeper inspection, and Auto-reload when you want updates reflected automatically. Consider unsaved input before reloading. For an actual native mobile app, use Mobile Emulator, rather than treating a narrow website as a device test.

Browser profiles save website logins on this device, separately for each Vortex account. App pages share the selected profile's cookies. See Browser settings and profiles before clearing or importing them.

Let the agent verify the flow#

Ask for a concrete check: “At phone size, add a fictional article, reload and confirm its title is still there.” Through the built-in browser tools, the agent can list, open, select and close tabs in the same browser profile, read page snapshots, click, double-click, hover, fill several fields at once, select, check, press keys, scroll, drag and drop files, find text, wait for a state, answer dialogs and go back or forward. It should read a fresh page snapshot after changes and target the actual tab. The page runs in a hidden window unless you ask to see it.

For deeper checks it can switch light/dark or print media, simulate offline or slow networks, inspect storage, cookies and requests with sensitive values hidden, mock a response, take full-page or element screenshots, and save a PDF, a Playwright trace or a short silent video. Exports are saved inside the project, up to 100 MiB. Recording your own demonstration requires a visible Preview. Nothing extra needs to be installed.

The agent can evaluate JavaScript within the selected web page for a focused check. Page evaluation has no Node, Electron or Vortex application bridge. Uploads use eligible project files; downloads are saved inside the project without being executed. All actions retain the conversation's permissions. Report an unsupported control or unverified step instead of substituting a screenshot for a completed save.

Keep terminals and services in the right folder#

The project terminal opens below the work area. Drag the divider above it to resize. Terminal tabs belong to the workspace: + → Open terminal in project contains only projects and available working copies in that workspace. Each session keeps its working directory and running commands when you switch projects or workspaces. Opening a terminal does not change the chat, Files or Source Control selection.

Use the project's external Terminal action when you want the operating system's terminal instead of an embedded shell. Hiding an embedded terminal keeps its session; End Active Shell ends the selected shell. Switching a project is not a command to change directory in an existing session.

Start any extra long-running service, such as a queue worker, in a project terminal in the intended folder. Reuse a suitable running service instead of starting another on the same port. Closing Browser does not stop a worker. For one bounded script whose result should resume the chat, use background jobs; for recurring agent work, use local schedules.

Diagnose the right layer#

Include the action, expected result and actual result in your feedback. “The title disappears after reload” is more useful than “the app is broken.” Starting locally does not publish the app. See checks and publishing, project connections and worktrees.