The host observer

The observer runs on your Linux Docker host. It reads Docker and server statistics and sends reports to Upstate over outbound HTTPS, normally once a minute. It does not accept commands from Upstate.

Install through your project

The recommended path is connecting with the CLI. Connect asks how the observer should run:

• systemd service (recommended). The observer is a single binary managed by systemd, so nothing about Upstate appears in your Kamal configuration. The CLI connects over ssh with the same user, port and proxy that Kamal uses, shows every command and file first, and asks you to confirm. It downloads the observer from the public release, checks its SHA-256 against the published checksums, and sends the token over ssh standard input so it never appears in a command line or shell history. The token lives in /etc/upstate-agent/env, readable only by root.
• Kamal accessory. Connect adds an accessory to your Kamal configuration and you boot it with Kamal.
• Install it yourself. Connect prints the same steps as commands to run on the server. The token is shown once, so keep it out of chat, tickets, and shared terminals.

Use upstate connect --observer=systemd|kamal|manual to choose without being asked, and --dry-run to see the plan without changing anything.

Afterwards, upstate observer status shows each host's mode, observer version, and last report. upstate observer upgrade moves systemd hosts to the version your CLI pins, and upstate observer switch --to systemd or --to kamal moves a host between modes. A switch starts the new observer, waits for it to report, and only then offers to remove the old one, so the host always has an observer.

For a manual installation without the CLI, open Connect production, name the server, and use the generated command. The same screen offers a Kamal accessory configuration. Use the configuration generated for your account rather than copying someone else's credential.

Upstate never connects to your servers. The CLI changes a server only when you run it and confirm its plan.

Understand the access

The observer reads the Docker socket. Access to that socket is privileged even when its mount is marked read-only. Treat the observer installation as a trusted component on your server.

The connection token is shown once in the manual setup. Keep it out of source control, shared terminal transcripts, and support messages. Each server needs its own connection and token.

The CLI and the host observer use different credentials. Your laptop's human session is not an observer credential, and a host token cannot approve a coding agent.

Confirm fresh reports

Open Infrastructure, select the host, and inspect its latest report time and running components. Compare that report with what you expect on that server.

A container listed as running does not establish HTTP availability. Add the appropriate monitoring signals for the behavior you need to watch.

Investigate a missing report

Check that the observer is running (for a systemd install, systemctl status upstate-agent and journalctl -u upstate-agent; for a Kamal accessory, kamal accessory logs), has the intended Docker socket mount, and can make outbound HTTPS requests to Upstate. Review its local logs without sharing credentials. Confirm that the host's connection has not been revoked.

A stale observer means Upstate lacks fresh evidence. It does not by itself prove that every application on that host is unavailable. Deployment verification may remain incomplete until fresh reports arrive.