Installation

Tarsk runs as a macOS desktop app or as a CLI on any platform with Node.js or Bun.

Desktop App (macOS)

Download the desktop app from tarsk.io. Prebuilt DMG installers:

Apple Silicon — stable-macos-arm64-tarsk.dmg
Intel — stable-macos-x64-tarsk.dmg

The desktop app bundles its own runtime. You do not need Node.js installed. It runs the same server and UI as npx tarsk, with a native window, menu bar tray icon, and auto-updates from install.tarsk.io. Closing the window keeps the server running; quit from the tray menu.

See Desktop App for tray behavior, updates, and permissions.

CLI

No installation required. Run the following command in any terminal:

npx tarsk

Tarsk starts on port 641 and opens http://localhost:641 in your browser automatically. The server stays running in that terminal session — press Ctrl+C to stop it.

CLI Flags

Flag	Description
`--server`	Start the API server only — do not open a browser tab
`--debug`	Enable verbose logging and listen on port 462
`--data-dir`	Override the data directory (sets `TARSK_DATA_DIR`)
`--assets-dir`	Override companion assets path (sets `TARSK_ASSETS_DIR`)
`--port`	Server port (sets `PORT`, default 641)
`--open`	Open the browser even when `--server` is set

Examples:

npx tarsk --server          # headless server for remote/mobile access
npx tarsk --debug           # troubleshoot with full logs

To always use the latest version:

npx tarsk@latest

System Requirements

Requirement	Notes
git	Must be installed and on your `PATH`. Tarsk uses git to clone repositories and manage branches. Download from git-scm.com.
Node.js 18+ or Bun	Required for `npx tarsk`. The desktop app (Electrobun) bundles its own runtime.
gh CLI (optional)	Required only for creating GitHub repositories and pull requests from within Tarsk. Install from cli.github.com.

Tarsk verifies that git is installed during the onboarding wizard on first launch and will show a warning with a download link if it is missing.

Where Data Is Stored

Tarsk stores its database and managed workspace folders in your user data directory:

Platform	Default path
macOS	`~/Library/Application Support/Tarsk/`
Linux / Windows (CLI)	Same path under your home directory (`~/Library/Application Support/Tarsk/`)

The desktop app and CLI both use this path by default. Set TARSK_APP_SUPPORT_DIR to change the application support directory. Use --data-dir /path/to/data or TARSK_DATA_DIR to change the data/ directory without moving logs or port.json. On Linux or Windows, set TARSK_APP_SUPPORT_DIR if you want a conventional location such as ~/.config/Tarsk.

Inside the application support directory:

data/tarsk.db — SQLite database (projects, threads, conversation history, settings)
data/{repo-slug}/ — one directory per thread, each a full git clone (e.g. org-repo from https://github.com/org/repo; -1, -2, etc. when names collide)
port.json — active server port (written when the server starts)

Each thread is a real, independent filesystem copy of your repository. You can open any thread directory directly in your IDE or file manager.

Mobile and Remote Access

To use Tarsk from a phone or tablet, sign in and turn Mobile & Network Access on in General Settings. Tarsk opens a public address on tarsk.net. Anyone who opens the public address must sign in as that same account. A QR code appears in the Mobile App section. Restart Tarsk after changing this setting.

For the native mobile app with QR code scanning, see the Mobile App guide.

On Linux and Windows, use npx tarsk or the VS Code extension. The macOS desktop app is available from tarsk.io/#download.

Next Steps

Continue to the Quickstart to connect your first repository and start working with the AI agent.