Skip to main content
AI tutorials

Lancer Beginner Tutorial: Build a Traceable Parallel AI Desktop Workspace

This tutorial introduces Lancer’s core capabilities and guides you through environment checks, dependency installation, model connection, and creating your first session. It also covers the ray UI, video tools, verification tests, and macOS build considerations.

About 24 min read
Lancer Beginner Tutorial: Build a Traceable Parallel AI Desktop Workspace

What Is Lancer

Lancer is a desktop AI workspace built on pi-gui and pi. It brings conversations, parallel branches, run processes, and deliverable files together in one interface, helping you trace a task from creation and decomposition through delivery.

Important: Lancer is currently in the Alpha stage, with macOS Apple Silicon as the primary validation platform. Although Linux and Windows have packaging configurations, this does not mean that all native capabilities have been fully validated. The source archive is not a desktop installer that can be launched by double-clicking.

Core Features

Sessions and Modular Tasks

Regular sessions can run independently. Modular sessions can be configured with stages, models, Skills, objectives, and delivery requirements, making them suitable for complex tasks with defined steps and results that require acceptance.

Parallel Branches and Result Aggregation

An assistant can manage multiple sessions. Tasks can spawn child and grandchild branches, with each branch returning its results to the parent session for aggregation when complete. This structure is suitable for parallel research, solution comparison, and multi-stage content production.

GitTree Task Event Graph

GitTree on the right side of the interface can display multiple session lines, branches, merges, and delivery nodes at the same time, or focus on the current session. Note that GitTree represents a task event graph; its nodes do not all represent actual Git commits.

Run Feedback and Light Effects

Activity bubbles and process rows display animated borders, while model output and delivery actions send light in the corresponding color to their associated nodes. These visual cues show which tasks are currently running and how their results flow.

Models, Accounts, and Doubao Takeover

Lancer uses pi to connect subscription accounts, API keys, and custom endpoints, while managing model brands and gateways separately. On macOS, it can also connect to an already-open Doubao App session to receive replies and videos. Doubao takeover requires local Accessibility permission, and interface updates to the desktop Doubao app may affect compatibility.

Video Analysis Workflow

The video workflow can download or receive videos, extract keyframes, and generate analysis and handoff files containing evidence. However, automatic recreation currently cannot guarantee a 1:1 match with the template. Doubao takeover, model analysis, code animation, and final editing are separate stages and should be accepted separately.

Before Installation

Before starting, confirm that your development environment meets the following requirements:

  • Node.js >=22.19.0 and <26; Node.js 24 is recommended.
  • pnpm 10.34.9.
  • Git.
  • macOS requires Xcode Command Line Tools.
  • Linux requires Python 3, make, a C++ compiler, a graphical desktop environment, and the system runtime libraries required by Electron.
  • Windows native dependencies may require Python and Visual Studio Build Tools with the C++ workload, but native Windows behavior has not yet been fully validated in the current version.

If macOS is missing the command-line tools, run:

xcode-select --install

On Debian or Ubuntu, install the Linux build dependencies:

sudo apt-get install build-essential python3

Install and Start from Source

Extract or clone the source into a new directory, enter the repository root, and run the following commands in order:

npx --yes pnpm@10.34.9 run doctor
npx --yes pnpm@10.34.9 install --frozen-lockfile
npx --yes pnpm@10.34.9 dev

These commands use pnpm 10.34.9 explicitly. You do not need to run corepack enable or install pnpm globally. If the same version is already installed on the system, you can replace the command prefix with pnpm.

Dependency downloads require a network connection. If dependency scripts were skipped during installation, the Electron binaries may be missing. After confirming that the network can access the Electron download source, run:

npx --yes pnpm@10.34.9 run setup:electron
npx --yes pnpm@10.34.9 dev

Do not fix Electron installation problems by indiscriminately allowing or disabling all dependency scripts. Check the installation logs and network errors first.

Complete the Initial Setup

  1. Start Lancer and open Settings.
  2. Connect a supported model account, provider, or custom endpoint. The source does not include personal credentials.
  3. Add or select a workspace.
  4. Create a regular session, or create a modular session with stages, models, Skills, objectives, and delivery requirements as needed for the task.
  5. After running the task, observe the session line, derived branches, aggregation, and delivery nodes in GitTree.

You can specify the interface language with an environment variable:

LANCER_LOCALE=zh-CN npx --yes pnpm@10.34.9 dev

For the English interface, set the value to en.

Load Optional Environment Configuration

Optional configuration is documented in .env.example in the repository, but the desktop launch script does not load this file automatically. On macOS or Linux, copy the template and load it in the current terminal:

cp .env.example .env.local
set -a
. ./.env.local
set +a
npx --yes pnpm@10.34.9 dev

PowerShell users can set environment variables individually, for example:

$env:LANCER_LOCALE = "en"

Connect real model accounts in the app settings. Do not commit API keys, authentication files, private endpoints, real conversations, or session recordings to a public repository.

Configure Video Tools

Media tools are not required when using only the conversation interface. To run video downloading, keyframe extraction, and media analysis workflows, you need executable versions of FFmpeg, FFprobe, and yt-dlp.

pnpm run doctor --media

If these tools are not in PATH, specify their absolute paths with the FFMPEG, FFPROBE, and YT_DLP environment variables, or configure the paths in video-learn-tools.json in the user data directory.

The diagnostic command actually runs each tool's version command, so it can detect not only missing files but also broken installations where the executable exists but a dynamic library is missing. Before performing complete validation, you can check manually:

ffmpeg -version
ffprobe -version

Run Checks, Builds, and Tests

When preparing to submit changes or evaluate the source state, run the following checks:

pnpm check
pnpm build
pnpm audit:dependencies
pnpm verify:install-copy
pnpm verify:release-config
pnpm --filter @lancer/desktop run test:e2e:core

You can also verify desktop reloads during development:

pnpm --filter @lancer/desktop run test:dev:reload

Core tests run the real Electron interface with isolated data, but passing the Core tests does not prove that real models, native permissions, installers, performance, or compatibility across all platforms have been validated. Media-related tests also require FFmpeg and FFprobe to run correctly.

Reuse Lancer Light UI Independently

If you only need the light effects that connect models or bubbles to the work tree, you can export Lancer Light UI. It does not depend on Electron, the CLI, or model services, and provides examples of single lines, fork-and-merge flows, and parallel multi-session operation.

pnpm export:light-ui /absolute/new/lancer-light-ui
cd /absolute/new/lancer-light-ui
npm install && npm run dev

The export path must be replaced with an absolute path on the target machine. For more information, see the Light UI README in the repository.

Build a Local App on macOS

The source package does not include a directly launchable .app, and a standalone app download has not yet been released. After installing the dependencies, you can run the local build script:

bash scripts/build-mac-lancer.sh --skip-install --dir

Local installers require a preconfigured persistent signing certificate. The script does not automatically create a certificate, switch to temporary signing, or perform notarization. Build results are saved in a separate apps/desktop/release-local-*/ directory.

After validating the candidate app, add --install to install it in /Applications:

bash scripts/build-mac-lancer.sh --skip-install --dir --install

The installer requires the old app to exit normally, checks the signature, and preserves a recoverable old version without clearing session data. Public distribution still requires Developer ID, notarization, and acceptance testing on a clean machine. Local signing must not be treated as completed certification for public release.

Advanced Usage and Security Recommendations

Understand Where Runtime Data Is Stored

Session and account data use pi's ~/.pi/agent. On macOS, Lancer interface state is stored in ~/Library/Application Support/Lancer. Copying the source to another directory does not isolate this runtime data; for completely isolated manual testing, use a separate operating system user.

Design Branches for Complex Tasks

You can split research, analysis, implementation, and acceptance into separate child branches, then have the parent session aggregate them. When using GitTree, understand nodes as task events and delivery relationships rather than assuming that every node is a code commit.

Accept Each Video Stage Separately

For video projects, check the takeover input, model analysis, code animation, and final edit separately. Do not infer that the final work can automatically match the reference template completely just because one stage succeeded.

Export an Auditable Source Candidate

When preparing a source release, you can export a new candidate directory and SHA-256 manifest:

pnpm export:source /absolute/path/to/new/lancer-source

This command excludes .git, local session artifacts, key files, and build output, but retains the current workspace, historical screenshots, and recordings. A successful export does not mean the result is ready for public release; the authorization of media assets and sensitive content still requires manual review.

Frequently Asked Questions

  • Corepack reports a permission error: Use the fixed-version npx --yes pnpm@10.34.9 command; no changes to the global shim are required.
  • Electron was not installed correctly: Check the network and installation errors, then run run setup:electron.
  • Linux reports that make or a compiler is missing: Install Python 3, make, and the C++ build tools first, then reinstall the dependencies.
  • Video tool checks fail: Run pnpm doctor --media and confirm that the executables and their dynamic libraries are available.
  • The model is unavailable: Connect a supported account or provider in Settings; the source does not contain personal authentication information.

Summary

Lancer brings parallel AI sessions, recursive branching, process feedback, and delivery file organization together in a single desktop workspace. Follow this tutorial to complete the environment checks, launch from source, connect your account, and configure the media tools, then start building traceable task workflows. As the project is still in the Alpha stage, production use, cross-platform compatibility, Doubao takeover, and video replication results should all be independently verified.