Dev Server

Run a live development server to preview the application as the AI agent makes changes. The dev server runs in isolation within the workspace’s directory. A project runs one dev server at a time.

Setting Up the Run Command

Before you can use the Run/Stop button, configure a Run Command for the project:

1. Open Project Settings (Settings → Project → Settings in the settings sidebar).
2. Enter the Run Command — for example:
   • bun dev
   • npm run dev
   • python manage.py runserver
   • rails server
   • cargo watch -x run
3. Click Save.

Workspaces share the run command and the project’s single dev server. Stop the server before starting it in another workspace.

Starting and Stopping the Server

The Run/Stop button is in the chat header. It appears once a Run Command is configured and a workspace is selected — pages without a conversation, such as Tasks and Automations, hide it.

• Click Start dev server (▶) to execute the Run Command in the workspace’s working directory.
• Click Stop dev server (■) to terminate the process. While stopping, the button shows Stopping… briefly.
• Failed (⚠) — If the server fails to start, the button shows an error state. Hover for the reason, click to retry.

When a URL is detected in the server output, Tarsk opens the Browser panel automatically. If you navigated elsewhere in the Browser, Tarsk updates the address bar instead of forcing navigation.

On the project landing page (before selecting a workspace), Start App appears when a run command is set and the server is not running.

The server starts in the background; you can continue chatting with the agent while it runs.

Tip

Start the dev server before asking the agent to make UI changes. That way you can immediately see the results in the Browser panel without a separate step.

Port Already in Use

If the dev server cannot bind its port, Tarsk detects the conflict from process output and shows a Kill and retry dialog (Run/Stop). Confirm to free the port and restart automatically.

If Tarsk cannot kill the process automatically, the output includes a manual shell command you can copy.

Viewing Server Output

Expand the Run Command’s tool block in the chat transcript to read startup stdout and stderr. After Tarsk detects a server URL, it finalizes the block and stops the output stream while the server keeps running. Use the block to check startup errors and the detected port.

Browser panel

Open the Browser window from the chat dock Window launcher to preview the running app inside Tarsk. When the dev server stops, the Browser shows a Dev server stopped placeholder instead of a stale page.

If Built-in Browser is disabled in project settings, open the URL in your system browser instead. Outside the desktop app — the web and mobile builds — the detected URL always opens in your system browser.

Terminal panel

For interactive shell access, open the Terminal window from the Window launcher. See Terminal.

Port Configuration

Tarsk does not assign ports automatically — your Run Command determines the port. A project runs one dev server at a time; choose a different port only when servers from different projects must not collide:

• Pass a PORT environment variable: PORT=3001 bun dev
• Configure the port in .env files the agent can create

Workflow Example

1. Configure Run Command: bun dev (starts on port 3000)
2. Click Run — Tarsk detects http://localhost:3000 and opens the Browser panel
3. Ask the agent: “Change the hero section background to a gradient from indigo to purple”
4. Hot-reload updates the browser; review and ask for the next change

Domain model

See specs/projects.md (Dev Server section) for the dev server state machine and recovery behavior.