Skip to main content
This quickstart guide will help you run your first Longshot build in under 5 minutes.

​
Prerequisites

Before starting, ensure you have:
1

Longshot installed

Follow the installation guide to install Longshot via pipx or Homebrew.
2

Modal account set up

Longshot uses Modal for cloud sandboxes. Install and authenticate:
pip install modal
modal setup
3

LLM API credentials

You’ll need an API key from one of:
  • OpenAI (GPT-4o, GPT-5.3)
  • Anthropic (Claude Opus, Claude Sonnet)
  • Any OpenAI-compatible endpoint

​
Run Your First Build

1

Create a configuration file

Create a .env file in your project directory:
# Minimum required configuration
LLM_BASE_URL=https://api.openai.com/v1
LLM_API_KEY=sk-your-api-key-here
LLM_MODEL=gpt-4o

GIT_REPO_URL=https://github.com/your-org/your-repo.git
GIT_TOKEN=ghp_your-github-token-here
See the configuration guide for all available options.
2

Run Longshot

Execute your first build with a natural language request:
longshot "Build a REST API according to SPEC.md"
Longshot will:
  1. Parse your request with the root planner
  2. Decompose it into granular tasks
  3. Dispatch tasks to parallel Modal sandboxes
  4. Merge results back into your repository
  5. Run the reconciler to fix any build issues
3

Monitor progress

Watch the real-time metrics in your terminal:
[0:05:23]  workers=12  pending=24  done=8  failed=0  commits/hr=96  merged=7  tokens=45,234

​
CLI Options

Longshot provides several useful CLI flags: 
# Launch with Rich TUI dashboard
longshot "Build a REST API" --dashboard

​
Understanding the Output

Longshot outputs structured logs with the following components:
  • Timestamp: When the event occurred
  • Level: INFO, WARN, ERROR, or DEBUG
  • Agent: Which component generated the log (planner, orchestrator, worker-pool, reconciler, merge-queue)
  • Message: Human-readable description
  • Data: Additional context (task IDs, file paths, etc.)

​
Example Log Output

10:23:45  INFO   planner        Task decomposition complete  tasks=32 estimatedTokens=125000
10:23:46  INFO   worker-pool    Dispatching worker  taskId=task-1 workerId=worker-1
10:24:12  INFO   merge-queue    Merge successful  branch=worker/task-1 strategy=rebase

​
Run Artifacts

After each run, Longshot generates three output files:
FileDescription
logs/run-<timestamp>.logComplete structured log of the run
logs/traces-<timestamp>.jsonlDetailed execution traces for debugging
logs/llm-<timestamp>.jsonlAll LLM requests and responses

​
Next Steps

First Project

Step-by-step walkthrough of building your first project

Configuration

Learn about all configuration options

Build docs developers (and LLMs) love

Get started for freeTalk to us