Open caret from another device¶
Audience: anyone who wants caret's review page on a phone, tablet, or another computer.
To open the review page on another device, set up
the computer that runs caret (the server), then open a login link on each device. The
server runs a background service: the one
caret install keeps running, or one caret serve runs. Do the first four sections in
order. The steps are the same in every agent host.
By default, caret listens on 127.0.0.1 only, with no login. These steps assume a network
you trust. On any other network, read Use an HTTPS proxy first.
Set the address¶
In the [daemon] table of the server's config.toml (keys
in
The [daemon] and [review] tables),
bind caret to the network and give it a name:
An exposed host, one outside loopback, turns token login on: devices then need the login
link below.
caret answers only to the hostnames entries, and to host when it is a specific
address. It refuses any other name with 403 host not recognized. So with a wildcard bind
(0.0.0.0 or ::), a device that reaches the server by IP address needs that IP in
hostnames. Printed links use the first hostnames entry.
A specific address in host also works, but then caret can't start while that address is
missing: after a network or DHCP change, or a boot that beats the network. caret exits
rather than waiting, so prefer a wildcard bind plus hostnames.
If the server runs a firewall, allow incoming TCP on port.
Point a DNS record at the server¶
Skip this step if devices reach the server by an IP you listed.
In your router or local DNS server, add an A or AAAA record from the first hostnames
entry to the server's LAN address. A computer can use a hosts-file entry instead.
Avoid a multicast DNS (mDNS) .local name: any device on the LAN can answer a .local
lookup and receive the token.
Restart the background service¶
These keys take effect on the next start:
- For
caret serve, pressctrl+cand run it again. - For the service
caret installsets up, use its restart command, or runcaret install --refresh.
Open the login link on each device¶
caret serve prints the login link on every start. Otherwise, run caret login-link:
Open the link once on each device. It sets a cookie that keeps the device logged in. The link is a secret: anyone holding it can log in.
caret login-link reads config.toml and the token file, not the running background
service, so its link works only once the background service has restarted.
Set up the other devices¶
A device that only opens the review page needs a browser and the login link, not caret. Only the server runs caret as a service.
If another device runs caret for its own agent, answer I'll run it myself when
caret install asks. Unless it sends its plans to the server, keep the server's host
and hostnames out of that device's config.toml. Otherwise its background service also
listens on the network and prints links to the server's name. Those links open the server,
so you never see the device's own reviews.
By default, an agent on another device reviews its plans on that device's own background
service, at caret.localhost. To review them on the server instead, see
Send plans to caret on a server.
Log every device out¶
Delete the token file, then restart the background service:
caret mints a new token at start, so every device's cookie stops matching. Open the new
link from caret login-link on each device you keep.
Use an HTTPS proxy¶
caret speaks plain HTTP, so everything crosses the LAN unencrypted, including the token in the link and the cookie. On a network you don't trust, put caret behind an HTTPS reverse proxy rather than exposing the bind:
-
Run the proxy on the same machine and keep
hoston loopback. List the proxy's name inhostnames, and setauth = "token", since a loopback bind leaves the login off otherwise: -
Have the proxy send
X-Forwarded-Proto: https. Caddy does by default; nginx needsproxy_set_header X-Forwarded-Proto $scheme;. A login through the proxy then sets aSecurecookie, which a browser never sends over plainhttp://. caret trusts that header only whilehostis loopback. - Rewrite each link caret prints,
http://<name>:<port>, to the proxy'shttps://<name>/, keeping the?token=part.
Configured names match on any port and over https, so the proxy's requests pass. A
device already logged in keeps its old cookie until it opens the https:// login link
again.
Turn the login off¶
Set auth = "none" on an exposed bind. Devices then open http://<name>:<port>/
directly, and caret login-link prints that URL instead of a link.
Warning
With the login off, anyone who can reach the port can read plans, read files under a
review's working directory, and approve a plan. caret serve and caret login-link
warn while auth = "none" is set.
If caret stays on loopback¶
- An invalid
config.tomlleaves caret on loopback with token login on, rather than falling back to no login.caret serveandcaret login-linkthen print a link tocaret.localhostinstead of yourhostnamesname. - An older caret ignores these keys and keeps listening on loopback only.
Next steps¶
- Send another computer's plans to this server with Send plans to caret on a server.
- Keep the server's background service up with Run the background service.