Ultrafast Installation & Running: uv sync Plus Two API Keys
The previous lesson finished breaking down Jev Ultrafast Principles; this lesson is hands-on: install jev-ultrafast on your own computer and get the local inspector running. There are only two things to do — uv sync to set up the environment, and .env to fill in two API Keys.
The official README's installation path consists of 5 commands in total (git clone, cd, uv sync, cp, uv run jev); the commands themselves aren't hard — but behind each command there's a "why": why uv and not pip, what each of the two Keys is for, and when Chrome gets connected. This lesson spends its 15 minutes here, and once the installation is done, you can go straight into the next lesson to run a real Google Flights task.
What You'll Be Able to Do After This Lesson
- Complete the jev-ultrafast installation using
git clone+uv sync, with dependencies locked in the repository's bundleduv.lockand installed into the.venvnext to the project, without touching system Python - Configure the 6 environment variables in
.env, and be able to explain which two Keys are required and which call each one serves - Open the inspector at
127.0.0.1:8766and get the first demo running with Start demo → Run automatically - Connect Chrome using
uv run browser-harness --doctor, and know whether you should click the "allow remote debugging" prompt - Swap the text helper from the example's OpenRouter + Mercury to OpenAI-compatible models like DeepSeek or GLM
Your Current Difficulties
- You want to see 7-second flight searches with your own eyes, but the README only has five lines of commands, and when things don't run you don't know which layer to check: not installed, Key not configured, or Chrome not connected
- The Keys are a bit confusing: you have a TypeSafe Key, but the example configuration also asks for an OpenRouter one — you're not sure what happens if one is missing or when exactly it will blow up
- Your computer has a pile of Python versions, and this repository also requires Python ≥ 3.12 — you don't want to manually wrestle with yet another global environment
When to Use This Technique
When you need to:
- Get the open-source version of Jev Ultrafast running on your own machine, preparing the environment for Getting Google Flights Running
- See with your own eyes, in the inspector, the numbered elements, action probabilities, and goal probabilities covered in the previous lesson — principles turned into visuals
- Later use the Agent library to write your own browser tasks
And you don't want to:
- Manually create a venv, pip install dependencies, or deal with version conflicts
- Hardcode API Keys into your code, or accidentally commit them into git
🎒 Preparation Before Starting
- Completed Jev Ultrafast Principles: you know about the action set, speculative target heads, and safety boundaries, so the inspector won't confuse you once it's installed
- You have a TypeSafe API Key in hand (if not, first go through Sign-up and API Key)
- Chrome is installed on your computer — all of the agent's clicks and inputs happen inside Chrome
- (Optional) A key from an OpenRouter account, or just use a DeepSeek / GLM key (step 3 explains how to swap)
- A glass of water — this time you're really letting Jev click the browser for you
System Requirements
| Item | Requirement | Source |
|---|---|---|
| Python | ≥ 3.12 (requires-python = ">=3.12") | Repository pyproject.toml |
| uv | Any working version; if you don't have it, install it in step 1 | README installs via uv sync |
| Chrome | Installed locally; allow remote debugging at runtime | README "Try it" |
| Network | Able to reach api.typesafe.ai and the text model endpoint you configure | jev_ultrafast/model.py |
💡 What is uv
uv is a Python package and project manager from Astral (official wording: extremely fast Python package and project manager, written in Rust). It maintains a project-specific .venv next to pyproject.toml, and uv run always verifies that the environment and lock file are in sync first — you never have to manually activate anything again. We previously used uv add in SDK installation alternative methods; this time it's its sibling command uv sync.
Core idea
The essence of installing jev-ultrafast = one set of locked dependencies + two keys.
Leave the dependencies to uv sync. This repository already ships with pyproject.toml and uv.lock, and uv sync does two things (per the uv official docs, "Locking and syncing"): it locks the dependencies into a lock file, then installs the packages from the lock file into the project environment (the .venv next to pyproject.toml). The three core things you end up with:
| What gets installed into .venv | Version constraint | What it's for |
|---|---|---|
jev-ultrafast itself | 0.1.0 | agent loop + jev command entry point |
browser-harness | == 0.1.13 | Connects to Chrome (README: installed automatically by uv sync) |
httpx[http2] | ≥ 0.28, < 1 | HTTP client for sending TypeSafe and text-model requests |
Development dependencies (pytest, ruff, pillow) belong to the dev group, and uv sync installs them by default too — you don't need to worry about them.
Fill the keys into .env — two in total. Why two? As covered in the previous lesson: Jev only makes decisions and doesn't generate text; when a TYPE_TEXT operation occurs, the string is produced by a separate "small LLM". So there are two independent services to authorize:
| Key | What it authorizes | When it's needed |
|---|---|---|
TYPESAFE_API_KEY | api.typesafe.ai/v1/systemone (Jev decisions) | Used every decision cycle; without it the very first request can't be sent |
TEXT_MODEL_API_KEY | The OpenAI-compatible endpoint that TEXT_MODEL_BASE_URL points to (the example is OpenRouter) | Only when the operation is TYPE_TEXT; without it you won't hit an error until the typing step |
This division of labor — one request to ask about the operation, typing outsourced to a small model — is the real-world form of speculative fan-out from Jev Parallel Questions.
Finally, there's the choice of how to run it — after installation there are three paths, and this lesson takes the first:
| How to run | Who it's for |
|---|---|
Local demo (uv run jev + inspector) | Want to take a quick look first and be able to pause step by step — this lesson |
Agent library (uv run --env-file .env python 你的脚本.py) | Want to write your own tasks — Lesson 5 |
BU Ultrafast cloud service (model: "bu-ultrafast") | Don't want to install anything and just run directly on Browser Use Cloud |
Follow along
Step 1: Install uv and Chrome — Prerequisites for the jev-ultrafast installation
Why: The entire installation is done with a single uv command; Chrome is the agent's "hands" — all clicks and inputs happen inside it.
First, check whether uv is present:
uv --versionYou should see: one line with a version number (e.g. uv 0.13.x, depending on the version you installed). If it's not there, on macOS / Linux use the official install script:
curl -LsSf https://astral.sh/uv/install.sh | shWindows (PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"These commands all come from the official uv installation docs (docs.astral.sh/uv); you can also go through package managers like brew install uv, pipx install uv, or winget install --id=astral-sh.uv -e. If your system doesn't have curl, the official docs also provide a wget version: wget -qO- https://astral.sh/uv/install.sh | sh.
Chrome needs no configuration changes — just having it installed is enough; the remote-debugging authorization prompt won't appear until Step 5.
uv --versionproduces output; Chrome opens normally
Step 2: git clone and run uv sync — the jev-ultrafast installation proper
Why: The install commands in the "Try it" section of the README are just these few — copy them verbatim; uv sync installs all the repository's locked dependencies in one go (including Browser Harness), so you don't have to pip them one by one.
git clone https://github.com/browser-use/jev-ultrafast.git
cd jev-ultrafast
uv syncYou should see: git clones the repository into the jev-ultrafast/ directory; uv completes dependency resolution and installation, with the output listing the packages installed into the environment (you should see browser-harness and httpx among them); a .venv/ appears under the repository directory.
Three details worth knowing (based on the official uv docs):
| Detail | Explanation |
|---|---|
.venv/ | The project environment uv manages next to pyproject.toml; it doesn't pollute your system Python and doesn't require manual activation |
uv.lock | Ships with the repository and locks exact versions; when a lock file already exists, uv sync prefers the locked versions |
uv run syncs automatically | Every uv run … first verifies that the environment and lock file are up to date, so even if you change dependencies you don't need to manually re-sync |
uv synccompletes without errors, andjev-ultrafast/contains.venv/
Step 3: Copy .env.example and fill in the two API keys
Why: All keys go through the .env file — it's ignored on the first line of the repository's .gitignore, and the README's development section also states "Credentials and raw traces stay ignored", so keys never travel with git.
cp .env.example .envThen open .env and fill in the two keys (<尖括号> are placeholders — remove the angle brackets after filling them in):
TYPESAFE_API_KEY=<你的 TypeSafe API Key>
TYPESAFE_MODEL=jev-latest
TEXT_MODEL_API_KEY=<你的文本模型 Key>
TEXT_MODEL_BASE_URL=https://openrouter.ai/api/v1
TEXT_MODEL=inception/mercury-2.5
TEXT_MODEL_REASONING=none.env.example has 6 variables in total; here's each one explained (example values and defaults all come from that file and jev_ultrafast/model.py):
| Variable | Example value | Required? | What it controls |
|---|---|---|---|
TYPESAFE_API_KEY | — | Required | The Bearer Key for decision requests, sent to the Jev endpoint api.typesafe.ai/v1/systemone |
TYPESAFE_MODEL | jev-latest | Optional | Decision model; when unset, the code likewise defaults to jev-latest |
TEXT_MODEL_API_KEY | — | TYPE_TEXT Required | Key for the text helper; if unset and a typing action is encountered, it throws an error directly |
TEXT_MODEL_BASE_URL | https://openrouter.ai/api/v1 | Optional | Text model endpoint; when unset, the code defaults to https://api.deepseek.com/v1 |
TEXT_MODEL | inception/mercury-2.5 | Optional | Text model name; when unset, the code defaults to deepseek-chat |
TEXT_MODEL_REASONING | none | Optional | none = turns off reasoning; for the rules when unset, see Method B below |
Where the two Keys come from: for TypeSafe, go to console.typesafe.ai/keys (the signup lesson walked through this once); the text model Key depends on the method you choose:
Method A (example configuration): OpenRouter + Mercury
.env.example's configuration as-is: OpenRouter's Key + inception/mercury-2.5, with reasoning off. The README says this is what the current demo uses. Just copy it verbatim — zero decision cost.
Method B: Direct DeepSeek connection — the default endpoint in the code
Fill in only TEXT_MODEL_API_KEY=<你的 DeepSeek Key>; the TEXT_MODEL_BASE_URL and TEXT_MODEL lines can be omitted (if you copied from .env.example, you must delete those two lines — leaving them empty won't work either, since an empty string still counts as set) — in model.py, the default values when unset are https://api.deepseek.com/v1 + deepseek-chat. The DeepSeek endpoint is auto-detected, and the request includes thinking: {type: disabled} to turn off reasoning.
Method C: GLM / Gemini and other OpenAI-compatible models
The README states explicitly: Gemini, GLM, and DeepSeek can all use this OpenAI-compatible text helper — "configure the corresponding model, endpoint, and reasoning settings." That is, replace TEXT_MODEL_BASE_URL with the OpenAI-compatible endpoint of your chosen service and TEXT_MODEL with the corresponding model name (refer to your provider's documentation for the exact values).
⚠️ Rules for the reasoning parameter
model.py's logic is: when the endpoint contains api.deepseek.com/, it automatically includes thinking: {type: disabled}; other endpoints include reasoning: {effort: low} by default; only with TEXT_MODEL_REASONING=none does it become reasoning: {enabled: false}. When switching models, keeping a line of TEXT_MODEL_REASONING=none is the least hassle.
You should see: in the opened .env, both the TYPESAFE_API_KEY and TEXT_MODEL_API_KEY lines contain your own values and the placeholder angle brackets have been removed; the other 4 lines keep the example values or are adjusted per Method B/C.
.envhas both Keys non-empty; confirm it is in.gitignore(ignored by default)
Step 4: uv run jev starts the local inspector
Why: jev is the command-line entry registered by pyproject.toml ([project.scripts] has jev = "jev_ultrafast.demo:main"); it starts an inspector page that listens only on the local loopback address.
Run from the repository root directory:
uv run jevYou should see (terminal output as-is, from demo.py's main()):
Jev Ultrafast: http://127.0.0.1:8766Open http://127.0.0.1:8766 in your browser and you'll see the demo homepage: a task input box, a scenario dropdown, and a row of control buttons. This service binds only to 127.0.0.1 (demo.py's docstring calls itself a Loopback-only inspector), so other machines cannot access it; press Ctrl+C to stop.
Two details:
The port defaults to 8766; if it's occupied, you can change it with the environment variable
TYPESAFE_DEMO_PORT(see Advanced Tips).envis read at startup from the current directory — so this command must be run inside thejev-ultrafast/repository root directory (see Pitfall Reminder item 2 for the reason)The terminal prints
Jev Ultrafast: http://127.0.0.1:8766, and the page is visible in the browser
Step 5: Start demo connects to Chrome and runs the first demo successfully
Why: the inspector is the official panel for viewing the decision process; the first time you click Start demo, Browser Harness will connect to Chrome — that's when the remote debugging authorization prompt appears.
On the page (button names are the interface's original text):
- The task box is pre-filled with the default goal: a one-way flight search from Zurich to London (original text in
static/index.html; you can change it to your own 1–2000-character goal) - In the scenario dropdown, select
Google Flights · real web(the other two,Travel planner · fixtureandReading room · fixture, are local pages and don't access the network) - Click Start demo
- When Chrome prompts for remote debugging, allow it (README's exact words: Allow remote debugging in Chrome when prompted)
- Click Run automatically to start running; to step through, click Choose next, which pauses before each execution
If Chrome doesn't connect, run this in another terminal (from the repository root directory):
uv run browser-harness --doctorYou should see: numbered elements, action probabilities, goal probabilities, and executed actions appear in the inspector panel (the four things mentioned in the README's original text); in the browser panel, the page starts being operated automatically. When it finishes, press Ctrl+C to shut down the service.
- After Start demo, the inspector shows numbered elements and two columns of probabilities; in the Chrome window, the page is moving
Checkpoint ✅
uv --versionproduces output, and Chrome is installeduv synccompletes without errors, the repository directory contains.venv/, and the installed list includesbrowser-harness- In
.env, both Keys are filled in:TYPESAFE_API_KEY,TEXT_MODEL_API_KEY - From the repository root, run
uv run jevand it printsJev Ultrafast: http://127.0.0.1:8766 - Open
127.0.0.1:8766in a browser; after Start demo you see numbered elements, action probabilities, and goal probabilities
Pitfall warnings
❌ Starting with only TYPESAFE_API_KEY filled in
Symptom: the demo starts and the page can be observed, but it stalls at the "type into the input box" step, with the error message exactly as follows:
TYPE_TEXT needs TEXT_MODEL_API_KEY; no text is hardcoded or guessed by the executor.Cause: TEXT_MODEL_API_KEY is only checked when the action is TYPE_TEXT (model.py's field_text()), and it is not validated at startup, so a missing Key can run all the way until typing before it blows up. The Flights demo has to generate city names, so there is no way around it.
Correct approach: configure both Keys at once — this is exactly what "two API Keys" means in this lesson's H1 heading.
❌ Running outside the repository root, so .env cannot be read
Symptom: you clearly filled in the Key, yet it still reports a missing Key or uses stale configuration.
Cause: demo.py's load_environment() reads .env from the current working directory (the code is literally Path.cwd() / ".env"), so when you run uv run jev in another directory, it reads a .env from elsewhere (or none at all). Also, it uses setdefault — if your terminal already had exported a variable with the same name, the value in .env will not override it.
Correct approach: first cd jev-ultrafast, then uv run jev; when troubleshooting, use echo $TEXT_MODEL_API_KEY to check whether a stale value in your shell took precedence.
❌ Chrome cannot connect and the panel stays frozen
Cause: Browser Harness requires Chrome to allow remote debugging, and Chrome shows a prompt on the first connection; if you miss it or decline, the connection fails.
Correct approach: run uv run browser-harness --doctor to diagnose the connection; the next time Chrome prompts "allow remote debugging", click Allow. For more troubleshooting on connection failures and unresponsive clicks, see Ultrafast troubleshooting.
❌ Assuming the text model can only be OpenRouter's Mercury
Cause: the example value in .env.example is OpenRouter + inception/mercury-2.5, which looks like a hard binding.
Fact: the README explicitly states that Gemini, GLM, and DeepSeek all work with this OpenAI-compatible helper; when TEXT_MODEL_BASE_URL / TEXT_MODEL are not set in model.py, the code default is simply DeepSeek (https://api.deepseek.com/v1 + deepseek-chat).
Correct approach: switch the endpoint and model name via option B / C of step 3, and configure reasoning as that ⚠️ note instructs; after switching, run the demo once to verify the typing step works.
Advanced tips (optional)
Change the port. When 8766 is occupied, set export TYPESAFE_DEMO_PORT=8767 in your shell before starting (on Windows PowerShell use $env:TYPESAFE_DEMO_PORT="8767"), then uv run jev. Note: this variable must be set before the process starts — demo.py reads the port at module import time, so putting it in .env takes effect too late.
Practice on the local fixture pages first. The Travel planner · fixture and Reading room · fixture options in the scenario dropdown run the repository's bundled local pages (static/fixture.html) without accessing the internet — pick them when you want to see how the agent moves but don't want to touch real websites yet.
Don't want to install locally? Go with the cloud. Browser Use Cloud offers a hosted version of BU Ultrafast, officially marked as available on all plans: just configure model: "bu-ultrafast" (cloud.browser-use.com). The open-source version runs on your computer, while the cloud service runs on Browser Use Cloud.
Lesson summary
✅ jev-ultrafast installation = git clone → uv sync → cp .env.example .env → uv run jev, four stages and five commands, taken verbatim from the "Try it" section of the README and usable as-is.
✅ The two Keys each handle their own share: TYPESAFE_API_KEY authorizes Jev decisions (used every cycle), while TEXT_MODEL_API_KEY authorizes the small LLM used for typing (a missing one only errors at TYPE_TEXT, and the error message text is searchable).
✅ uv sync installs the repository's pinned dependencies into the .venv next to the project (including browser-harness 0.1.13, which connects to Chrome); uv run automatically confirms environment sync every time.
✅ Chrome connects through Browser Harness, and uv run browser-harness --doctor is the official diagnostic command; remember to allow remote debugging on the first connection.
✅ The text model is not tied to OpenRouter: DeepSeek is the code default, and GLM / Gemini both work through the OpenAI-compatible endpoint.
Key configuration fields recap (.env, example values from .env.example):
| Field | Recommended value | Description |
|---|---|---|
TYPESAFE_API_KEY | (required) | Jev Key for decisions, obtained from console.typesafe.ai/keys |
TEXT_MODEL_API_KEY | (required) | Key for the text helper, depends on the chosen service |
TYPESAFE_MODEL | jev-latest | Decision model, optional (defaults to the same) |
TEXT_MODEL_BASE_URL | Per option A/B/C | Text model endpoint, optional for DeepSeek |
TEXT_MODEL | Per option A/B/C | Text model name, optional for DeepSeek |
TEXT_MODEL_REASONING | none | Disables reasoning; recommended to keep when switching models |
Next lesson preview
The environment is ready; in the next lesson, Run Google Flights: complete a real search in 7 seconds, the agent will do real work. You will learn:
- Run a real Google Flights search in the inspector and watch firsthand how the 7 seconds are spent
- Use
examples/flights.py --keep-opento reproduce the official recording: search, independent verification, save the trace — no selecting, no booking - Understand what the standalone
verify()in the example actually checked—DONE doesn't count, only code verification does - Which factors affect this number of seconds (details of the measurement methodology are left to performance interpretation)
Appendix: Source code reference
Click to expand and view source code locations
Updated: 2026-11-04 (repository github.com/browser-use/jev-ultrafast, local information source sources/jev/repo-ultrafast/)
| Feature | File path | Key locations |
|---|---|---|
| Installation commands and Chrome connection instructions | README.md | The "Try it" section (git clone / uv sync / cp / uv run jev / 8766 / --doctor / allow remote debugging); "Use the library" (--env-file usage) |
| Environment variable examples | .env.example | Entire file: 6 variables + 1 line of comments (TYPE_TEXT required note) |
| Python version, dependencies, jev entry point | pyproject.toml | requires-python = ">=3.12"; dependencies (browser-harness==0.1.13, httpx[http2]); [project.scripts] jev = "jev_ultrafast.demo:main" |
| inspector port and .env loading | jev_ultrafast/demo.py | L16 PORT (default 8766, reads TYPESAFE_DEMO_PORT); L23 load_environment() (.env in cwd, setdefault); L131 main() (prints Jev Ultrafast: http://127.0.0.1:8766; binds only 127.0.0.1) |
| demo scenarios and goal length | jev_ultrafast/demo.py | L44 command() (scenario ∈ travel/research/flights; goal 1–2000 characters) |
| Usage and errors of the two Keys | jev_ultrafast/model.py | L119 TypeSafe request (Bearer TYPESAFE_API_KEY); L160–168 field_text() (TEXT_MODEL_API_KEY required, DeepSeek default endpoint, reasoning three-way branch) |
| Panel buttons and pre-filled goal | jev_ultrafast/static/index.html | L33–36 scenario dropdown; L40–44 default goal and Start demo; L56–59 Choose next / Execute choice / Run automatically / Pause |
| .env not committed to git | .gitignore | line 1 .env; also ignores .venv/, artifacts/ |
| uv installation and sync behavior | uv official documentation | docs.astral.sh/uv (curl/irm commands in Installation; definitions and default behavior in Locking and syncing; .venv location see Projects → Structure and files) |