Stream an RTSP camera (CLI)

This tutorial connects a physical IP camera on your local network to Agnify. The CLI reads the camera’s RTSP stream, uploads the footage to Agnify continuously, and keeps running so the camera stays live. Once footage is flowing, you analyze it from the Agnify dashboard.

RTSP camera (on your LAN)
   │   the CLI reads the stream and uploads it
   ▼
agnify camera stream   ← runs on a computer that can reach the camera
   │
   ▼
Agnify   →   analyze in the dashboard

The CLI does the reading and uploading from a computer on the same network as the camera — Agnify never connects to your camera directly, so that computer must be able to reach it.

Prerequisites

An RTSP camera reachable from the computer that will run the CLI.

That computer must be on the same network as the camera (or able to reach its IP address). If the camera is on a different network you’ll need a route or VPN to it.
ffmpeg and ffprobe installed.

The CLI uses them to read the camera. Both must be installed.
- macOS
- Debian / Ubuntu
Terminal window
brew install ffmpeg
Terminal window
sudo apt-get update && sudo apt-get install -y ffmpeg
The Agnify CLI (needs Python 3.11+).
Terminal window
```
curl -LsSf https://app.agnify.ai/install.sh | sh
```
If agnify isn’t found afterward, open a new terminal so the updated PATH takes effect.
Sign in.

On your own machine, sign in through your browser:
Terminal window
```
agnify login
agnify whoami
```
On a server with no browser (for example, a dedicated streaming box), use an API key instead — create one in Settings → API keys:
Terminal window
```
export AGNIFY_API_KEY=ak_xxx
```
If you belong to more than one organization, pick the one the camera should live in: agnify org list, then agnify org use <name>. (An API key already belongs to one organization, so you can skip this when using AGNIFY_API_KEY.)

Find your camera’s RTSP URL

RTSP URLs look like rtsp://USER:PASS@IP:554/path. The path is specific to your camera’s brand — check its manual or settings page. Common examples:

rtsp://USER:[email protected]:554/h264Preview_01_main
rtsp://USER:[email protected]:554/Streaming/Channels/101
rtsp://USER:[email protected]:554/stream1

Verify the URL works before connecting it to Agnify:

ffprobe -rtsp_transport tcp "rtsp://USER:[email protected]:554/h264Preview_01_main"

If ffprobe prints the stream’s details, the URL is good. If it errors, double-check the IP address, username/password, and that the camera is reachable from this computer.

Connect the camera to Agnify

agnify camera create my-camera

Now start streaming. Point the CLI at your camera’s RTSP URL:

agnify camera stream <cam-id> --source rtsp://USER:[email protected]:554/h264Preview_01_main

This keeps running and uploads footage continuously. Leave it open while you check that it’s working; press Ctrl-C to stop.

From another terminal, confirm the camera is live:

agnify camera list
agnify camera status <cam-id>

The status tells you what Agnify is seeing:

Status	Meaning
`live`	Footage is arriving right now.
`stale`	The CLI is connected, but footage has stopped flowing — check the camera.
`offline`	The CLI isn’t connected (it stopped, or lost the network).
`never_connected`	Nothing has streamed to this camera yet.
`paused`	The platform has paused the stream (set via the dashboard).
`stopped`	The stream has been administratively stopped (set via the dashboard).

You’ll also see this status in the dashboard under Settings → Cameras.

Keep it running

agnify camera stream runs in the foreground and stops if the connection drops or the computer reboots. To keep a camera streaming permanently, run it under a supervisor that restarts it automatically. On a server with no browser, authenticate with an API key (AGNIFY_API_KEY) since there’s no way to sign in interactively.

Recommended on Linux. This service restarts the stream if it ever exits unexpectedly, and starts it again after a reboot.

[Unit]
Description=Agnify camera stream
After=network-online.target
Wants=network-online.target

[Service]
Environment="AGNIFY_API_KEY=ak_xxx"
ExecStart=/usr/local/bin/agnify camera stream cam-xxxxx --source rtsp://USER:[email protected]:554/h264Preview_01_main
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now agnify-camera
journalctl -u agnify-camera -f          # watch the logs
sudo systemctl stop agnify-camera        # stop it

Save as ~/Library/LaunchAgents/ai.agnify.camera.plist, then load it. It relaunches the stream if it exits unexpectedly.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>ai.agnify.camera</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/agnify</string>
    <string>camera</string>
    <string>stream</string>
    <string>cam-xxxxx</string>
    <string>--source</string>
    <string>rtsp://USER:[email protected]:554/h264Preview_01_main</string>
  </array>
  <key>EnvironmentVariables</key>
  <dict>
    <key>AGNIFY_API_KEY</key>
    <string>ak_xxx</string>
  </dict>
  <key>KeepAlive</key>
  <dict>
    <key>SuccessfulExit</key>
    <false/>
  </dict>
  <key>RunAtLoad</key>
  <true/>
</dict>
</plist>

launchctl load ~/Library/LaunchAgents/ai.agnify.camera.plist
launchctl unload ~/Library/LaunchAgents/ai.agnify.camera.plist   # to stop

A simple loop for systems without systemd or launchd. It retries with a growing delay if the stream drops.

#!/bin/bash
export AGNIFY_API_KEY="ak_xxx"
CAMERA_ID="cam-xxxxx"
RTSP_URL="rtsp://USER:[email protected]:554/h264Preview_01_main"

delay=10
while true; do
  agnify camera stream "$CAMERA_ID" --source "$RTSP_URL"
  code=$?
  [ "$code" -eq 0 ] && break          # clean stop
  echo "stream exited ($code); retrying in ${delay}s"
  sleep "$delay"
  delay=$(( delay * 2 < 300 ? delay * 2 : 300 ))
done

Analyze the footage

Once your camera is streaming, analyze its footage from the Agnify dashboard:

Open the dashboard and start a new Camera playback analysis (use Camera playback (live) to analyze footage continuously as it arrives, or Camera playback to analyze a past time range).
Select your camera.
Choose a pipeline (for example, object detection or counting) and start the run.

Results appear in the dashboard as the run progresses.

From the CLI

agnify run create --camera starts the same analysis without leaving the terminal. Pick a pipeline with agnify templates list, then:

agnify run create --template object-detection --camera <cam-id> --start

Leave --to off for an open-ended live run that analyzes footage as it arrives; pass --from and --to to analyze a past window instead. Stop a live run with agnify run stop <execution-id>.

Troubleshooting

Symptom	What to do
CLI says `ffmpeg` / `ffprobe` is missing	Install them (see Prerequisites) and open a new terminal.
”could not read source” when streaming	Re-check the RTSP URL, username/password, and that the camera is reachable from this computer. Confirm the same `ffprobe -rtsp_transport tcp <url>` command works.
Camera shows `offline`	The CLI isn’t connected — it stopped or lost the network. Check it’s still running (or that your supervisor restarted it).
Camera shows `stale`	The CLI is connected but footage stopped arriving — the camera may have dropped the stream. Re-check the URL and the camera.
`401` / `403` errors	Sign in again (`agnify login`) or check your API key, and make sure you’re in the right organization. Creating a camera needs the owner or admin role.

Recap

The CLI reads your camera and uploads its footage to Agnify; it runs on a computer that can reach the camera.
agnify camera stream doesn’t restart itself — use a supervisor (systemd / launchd / bash) to keep it running, with an API key for unattended servers.
Analyze the footage from the dashboard, or with agnify run create --camera once the first segment has landed.