jpspy.cam
Setup guide

Install JP Spy and link it to jpspy.cam

You put JP Spy on a small always-on computer on your network, tell it where your cameras are, then link it to this site so you can open it from anywhere. No networking experience needed: every step says what you should see when it worked.

Start at step 1 Something went wrong?

The short version

If you are comfortable with a Linux terminal, this is the whole job. Details for each line are in the steps below.

unzip jp_nvr.zip -d jp_nvr && cd jp_nvr
sudo bash deploy/install-debian.sh
sudo nano /opt/go2rtc/go2rtc.yaml        # add your cameras under "streams:"
sudo systemctl restart go2rtc
# then open http://YOUR-SERVER-IP:5000 and add your cameras
# and link the server to jpspy.cam (steps 4 to 6)

How it fits together

JP Spy is a camera system you run yourself. It is made of three parts, and it helps to know what each one does:

go2rtc

This is the engine that reads your cameras. It is a separate, free and open-source program (go2rtc by AlexxIT) that JP Spy depends on, and the installer sets it up for you. It connects to each camera once and shares that one stream with the recorder and with everyone watching, so more viewers do not mean more load on your cameras. You tell it where your cameras are in one small file (step 3).

JP Spy

The part you actually use: a website on your own server with a live wall, recordings, motion alerts and exports. You open it in a browser, and it has its own sign-in.

jpspy.cam (this site)

A phone book for your servers. It gives yours a memorable address like jpspy.cam/myhome and, if you switch it on, a tunnel so you can reach your server from outside your home without changing your router. It never stores your recordings.

Before you start

You need:

  • A computer to be the server. It should stay on and be plugged into your network. JP Spy is built and tested on Debian 12 or 13. Other Debian-based systems such as Ubuntu usually work (the installer warns you if it is not Debian). The installer supports 64-bit Intel/AMD and ARM processors.
  • Disk space for recordings. Video adds up quickly, so use a disk with plenty of room.
  • Your cameras' addresses, usernames and passwords. Your cameras need to offer an RTSP stream (most IP cameras do, but some have it switched off in their own settings). Step 3 shows what the address looks like.
  • Fixed addresses. In your router, reserve a permanent address for the server and for each camera so they do not change.
  • Internet access on the server while installing. It downloads go2rtc and some software.

1 Get JP Spy onto the server

Download the JP Spy package. It is a single .zip file.

Download JP Spy

Copy the zip to your server. From another computer on your network that is one command (change the user name and address to yours):

scp jp_nvr.zip YOUR-USER@YOUR-SERVER-IP:~/

Then, on the server, unpack it:

sudo apt update && sudo apt install -y unzip
unzip jp_nvr.zip -d jp_nvr
cd jp_nvr

You should see: ls lists a folder called deploy among other files. If it shows just one folder instead, cd into that folder.

2 Run the installer

sudo bash deploy/install-debian.sh

It installs everything and asks a few questions. Press Enter to take the answer shown in [brackets].

It asksWhat to answer
What would you like to call this system?Anything you like. It appears in the menu and page titles.
Install face recognition?Optional. It downloads about 37 MB. You can add it later in Settings → Modules.
Install people & vehicle detection?Optional. About 8 MB. Also available later in Settings → Modules.
Enable door access (ICT Protege WX)?N, unless you use that door controller.
Give this server a web address like jpspy.cam/yourname?N for now. You will do it properly in step 6 (or paste your code here if you already have one from step 5).

What the installer sets up

  • go2rtc in /opt/go2rtc, running as a service called go2rtc.
  • JP Spy in /opt/jp-nvr, running as two services: jp-nvr-web (the website) and jp-nvr-recorder (recording and alerts).
  • It starts them all, and starts them again by itself after a reboot.

It is safe to run again later: it upgrades the software and keeps your settings, data and recordings.

To skip the questions (for example, in a script), give your answers as options:

sudo bash deploy/install-debian.sh --yes --name "My Home" --timezone America/New_York

You should see a list of green ticks, including go2rtc API answering on :1984, and then a box that says Web UI: http://192.168.x.x:5000. Write that address down: it is where you open JP Spy.

3 Tell go2rtc where your cameras are

go2rtc keeps a list of streams. A stream is just a name you choose plus the address of one camera. You edit the list in one file:

sudo nano /opt/go2rtc/go2rtc.yaml

Find the line that says streams: and add your cameras underneath it. Keep two spaces at the start of each line, and use spaces rather than tabs:

streams:
  front_door: rtsp://admin:YourPassword@192.168.1.50:554/stream1
  front_door_sub: rtsp://admin:YourPassword@192.168.1.50:554/stream2
  garage: rtsp://admin:YourPassword@192.168.1.51:554/stream1
  • The name (front_door) is yours to choose: letters, numbers and underscores. You will pick it again in step 4.
  • The address starts with rtsp://, then the camera's username and password, then @, then its network address and port.
  • The optional _sub stream. Many cameras give a second, lower-quality stream. If you name it the same plus _sub, JP Spy uses it for the live wall and for motion detection, which keeps everything light. If your camera has only one stream, skip it.
  • Special characters in a password must be written as codes inside the address: @ as %40, # as %23, / as %2F, : as %3A, and a space as %20.

What does my camera's address look like?

It depends on the make and model, so check your camera's manual for its RTSP address. These common formats are examples to start from (IP is the camera's address on your network):

CameraMain streamLower-quality stream
Hikvisionrtsp://USER:PASS@IP:554/Streaming/Channels/101…/Streaming/Channels/102
Dahua, Amcrestrtsp://USER:PASS@IP:554/cam/realmonitor?channel=1&subtype=0…channel=1&subtype=1
Reolinkrtsp://USER:PASS@IP:554/h264Preview_01_main…/h264Preview_01_sub
TP-Link Taportsp://USER:PASS@IP:554/stream1…/stream2 (needs a camera account made in the Tapo app)

go2rtc reads many other kinds of camera too, such as ONVIF and plain HTTP streams. See the go2rtc documentation for every kind of address it understands.

Save the file (Ctrl+O, Enter, then Ctrl+X) and restart go2rtc so it reads your changes:

sudo systemctl restart go2rtc

You should see: open http://YOUR-SERVER-IP:1984 in your browser. It is go2rtc's own page, and it lists each stream you added. Click stream next to one to watch your camera. If a stream does not play, fix it here before going further (see troubleshooting).

Keep go2rtc private. go2rtc has no password. Its ports (1984, 8554 and 8555) are for your own network only. Never forward them in your router. Reaching your cameras from outside goes through JP Spy's sign-in instead (step 7).

Tip: instead of one big file you can put each camera in its own file in /opt/go2rtc/conf.d/. Every .yaml file there is loaded automatically.

4 Add the cameras in JP Spy

  1. On any computer or phone on your network, open the address the installer showed you, http://YOUR-SERVER-IP:5000.
  2. The first time, JP Spy asks you to create the admin account. Choose a username and a strong password, and keep them safe.
  3. Go to Settings → Cameras and click + Add camera.
  4. In the go2rtc stream box, pick the name you chose in step 3. The box suggests the names go2rtc has.
  5. Choose what the camera should do: Record 24/7, Record on motion, or Off (view only).
  6. Repeat for each camera, then save.

You should see: open Live from the menu, and your cameras appear with video. If the stream box has no suggestions, JP Spy cannot reach go2rtc (see troubleshooting).

5 Create your account here and claim a name

  1. Create an account on jpspy.cam (or sign in if you have one).
  2. On your dashboard, claim a name, for example myhome. That becomes your address, jpspy.cam/myhome.
  3. Click Add a site and give this server a name, for example Home. One name can cover several places, so add one site for each server you run.
  4. The dashboard shows a one-time code like ABCD-2345. It works once and expires after 15 minutes. Leave that page open.

7 Open it from anywhere

At home, people on your network can already use the server's own address. To reach it from outside, pick one of these:

Option A: the tunnel (easiest, no router changes)

  1. In Settings → Remote access, tick Reach this server from anywhere through the portal (no port forwarding needed) and save.
  2. Within a few seconds the page says Tunnel connected and shows your address, like https://home--myhome.jpspy.cam/. The short form jpspy.cam/myhome/home forwards there.

Your server makes an outgoing connection to this site, which is why your router needs no changes. Anyone who opens that address still signs in to your JP Spy.

Read this before you turn the tunnel on. Everyone who opens that address is talking through this site's server. That server carries your video live and could read the traffic, including your JP Spy sign-in. Recordings are never stored here. Only use the tunnel if you trust whoever runs this site, and turn on two-step sign-in (on JP Spy's Account page) as soon as it is on. If you would rather not rely on it, use option B.

Option B: your own address or a private network

If your server is already reachable some other way, such as a VPN or Tailscale, put that address in Settings → Remote access → This server's public address. This site then sends people there, and nothing passes through it. (The installer can install Tailscale for you with --tailscale.)

Check it all works

  • http://YOUR-SERVER-IP:1984 lists your streams, and they play.
  • Live in JP Spy shows video from every camera.
  • Settings → Remote access says Linked and Online.
  • jpspy.cam/myhome shows your site with a green dot.
  • With your phone off your home Wi-Fi, your tunnel address opens and asks you to sign in.

Troubleshooting

Click a problem to open it. Commands starting with journalctl show a service's recent log, which usually says exactly what is wrong.

I cannot open http://YOUR-SERVER-IP:5000
  • Are you on the same network as the server? That address only works inside your home or office.
  • Find the server's real address by running hostname -I on the server.
  • Check the website service is running: sudo systemctl status jp-nvr-web. If it is not, sudo systemctl restart jp-nvr-web.
  • If the server has a firewall, allow port 5000 (for ufw: sudo ufw allow 5000/tcp).
A camera says "Reconnecting" or never shows video
  • First test it in go2rtc's own page, http://YOUR-SERVER-IP:1984. If it does not play there, the problem is the camera address, not JP Spy.
  • Check the username, the password, and the stream path for your camera model. A password with @, # or / in it must be written as a code (see step 3).
  • Make sure RTSP is switched on in the camera's own settings, and that you can reach the camera from the server. This test shows the camera's details if the address is right: ffprobe -rtsp_transport tcp "rtsp://USER:PASS@IP:554/stream1"
  • See what go2rtc says: journalctl -u go2rtc -n 50 --no-pager
  • Some cameras only allow a few viewers at once. go2rtc connects once per camera and shares it, so this is rarely the cause, but check there is no other recorder hogging the camera.
The "go2rtc stream" box in Settings → Cameras has no suggestions

JP Spy cannot reach go2rtc. Check it is running with sudo systemctl status go2rtc and restart it with sudo systemctl restart go2rtc. Its page at http://YOUR-SERVER-IP:1984 should open.

go2rtc will not start after I edited the file

Almost always the spacing. The file needs two spaces (not tabs) before each camera name. journalctl -u go2rtc -n 30 --no-pager usually names the line it dislikes. Fix it, then sudo systemctl restart go2rtc.

The code is rejected or "expired"
  • A code works once and expires after 15 minutes. On your dashboard, click Add a site again to make a fresh one.
  • Type it exactly as shown. The server also needs to reach jpspy.cam over the internet.
It says my server's clock is wrong

The server's clock must be within 5 minutes of the real time. Run timedatectl: it should say System clock synchronized: yes. To set your time zone, for example: sudo timedatectl set-timezone America/New_York.

My site shows as offline on jpspy.cam
  • Open Settings → Remote access in JP Spy. It shows the reason in plain words.
  • The server must be able to reach jpspy.cam over the internet (an ordinary outgoing HTTPS connection).
  • Restart the recorder, which does the reporting: sudo systemctl restart jp-nvr-recorder
  • Then look at its log: journalctl -u jp-nvr-recorder -n 50 --no-pager
The tunnel says "not connected"
  • The line under the checkbox gives the reason. Read it first.
  • The person who runs this site has to have the tunnel switched on at their end. If it is off, there is nothing you can change on your server.
  • Your server needs an ordinary outgoing internet connection. Restarting the recorder retries straight away: sudo systemctl restart jp-nvr-recorder
I forgot my JP Spy admin password 
cd /opt/jp-nvr && sudo -u nvr venv/bin/python manage.py reset-password YOUR-USERNAME
I want to unlink this server, or move to a new one

In JP Spy, open Settings → Remote access and click Disconnect. You can also click Unlink next to the site on your dashboard. A server's link is not copied into backups, so after restoring onto a new machine you link it again with a fresh code (steps 5 and 6).

Handy commands

Run these on the server.

ToRun
Apply changes to go2rtc.yamlsudo systemctl restart go2rtc
Restart the JP Spy websitesudo systemctl restart jp-nvr-web
Restart recording and remote accesssudo systemctl restart jp-nvr-recorder
Watch the recorder's log livejournalctl -u jp-nvr-recorder -f
See go2rtc's logjournalctl -u go2rtc -n 50 --no-pager
Reset a JP Spy passwordcd /opt/jp-nvr && sudo -u nvr venv/bin/python manage.py reset-password USERNAME
Upgrade JP SpyUnpack the new package and run sudo bash deploy/install-debian.sh again. It keeps your settings, data and recordings.

Questions people ask

Do I need to open ports on my router?

No. The tunnel works through an outgoing connection, so your router stays as it is. Never forward go2rtc's ports (1984, 8554, 8555): it has no password.

Does my video go through jpspy.cam?

Only if you use the tunnel, and then only live, on its way to you. It is never stored here. Recordings, faces and camera passwords stay on your server.

What is go2rtc, and do I have to install it separately?

It is the free, open-source streaming engine JP Spy uses to talk to cameras. You do not install it yourself: the JP Spy installer does it. You only tell it where your cameras are (step 3).

Will my camera work?

If it offers an RTSP stream (or ONVIF, or an HTTP video address), go2rtc can very likely read it. The quickest check is to try its address in step 3 and see whether it plays on go2rtc's page.

Can I link more than one place?

Yes. Install JP Spy on each server, and click Add a site on your dashboard for each one. They all appear under the same name.

What if I do not want to use the tunnel?

Leave it off. You can still open JP Spy at home by its own address, and use option B in step 7 (your own address or a private network) to reach it from elsewhere.

All set up?

Create your account to claim a name and get your first code.

Create your account