Dev Server

Every branch can run its own live development server, letting you preview the application as the AI agent makes changes. The dev server runs in isolation within the branch’s directory — different branches can run servers on different ports simultaneously.

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 icon in the chat header, or Settings → Project → Settings).
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.

The run command is shared across all branches but runs independently in each branch’s directory.

Starting and Stopping the Server

The Run/Stop button is in the chat header. It appears once a Run Command is configured.

• Click Run (▶) — Tarsk executes the Run Command in the branch’s working directory.
• Click Stop (■) — Tarsk terminates 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 and shows a toast instead of forcing navigation.

On the project landing page (before selecting a branch), 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

When the dev server is running, the Output panel appears below the chat area with a live stream of stdout and stderr — useful for confirming the port, seeing compile errors, and watching hot-reload events.

Click X to hide the output panel without stopping the server.

Browser panel

Open the Browser window from the chat dock taskbar 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.

Terminal panel

For interactive shell access, open the Terminal window from the chat dock taskbar. See Terminal.

Port Configuration

Tarsk does not assign ports automatically — your Run Command determines the port. For multiple simultaneous branches, use different ports:

• Pass a PORT environment variable: PORT=3001 bun dev
• Configure different ports per-branch via .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/glossary.md and specs/adr/dev-server-lifecycle.md for the dev server state machine and recovery behavior.