Getting started

Start with an existing Kamal project, access to its servers, and an Upstate account. Create an account or log in, then select the account that should own this project.

Install the CLI

On a computer with Homebrew:

brew install upstate-run/tap/upstate
upstate version

You can also download a macOS or Linux binary from the CLI releases. Match your operating system and CPU, verify the archive against its published checksums, and put the binary on your PATH.

Preview the connection

From your Kamal project folder:

upstate connect --dry-run

The dry run changes no local or remote resources and does not authenticate. Review the discovered service, destinations, roles, and hosts. Dynamic configuration may need explicit answers before Upstate can connect it safely.

Connect your project

upstate connect

If you are not authenticated, the CLI opens a browser approval flow. Check the code and account before approving. Review the hooks and observer setup before applying the proposed changes.

Connect asks how the observer should run on your servers: as a systemd service (recommended; it keeps Upstate out of your Kamal config), as a Kamal accessory, or you can install it yourself from printed instructions. Choose without the question using upstate connect --observer=systemd, --observer=kamal or --observer=manual. For systemd, the CLI shows the exact ssh commands and files for each server and waits for your confirmation before changing anything; --dry-run shows the plan and changes nothing. Upstate itself never connects to your servers.

If you have saved logins for several accounts, connect says which account it is using. Choose another with --account NAME, or change your default with upstate account use NAME.

Connect can discover several Kamal destinations in one repository. Use --destination NAME when you intend to connect only one. Existing deploy hooks are preserved and called by the installed wrappers.

Already signed in to another account?

The CLI connects to the account it is signed in to, not the one open in your browser. If you belong to more than one account, point it at the right one first:

upstate account list
upstate account use <name-or-public-id>

account list shows the accounts the CLI is signed in to. If the account you want is not listed, connect with --account. It opens a browser approval for the account you name; check the code and account name before you approve.

upstate connect --account <name-or-public-id>
upstate auth whoami

A second account you own needs the Solo plan before it can watch servers. Your first account stays on Free.

Using another Upstate address?

The CLI talks to https://upstate.cloud. You only need to change that for a self-hosted or local development copy of Upstate:

export UPSTATE_URL=https://upstate.example.com

This is different from upstate connect --url, which sets your app's public URL for the web check.

Prefer a manual setup? Open Connect production. Each server needs its own connection and observer credential. See the host observer for what that installation can access.

Check the first report

Open your overview and find the connected project and hosts. Check the latest report time and discovered components. A connection record alone does not mean the observer has reported successfully.

upstate status
upstate doctor

Use doctor to investigate missing local credentials or configuration. If reports are missing, run upstate observer status and check the observer service or container and its outbound connection before treating the application itself as down.

Watch your next deployment

kamal deploy
upstate receipt --watch

The deploy hooks report lifecycle facts while the observer independently reports what is running. Deployment receipts explain the resulting verdict and any missing evidence.