Install and verify

Install the CLI, sign in, and connect your agent.

For signup and setup through your agent, start with the Quickstart. To set up an approved account yourself, follow the steps below.

The CLI connects your agent to Synkro's hosted service. Existing service settings are preserved when you upgrade.

New signup is currently available in sandbox for approved testers. Before sign-in, set the sandbox App in each terminal session:

export SYNKRO_WEB_AUTH_URL="https://app.sandbox.synkro.sh"

Use test cards only. Keep an existing production installation separate; do not overwrite its credentials to try sandbox.

Supported machines

Ubuntu 22.04 and newer are supported.

Install with Homebrew

On macOS, install Homebrew first if brew --version fails. On Linux, prefer the direct download below, especially on Ubuntu 22.04 or without administrator access. If you already use Homebrew, run:

brew install synkro-sh/tap/synkro

On older Linux systems, Homebrew may install its own compiler and system libraries. The direct download avoids those dependencies.

Check the installed commands:

command -v synkro
synkro --version

If command -v synkro points to a development build, fix your PATH before continuing.

Update an existing installation

brew update
brew upgrade synkro-sh/tap/synkro
synkro update --yes
synkro --version
synkro status

Homebrew updates the CLI. synkro update --yes updates its installed components, not a hosted server. Start a new agent session afterward. If you installed directly on Linux, repeat the download below instead of the Homebrew commands, then run synkro update --yes.

Your agent can let you know when a newer CLI version is available and offer to update it with your approval. Declining keeps your work going. You can also run synkro update --check to check without installing anything. Hosted service versions are managed separately.

Linux without Homebrew

Recommended on Linux. This installs 0.2.0-rc.24 into your account without sudo or Homebrew. You need Git, curl, tar, CA certificates and sha256sum. The CLI includes its TLS library; no OpenSSL package or compiler is needed. The archive and checksum come from the same release. Run the whole block in a shell:

(
  set -eu
  case "$(uname -m)" in
    x86_64)
      synkro_target=x86_64-unknown-linux-gnu
      ;;
    aarch64|arm64)
      synkro_target=aarch64-unknown-linux-gnu
      ;;
    *) echo "Unsupported Linux architecture" >&2; exit 1 ;;
  esac
  synkro_tmp="$(mktemp -d)"
  synkro_archive="synkro-${synkro_target}.tar.gz"
  synkro_release="https://github.com/synkro-sh/homebrew-tap/releases/download/v0.2.0-rc.24"
  curl -fL "${synkro_release}/${synkro_archive}" \
    -o "${synkro_tmp}/${synkro_archive}"
  curl -fL "${synkro_release}/SHA256SUMS" -o "${synkro_tmp}/SHA256SUMS"
  awk -v name="$synkro_archive" '$2 == name { print }' "${synkro_tmp}/SHA256SUMS" \
    > "${synkro_tmp}/selected.sha256"
  test "$(wc -l < "${synkro_tmp}/selected.sha256")" -eq 1
  (cd "$synkro_tmp" && sha256sum --strict -c selected.sha256)
  tar -xzf "${synkro_tmp}/${synkro_archive}" -C "$synkro_tmp"
  mkdir -p "$HOME/.local/bin"
  install -m 0755 "${synkro_tmp}/synkro" "$HOME/.local/bin/synkro"
)

Add the install directory to this terminal's PATH:

export PATH="$HOME/.local/bin:$PATH"
command -v synkro
synkro --version

Add the same export line to your shell startup file to keep it for future terminals.

Connect to a hosted Synkro service

Run synkro install --no-browser to use the service selected during sign-in. If your administrator provides a different Synkro service, use:

synkro install --daemon-url https://your-synkro-service.example --no-browser
synkro whoami
synkro status --json

Replace the example URL with the one provided to you. Confirm endpoint names that service and enforcement is active.

Sign in and connect your agent

synkro install

Complete sign-in in the browser. The installer configures detected agents.

Do not paste passwords or tokens into the terminal or agent conversation.

For SSH or a machine without a usable browser:

synkro install --no-browser

Open the printed verification URL on another device and enter the short code. If the terminal only shows the code, open Synkro device sign-in. Keep the matching terminal process running until it finishes, then run synkro whoami to confirm sign-in.

Check the result

synkro whoami --json
synkro status --json

Confirm:

• Your identity and organization are correct.
• If the CLI reports installationEnforcement, use that installation-specific state. Anonymous server health alone cannot prove that your account is connected.
• running and healthy are true.
• health.enforcement.state is active.
• There is no semantic-check warning if you need semantic Rules.
• Your agent's configuration and plugin checks pass.

For a null plugin status, check that setting in your agent's interface.

Add the project and verify an action

In a repository without synkro.toml, run synkro init, review the files, then run synkro lock to write synkro.lock. Keep existing project settings if they are already present.

Start a new agent session, ask it to run git status --short, and check:

synkro events --type verdict --limit 5 --details

Match the new decision to that command. See Verify a decision if it is missing.

Remove the integration

Run synkro uninstall to remove Synkro's agent integrations and managed hook executable. It preserves unrelated settings, your Homebrew package and recorded history.