Skip to content
JarvisJarvis Docs

Quickstart

This quickstart takes you from a fresh clone to a working local Jarvis instance that you can open in the browser.

Prerequisites

Section titled “Prerequisites”

Before you start, make sure this machine has:

  • git
  • Python 3.11+
  • Node.js 20.19+
  • a POSIX shell such as bash or zsh

If you plan to launch coding sessions right after setup, also install and authenticate at least one supported runtime CLI such as Claude Code, Codex, or OpenCode.

1. Clone the repository

Section titled “1. Clone the repository”
Terminal window
git clone <your-jarvis-repository-url>
cd Jarvis

2. Create the Python environment and install backend dependencies

Section titled “2. Create the Python environment and install backend dependencies”
Terminal window
python3 -m venv .venv
source .venv/bin/activate
pip install -e 'backend/[dev]'

The editable install keeps the backend running from your working tree while exposing the project scripts through the local virtual environment.

3. Create the local environment file

Section titled “3. Create the local environment file”
Terminal window
cp .env.example .env

Start with the defaults unless you already know you need a different port or database path. For a first local run, the main requirement is that .env exists and points Jarvis at a valid local setup.

4. Build the frontend

Section titled “4. Build the frontend”
Terminal window
cd frontend
npm install
npm run build
cd ..

This produces the static frontend bundle that the backend serves.

5. Start Jarvis

Section titled “5. Start Jarvis”
Terminal window
./restart.sh

On success, Jarvis starts the backend, applies any required local setup, and prints the local listening address. The default local UI address is http://127.0.0.1:8888.

6. Generate an API key

Section titled “6. Generate an API key”

Open a second terminal in the repository root and run:

Terminal window
source .venv/bin/activate
python scripts/generate_api_key.py -d "Local browser"

Copy the generated key. You will paste it into the UI on first access.

7. Open the UI

Section titled “7. Open the UI”
  1. Open http://127.0.0.1:8888 in your browser.
  2. Paste the API key when Jarvis prompts for authentication.
  3. Confirm that the chat workspace loads instead of the API key prompt.

8. Verify the instance

Section titled “8. Verify the instance”

Use both a backend check and a UI check:

Terminal window
curl http://127.0.0.1:8888/api/v1/health

You should get a JSON health response from the local backend.

In the browser, verify that:

  • the main chat view loads
  • the UI accepts normal input
  • no immediate authentication loop appears after you paste the API key

9. Next steps

Section titled “9. Next steps”
  1. Open First coding session to launch a runtime-backed worker from the UI.
  2. Configure runtime CLI authentication if the runtime selector shows your preferred runtime as unavailable.
  3. Read the concept pages once you want to understand session replay, summary capsules, and worker reporting tools.

Troubleshooting

Section titled “Troubleshooting”
  • Frontend build fails immediately: confirm node -v is 20.19 or newer.
  • ./restart.sh does not produce a reachable local server: check whether another process is already bound to port 8888.
  • Browser keeps asking for authentication: generate a fresh API key and paste it again.
  • Health endpoint works but the UI looks stale: rebuild frontend/ and refresh the browser.