Skip to main content
This guide takes you from nothing installed to your first chat with your own FrogBot agent, running on your computer. It takes about 15 minutes. You type a few commands; each step says what you should see. Would you rather have a coding agent such as Codex or Claude Code do this for you? Use Start with a coding agent instead.
1

Install Node.js

FrogBot runs on Node.js 24.21 or newer. Download the installer from nodejs.org and run it.You should see: the installer finishes without errors. You check the version in step 2.
2

Open a terminal

A terminal is a window where you type commands.
  • macOS: open Terminal from Applications → Utilities, or search for it with Spotlight (Cmd+Space).
  • Windows: search for Command Prompt in the Start menu and open it.
Type this command and press Enter:
You should see: a version number of v24.21.0 or higher, such as v24.22.0. If the command is not found or the number is lower, install Node.js again and open a new terminal window.
3

Create the app

In the terminal, run:
If it asks to install create-frogbot-app, type y and press Enter. It then asks a few questions. Press Enter to accept the default for each one, except the AI provider: choose OpenAI. When it asks for OPENAI_API_KEY, paste your key if you already have one, or leave it blank and add it in step 5. If it says Found OPENAI_API_KEY in your environment. Use it for this app?, press Enter to use that key.You should see: Created my-frogbot. followed by the commands to start the app. If you left the key blank, it first prints Set OPENAI_API_KEY in my-frogbot/.env. The app won't start without it. Your app is in a new folder named my-frogbot in the folder where you ran the command (your home folder, if you just opened the terminal).
4

Get an AI key

Your agent needs an AI provider to answer. This guide uses OpenAI. Sign in at platform.openai.com/api-keys, select Create new secret key, and copy the key. OpenAI charges for usage, so you may need to add a payment method first.You should see: a long key that starts with sk-. Keep it somewhere safe; OpenAI shows it only once.To use Anthropic or Google instead, see Installation.
5

Add the key to your app

Skip this step if you pasted your key, or chose to use the one it found, in step 3. Otherwise, add the key before you start the app; without it, the app does not open.Open the my-frogbot folder and find the file named .env:
  • macOS: Finder hides files whose names start with a dot. Open the folder in Finder and press Cmd+Shift+. (period) to show them. Then Control-click .env and choose Open With → TextEdit.
  • Windows: open the folder in File Explorer, right-click .env, and choose Open with → Notepad.
Find the line OPENAI_API_KEY=, paste your key directly after the = with no spaces, and save the file.You should see: a line like OPENAI_API_KEY=sk-... with your full key. The .env file stays on your computer and is not added to Git.
6

Start the app

In the terminal, run:
You should see: a few lines that include the address http://localhost:3000 and end with Ready. Leave this terminal window open while you use the app. To stop the app later, press Ctrl+C in that window (on Windows, type Y and press Enter if it asks to terminate the batch job).
7

Create your admin account

Open http://localhost:3000 in your web browser. The first page load can take a minute while the app prepares.You should see: a Welcome page that says “To begin, create your first user.” Enter your email address, type the same password in New Password and Confirm Password, and select Create. You can leave the other fields as they are. The account is stored only in your app on your computer.After you create it, you see your dashboard: a card for each collection, such as Users and Chats, under the Collections heading.
8

Send your first message

In the sidebar, under Collections, select Chats, then select Create New. If the sidebar is closed, select the FrogBot logo at the top left to open it.A new chat opens with a greeting and a message box at the bottom. Type a message, such as “Hello!”, and press Enter.You should see: your agent replies in the chat.
You now have a working FrogBot app. To change what your agent does, edit src/frogbot.config.ts in the my-frogbot folder; Concepts explains the building blocks.

​
If something goes wrong

The key is missing. The browser and the terminal both show Invalid gateway config: providers.openai.apiKey or OPENAI_API_KEY must be a non-empty string. Add it to .env as shown in step 5, press Ctrl+C in the terminal, and run npm run dev again.
Your message appears, but no reply comes, and the terminal shows an error from OpenAI, such as Incorrect API key provided. Usually the key is wrong or incomplete. Open .env in the my-frogbot folder and check that the OPENAI_API_KEY= line has your full key after the =, with no spaces or quotes. Save the file, press Ctrl+C in the terminal, run npm run dev again, and send a new message.If you created a new key, make sure your OpenAI account has billing set up.
A key that is already set in your terminal takes priority over the one in .env. Close the terminal, open a new one, and start the app again. If that does not help, the variable is set in your terminal’s startup settings. Remove it there, or put the same key in both places.
Install Node.js 24.21 or newer from nodejs.org, then close the terminal and open a new one before you try again.
A folder with that name is already there, often from an earlier try. Choose another name, such as npx create-frogbot-app@latest my-frogbot-2, and use that name in the steps that follow. You can also delete the old folder if you do not need it.
Project names use only lowercase letters, numbers, dots, dashes, and underscores, and start with a letter or number. For example, my-frogbot works, but My-FrogBot does not. A name with a space, such as my frogbot, shows Provide the project name once; use a dash instead of the space.
PowerShell blocks the npx and npm commands on many Windows computers. Open Command Prompt instead, as shown in step 2, and run the same command there.
If another program is already using port 3000, the app starts on the next free port and prints it, such as http://localhost:3001. Open the address shown in the terminal.
Still stuck? Ask in the FrogBot Discord, or see Installation for every option.