Getting Started

Tracer wraps pinned Harbor and swe_data_process checkouts in the LegoFlow block layout. It prepares verified tasks, rolls an agent out through a per-job LiteLLM proxy, archives the run, and can convert successful trajectories into training data.

Recommended: operate via the Claude plugin

The block ships a tracer Claude Code plugin that owns the complete lifecycle. Launch Claude from the repository root to load every block plugin, or from blocks/tracer/ for the block-local plugin, then use:

/tracer:setup          # pin repos, build all three environments, initialize the ledger
/tracer:check          # read-only preflight of config, repos, tasks, endpoint, Docker
/tracer:run            # confirm, run Harbor, archive, and perform tracer bookkeeping
/tracer:dashboard      # preview/publish progress or refresh SFT data and statistics

From the repository root, the generic orchestration equivalents are:

/root:check tracer
/root:run tracer

Choose either /root:run tracer or /tracer:run for a given job, not both. Both flows validate first and require explicit confirmation before launching. The root command owns generic dispatch and archiving; the tracer command also documents the block-specific proxy, ledger, and post-run procedure.

The commands read config.yaml. LLM settings live under runtime_info.input.llm_api, task selection under task_source, rollout scale under harbor_job, the runtime preset under agent, and conversion settings under sft_conversion. Edit that file instead of the scripts or skill files.

The rest of this page describes the underlying commands for manual operation and debugging.

Prerequisites

• Docker with a reachable daemon.
• uv and Python 3 with PyYAML.
• Python 3.13 for the pinned LiteLLM environment; uv can install it.
• An OpenAI-compatible LLM endpoint and API key.
• A task source: curator's merged Harbor tasks or a compatible Hugging Face dataset.

1. Enter and configure the block

Run manual commands from the block root:

cd blocks/tracer

Fill the two checked-in human markers:

runtime_info:
  input:
    llm_api:
      api_key: <your-key>
      api_base_url: https://your-openai-compatible-endpoint/v1
      model: openai/Qwen3.6-35B-A3B

Do not commit a real key. Before continuing, also review task_source.provider, task_source.dataset_name, harbor_job.n_tasks, harbor_job.n_concurrent, and the complete agent preset. When changing agents, keep its import path, API protocol, version, runtime image/runtime mount, and SFT scaffold aligned.

2. Update the managed repos

Tracer pins harbor and swe_data_process in config.yaml. Initialize the tracked Harbor submodule in a fresh clone, then let the updater enforce both pins:

git submodule update --init repos/harbor
bash scripts/update_repos.sh

The updater refuses to overwrite local modifications and makes repositories marked readonly: true read-only after checkout. Use --repo harbor or --repo swe_data_process to update one dependency.

3. Build the environments

The three environments live outside the read-only repositories:

bash scripts/setup_harbor_env.sh

uv python install 3.13
uv venv artifacts/env/litellm-venv --python 3.13
uv pip install --python artifacts/env/litellm-venv/bin/python \
  "litellm[proxy]==1.83.14"

bash scripts/setup_swe_data_process_env.sh

/tracer:setup performs these steps idempotently and verifies the imports. start.sh expects the environments to exist; it does not build missing ones on demand.

4. Prepare tasks

Stage the configured source as Harbor task directories:

bash scripts/prepare_tasks.sh

For a local curator source, the script copies only IDs from verifiable_tasks.txt when that manifest exists. If the local source has no manifest, the current implementation copies all structurally valid task directories and prints that behavior. Hugging Face sources are downloaded under artifacts/tasks/.cache/ before compatible task directories are staged.

Prepared tasks land under artifacts/tasks/<dataset>/. Existing valid tasks are reused; pass --overwrite to rebuild them. See Prepare Tasks.

Task preparation is explicit. A normal start.sh does not prepare tasks unless it is launched with TRAJGEN_PREPARE_TASKS=1.

5. Validate the block

Run the read-only preflight:

bash scripts/dryrun.sh

It validates the shared block schema and dependency wiring, repo pins, the Harbor/LiteLLM/converter environments, prepared tasks, LLM model visibility, the proxy port, Docker and runtime image, conversion settings, and the processed-task ledger. Cloudflare and registry credentials are optional warnings.

Fix all failures before launching. To inspect the generated Harbor command without starting the proxy or rollouts:

bash scripts/start.sh --dry-run-command

6. Launch and inspect a job

After the preflight passes:

bash scripts/start.sh

start.sh generates a job-specific LiteLLM config, starts the proxy, builds the Harbor command from config.yaml, excludes both manually blocked and already-processed tasks, runs the job, optionally converts SFT data, stops the proxy, and archives the exit status.

The principal outputs are:

artifacts/jobs/<job>/result.json
artifacts/jobs/<job>/<task>/agent/litellm-trajectory.jsonl
artifacts/archives/run_NNN/
artifacts/index.yaml

When sft_conversion.enabled: true, successful trajectories are also written under artifacts/sft_data/<job>/. Use the dashboard for job, instance, trajectory, and SFT views.