--- title: "00 Setup" description: "Have the workshop app running locally with both OpenAI and Langfuse credentials in place. From here you can skim 01-base-app, then start building in 02-tracing." --- # 00 Setup Workshop material is maintained in the public [`langfuse/langfuse-workshop`](https://github.com/langfuse/langfuse-workshop) repository. Use the repository for the runnable app, checkpoint branches, and local setup. [View this Markdown file](https://github.com/langfuse/langfuse-workshop/blob/main/docs/learner/00-setup.md) ## Goal Have the workshop app running locally with both OpenAI and Langfuse credentials in place. From here you can skim `01-base-app`, then start building in `02-tracing`. > ⚠️ Use **Langfuse Cloud** so you have the latest features this workshop describes. Self-hosted instances may be on an older version and will not match the lessons. ## Prerequisites **Node.js `^20.19.0 || >=22.12.0`** — check with `node -v` and upgrade before installing if you are below it (`nvm install 22`, or the equivalent for `asdf`, `fnm`, or `volta`). An older version fails in a way that is easy to misread. Vite's platform-specific binary is an optional dependency, so npm skips it **without reporting an error**: `npm install` looks like it succeeded, and the problem only appears later when `npm run dev` cannot start Vite. If you upgrade Node after installing, re-run `npm ci` so the skipped binary is fetched. ## Starting point Clone the workshop repository, enter it, then check out the setup checkpoint for this chapter: ```bash git clone https://github.com/langfuse/langfuse-workshop.git cd langfuse-workshop git checkout checkpoint/00-setup ``` This checkpoint intentionally contains the same untraced base app as `checkpoint/01-base-app`. Use it to confirm that your API keys, dependencies, and local ports work before switching to the build chapters. The Langfuse keys are configured now, but traces start only after you add instrumentation in `02-tracing`. ## Step 1 — Get the API keys 1. **OpenAI** — [platform.openai.com](https://platform.openai.com) → API Keys → create one. Copy the `sk-...` value. 2. **Langfuse** — sign up at [langfuse.com](https://langfuse.com) on the **EU region**, create a project, and copy the public + secret keys from **Settings → API Keys**. ## Step 2 — Install the Langfuse skill and CLI Later modules drive Langfuse through a coding agent, which needs the `langfuse` skill and the Langfuse CLI. Paste this into your coding agent to install both: > "Please install the `langfuse` skill from `https://github.com/langfuse/skills/tree/main/skills/langfuse`, and install the Langfuse CLI with `npm install -g langfuse-cli`." Prefer to install them yourself: ```bash # Langfuse CLI npm install -g langfuse-cli # Langfuse Skill: npx skills add langfuse/skills --skill "langfuse" ``` ## Step 3 — Configure `.env` ```bash cp .env.example .env ``` Fill in: ```bash OPENAI_API_KEY=sk-... LANGFUSE_PUBLIC_KEY=pk-lf-... LANGFUSE_SECRET_KEY=sk-lf-... LANGFUSE_BASE_URL=https://cloud.langfuse.com ``` Leave the rest of the defaults as they are. The workshop app always loads this repository's `.env` file for the server and helper scripts. If you have `LANGFUSE_*`, `OPENAI_*`, or `DATASET_NAME` values exported in your shell from another project, they will not override this file. To change the workshop configuration, edit `.env`. Keep these values in your local `.env` only. Do not paste real API keys into shared workshop notes, transcripts, screenshots, or chat messages. ## Step 4 — Install and run ```bash npm install npm run dev ``` Open [http://127.0.0.1:3333](http://127.0.0.1:3333). If you want to verify the server separately, check [http://127.0.0.1:8787/api/health](http://127.0.0.1:8787/api/health) or [http://127.0.0.1:8787/api/support-context](http://127.0.0.1:8787/api/support-context). During `npm run dev`, `127.0.0.1:8787/` is not the main app URL. If nothing loads on `127.0.0.1:3333`, scroll the `npm run dev` output back to the `[dev:client]` lines. `concurrently` keeps the API server running even when Vite has crashed, so the terminal still looks alive — and opening `127.0.0.1:8787/` in that state answers with `ENOENT ... dist/index.html`, which only means the production build is absent and says nothing about the real failure. A `Cannot find native binding` crash in those `[dev:client]` lines is the Node version; see Prerequisites. ## Step 5 — Confirm what you see You should see the **Dad IT Support Agent** chat: - the Specs mascot up top - a greeting from Specs - suggestion chips below the greeting - the iPhone panel on the right ("Dad" + iPhone 15 details) ![How Specs handles a ticket — one agent, two tools, one model, each hop an observation in the trace.](https://raw.githubusercontent.com/langfuse/langfuse-workshop/main/docs/images/specs_illustration.png) ## How to verify you are done - `npm run dev` is running and listening on `http://127.0.0.1:3333` (client) and `http://127.0.0.1:8787` (API server). - `http://127.0.0.1:8787/api/health` or `http://127.0.0.1:8787/api/support-context` returns a real response. - The browser shows the Specs greeting, not an error. - Sending one of the suggestion chips returns a real iPhone answer from the model. ## End state Your environment is ready. To build the workshop step-by-step, skim `01-base-app` if you want the app tour, then check out `checkpoint/02-tracing` for the first code changes. --- ## Agent Instructions This page is part of the [Langfuse](https://langfuse.com) documentation, published as plain Markdown for AI agents. Every page is available as Markdown by appending `.md` to its URL, or by sending an `Accept: text/markdown` header. This page: `https://langfuse.com/workshop/learner/00-setup.md`. ### Querying these docs If the answer is not on this page, query the documentation instead of guessing: - **Semantic search** across all Langfuse docs, returning an answer with the relevant pages and excerpts. Ask a specific, self-contained question: ```bash curl -sG "https://langfuse.com/api/search-docs" --data-urlencode "query=How do I trace a LangGraph agent?" ``` - **Index of every page**: , with per-section indexes [llms-docs.txt](https://langfuse.com/llms-docs.txt), [llms-integrations.txt](https://langfuse.com/llms-integrations.txt), and [llms-self-hosting.txt](https://langfuse.com/llms-self-hosting.txt). ### Before writing Langfuse code - **Install the [Langfuse Agent Skill](https://langfuse.com/docs/api-and-data-platform/features/agent-skill).** It encodes Langfuse's own best practices for instrumentation, prompt management, and evaluation, and materially improves results. - **Read [What does a good trace look like?](https://langfuse.com/docs/observability/best-practices.md)** before instrumenting an application. - **Verify endpoints, parameters, and response fields** against the [API reference](https://api.reference.langfuse.com) instead of inferring them from code examples. - **Use the [Langfuse CLI](https://langfuse.com/docs/api-and-data-platform/features/cli)** (`npx langfuse-cli api `) to read or write traces, prompts, datasets, and scores from the terminal. Found an error in these docs? Please open an issue at .