Connect a camera

Run one command beside a camera you already have, and a page finds it and adds it to your workspace.

Connect a camera you already have by running one command on a computer beside it. A page opens on that computer, finds the camera and adds it to your workspace. At the end you can see the camera’s view.

You need Docker, on a computer that’s always on and on the camera’s network. There’s nothing to mount or ship.

Keep the camera where it is. A pan-tilt camera should stay parked on one view, because a camera that keeps moving leaves Dialect unsure of what it’s reading.

Run the command

In the console, open Gateways, then Add a gateway, then Your computer, and copy its command. For a first camera it’s this, the same on a Mac, Windows and Linux:

Start the gateway

You should see the container’s ID.

Open the page

Open http://localhost:8765 on the same computer. It looks for cameras, which takes under a minute, and lists what it finds.

The first browser to open the page keeps it, so nothing else on the computer can use the setup after that. To use another browser, or on a computer you share with people or programs you don't trust, run docker exec dialect-gateway dialect-gateway page and open the link it prints.

Choose your camera

Choose it and give its login. You should see a picture from it, so you can tell it’s the right one. Select Use this camera.

The password stays on this computer. It goes to the camera and into the container’s volume, and never to Dialect.

Add it to your workspace

Select Add to workspace, choose your workspace and select Add. The gateway starts within about 15 seconds. The page then says you’re done.

Check the view

On the gateway’s page in the console, open Check the view. You should see the camera live, and you can aim it. This is free, before you’ve paid.

Connect another camera

Run one container per camera. Each is its own gateway. The console’s command for your next camera has its own name, volume and port, such as http://localhost:8766, so copy it fresh each time. If Docker says a name or port is taken, it’s another camera’s on this computer: type a name under Other ways to connect and change the first number after -p and DIALECT_SETUP_PORT to a free port.

Each question you pay for covers one gateway, and before paying you have one. For another, add a question on Billing. See Billing.

Find your camera’s login

CameraWhat to do
TapoIn the Tapo app, open the camera’s settings, then Advanced Settings, then Camera Account, and create a username and password. Use those here, not your Tapo login. Letters and numbers work best. Most battery models can’t connect.
ReolinkIn the Reolink app, tap the gear, then More Features, Advanced Network Settings, Server Settings, and switch on RTSP. The username is admin unless you changed it, and the password is the one you chose when you set the camera up. Battery cameras need a Reolink hub.
HikvisionThe username is admin, and the password is the one created when the camera was first activated. Check it before trying again: after several wrong tries the camera blocks this computer for about 30 minutes.
DahuaThe username is admin, and the password is the one set when the camera was first set up. Check it before trying again: too many wrong tries locks the account for a while.
AmcrestUse the camera’s own username and password, not your Amcrest account. Some smart home models can’t connect.
LorexUse your Lorex recorder’s address and login, as its manual shows them. Only certain models can connect.
Ubiquiti UniFiIn UniFi Protect on the web, open the camera’s settings, go to Advanced and switch on RTSP. Copy the whole link it shows, choose Enter the address myself, and paste it there. It needs no username or password.
AxisAxis cameras have no preset password, so use the account created the first time the camera was opened. If nobody has, open the camera’s address in a browser and create one.
WyzeOnly some Wyze models have this, and the camera still needs the internet to start. In the Wyze app, pick the camera, open Advanced Settings, tap RTSP and set a username and password.
EufyIn the eufy app, open the camera’s settings and look for RTSP/NAS. If it isn’t there, this camera can’t connect. Choose continuous, copy the address it shows, choose Enter the address myself, and paste it there.

These can’t connect, because they keep their video to their own service:

CameraWhy
RingRing cameras send their video through Ring’s service, so Dialect can’t read them directly. This spot needs a different camera.
Google NestNest cameras don’t offer video Dialect can read directly on your network. This spot needs a different camera.
BlinkWe found no way to connect Blink cameras directly. This spot needs a different camera.
ArloArlo cameras talk only to their own hub and app, and we found no supported way to connect them. This spot needs a different camera.
SimpliSafeWe found no way to connect SimpliSafe cameras directly. This spot needs a different camera.
Logitech CircleWe found no way to connect Logitech Circle cameras. Circle View works only with Apple Home. This spot needs a different camera.
Apple Home onlyCameras that work only through Apple Home keep their video private to Apple devices, so Dialect can’t read them. This spot needs a different camera.

If no camera is found

The page says so, and you can enter the address yourself. The likely reasons:

  • The camera is off, or on a different network from this computer.
  • Its video isn’t switched on. See the table above.
  • It’s a make that can’t connect.
  • Docker can’t see your whole network. Docker on a Mac or Windows runs in a virtual machine, so the page finds a camera only if it answers a discovery question, or its router does. On Linux it also tries every address on your network.
  • A network with no router at .1, as some routers use .254, isn’t looked at. Enter the address yourself.

Change the camera

Choose a different camera

It restarts, its page asks again, and it stays in your workspace. The page itself never changes a saved camera: nothing else on your computer can, however it asks.

Connect without the page

For a server with no browser, or a camera whose address you already know, use Other ways to connect in the console. Choose Copy for your agent to hand the steps to a coding agent with a shell on that computer. It finds the camera, checks the address and starts the gateway, and your only job is to open the link it sends you.

Every command below except run answers in JSON, and every problem has a stable code, a message and a fix, so an agent can do this unaided.

To use the page from another computer, forward its port: ssh -L 8765:localhost:8765 <server>.

Find the camera

This lists the cameras the computer can reach, with their RTSP ports, and the ONVIF name and model when the camera gives them. It works from any computer. On Linux, --network host also finds cameras that only answer on the local network.

Find cameras on your network

You should see each camera it found:

Response from discover

Check the address

This answers "ok": true and the stream’s size, or the problem. For a wrong path, the fix names the paths the camera does answer at.

Check a camera’s address

You should see:

Response when the address works

Start the gateway

Start the gateway with its address

You should see the container’s ID. Its status phase then reads waiting_for_claim. With DIALECT_CAMERA set there is no page, and the container opens no ports.

Print its link, open it, choose your workspace and select Add.

Print the gateway’s link

You should see https://dialectlayer.com/claim/<serial>#<secret>.

Set its options

VariableWhat it is
DIALECT_CAMERAThe camera’s rtsp:// or rtsps:// address. Without it, the container serves its setup page. A /, ? or # in its password must be URL-encoded as %2F, %3F or %23
DIALECT_GATEWAY_NAMEThe gateway ID it asks for. Optional. Lowercase letters, digits and dashes, starting with a letter, 2 to 63 characters. A workspace that already has that ID gets -2 on the end. Without it, the ID is gateway- and six characters of its serial
DIALECT_SETUP_PORTThe port on this computer that -p publishes the setup page on, when it isn’t 8765. The page answers only at that port

These are common stream paths, which the page tries for you:

MakePath
Tapo/stream1 (full) or /stream2 (smaller)
Reolink/Preview_01_main
Hikvision/Streaming/Channels/101
Dahua, Amcrest, Lorex/cam/realmonitor?channel=1&subtype=0
Axis/axis-media/media.amp

To keep the camera’s password out of your shell history, put the settings in a file with mode 600 and pass --env-file instead of -e.

To change an address given in DIALECT_CAMERA, run docker rm -f dialect-loading-dock and start it again with the new one. Its volume keeps it added, so there’s no new link.

Check what it connects to

It makes the RTSP connection to the camera and outbound HTTPS connections, which carry pictures out to be read and kept. It runs as uid 10001 and keeps its state in /var/lib/dialect.

The setup page is published on this computer alone (127.0.0.1). It answers only requests addressed to its own host and port and sent by the page itself, so other websites can’t reach it. It looks for cameras only while you’re on it, and only on private networks.

Check its status

Read the gateway’s status

You should see this while it reads:

Response while it reads

It exits 0 only while it reads, and it’s the image’s health check, so docker ps shows healthy only then. docker logs dialect-gateway says each step in words.

phaseMeans
waiting_for_setupWaiting for someone to choose a camera on its page
enrollingRegistering with Dialect
waiting_for_claimWaiting for someone to open its link. claim_url holds it
waiting_for_cameraAdded, and waiting for the camera to answer
runningRunning. device says how: reading, camera_problem, needs_network and others
stoppedA setting needs changing. It says so and waits, since a restart wouldn’t help

Fix a problem

codeWhat to change
camera_not_setDIALECT_CAMERA isn’t an rtsp:// address
camera_login_not_encodedURL-encode the /, ? or # in the camera’s password
registration_refusedDIALECT_GATEWAY_NAME isn’t a gateway ID, or the volume’s key was registered with another link. Start with a new volume
gateway_refusedThe gateway was revoked or retired. Start with a new volume for a new link
camera_not_found, camera_unreachable, camera_not_rtspThe address: the camera is off, on another network, or has RTSP switched off
camera_login_needed, camera_login_refusedThe login: the camera’s own RTSP login, which can differ from its app or cloud account
camera_path_not_foundThe path: the fix names one the camera answers at
camera_no_pictureThe camera has as many viewers as it allows. Close one, or use its other stream

A camera or network that isn’t there yet is waited for. While it’s added and its camera doesn’t answer, the gateway stays online and the console says why.

If a Mac can’t reach the camera

Docker on macOS runs in a virtual machine, and macOS’s Local Network privacy can stop it reaching cameras on your network. The page then finds none, and the camera doesn’t answer when you enter its address. Allow your Docker app under System Settings, Privacy & Security, Local Network, or run it on a Linux server instead.

Update the gateway

Pull the new image, then remove the old container

Then run the same docker run command. The volume keeps its enrollment and the camera you chose. Each image is tagged latest and with the commit it was built from.

Know when it goes quiet

The console calls a gateway offline after 30 seconds of silence. After 5 minutes, a gateway in use opens an alert of its own. Stopping it on purpose with docker stop opens none.

Next steps