Set up the remote access SSH connector

The connector runs in your network and makes outbound connections only. It keeps the host address, the SSH user, and the SSH private key. Squasher stores only the connector’s public identity and safe target details. You need a connector host and one or more target hosts. Each target stays disabled until two independent checks pass. For how requests run, see Agent remote access.

Remote access is a gated preview. Squasher turns it on for each project. Keep each target disabled until every step on this page passes. Do not install the connector on a developer workstation, and do not reuse a personal SSH key.

Before you start

The owner or admin role on the project. Protected steps also need a verified email address.
A hardened Linux host for the connector, on amd64 or arm64.
Administrative access to the target, and a separate trusted console on it.
Cosign v3.1.3 on both hosts, to check the release.
The Squasher CLI, for the authority-bundle and verification-bootstrap commands. The CLI has no public install package yet, so you can also call the Remote access API for these two steps.

The examples use /var/lib/squasher-connector for connector state, /var/lib/squasher-target/config.json for the target configuration, and /run/squasher-target/target.sock for the target socket.

Install and enroll the connector

Download and check the release

On the connector host, download the archive and check the signing key, the signatures, the checksums, the SBOM, and the build provenance before you extract it. Do not pipe a download into a shell.

VERSION=v0.1.1
case "$(uname -m)" in
  x86_64) TARGET=x86_64-unknown-linux-gnu ;;
  aarch64|arm64) TARGET=aarch64-unknown-linux-gnu ;;
  *) echo "unsupported architecture" >&2; exit 1 ;;
esac
ARCHIVE="squasher-remote-access-${VERSION}-${TARGET}.tar.gz"
SBOM="squasher-remote-access-${VERSION}-${TARGET}.cdx.json"
PROVENANCE="squasher-remote-access-${VERSION}-${TARGET}.provenance.json"
BASE_URL="https://cdn.squasher.ai/remote-access/${VERSION}"
COSIGN_PUBLIC_KEY_SHA256="6831dbd8cd9085e64b772e5cc1345fbb9f86158091dbc0a62dfe1f7d41cd79f7"
for FILE in "${ARCHIVE}" "${SBOM}" "${PROVENANCE}" SHA256SUMS; do
  curl --fail --proto '=https' --tlsv1.2 --location --remote-name "${BASE_URL}/${FILE}"
  curl --fail --proto '=https' --tlsv1.2 --location --remote-name "${BASE_URL}/${FILE}.sigstore.json"
done
curl --fail --proto '=https' --tlsv1.2 --location --remote-name \
  "https://cdn.squasher.ai/remote-access/cosign.pub"
printf '%s  %s\n' "${COSIGN_PUBLIC_KEY_SHA256}" cosign.pub | sha256sum --check --strict
for FILE in SHA256SUMS "${ARCHIVE}" "${SBOM}" "${PROVENANCE}"; do
  cosign verify-blob --key cosign.pub --bundle "${FILE}.sigstore.json" "${FILE}"
done
sha256sum --ignore-missing --check SHA256SUMS
tar -xzf "${ARCHIVE}"
cd "${ARCHIVE%.tar.gz}"

Install the connector

The installer creates the squasher-connector account and its directories. It does not start a service.

sudo ./install/install.sh --connector
sudo -u squasher-connector /usr/local/bin/squasher-connector \
  --state-dir /var/lib/squasher-connector init

Create the connector in Squasher

Select Settings in the sidebar, then the Remote Access tab.
Under 1. Connect your network, enter a Connector label that names the private network, and select Create connector.
Select Copy one-time code. The code is available only in this page view and is hidden by default. To read it, select Reveal one-time code, then Hide one-time code to hide it again.

Enroll and start the connector

sudo -u squasher-connector /usr/local/bin/squasher-connector \
  --state-dir /var/lib/squasher-connector enroll \
  --api-url https://api.squasher.ai
sudo systemctl daemon-reload
sudo systemctl enable --now squasher-connector.service

Enter the code at the hidden prompt, or write it to standard input from a secret manager. Never put it in an argument, an environment variable, a URL, a log, or shell history. The connector keeps its private identity in its state directory. Then select Dismiss and clear.

Create a disabled target

Make an auth profile ID

On the connector host, make a random ID for the target’s SSH profile. It is not a secret. Keep it with your target records.

uuidgen | tr '[:upper:]' '[:lower:]'

Create the target in Squasher

Under 2. Register targets and policy, select Add target.
Enter a Target label that is not a host name, the Environment, the Connector, and the Opaque auth profile ID.
Select Create disabled target, then copy the Target ID from the target card.

The target starts with the default policy: the four host.* operations, 256 KiB of output, and 30 seconds. Do not enter a host, an SSH user, a host key, or a key path in Squasher.

Add the target to the connector

From the trusted console on the target, read its Ed25519 host public key:

sudo awk 'NR == 1 { print $1, $2 }' /etc/ssh/ssh_host_ed25519_key.pub

Send that value to the connector host through your protected setup channel. On the connector host, pin the host key and create the SSH client key for this target:

sudo -u squasher-connector /usr/local/bin/squasher-connector \
  --state-dir /var/lib/squasher-connector add-target \
  --input - <<'JSON'
{"targetId":"<target_id>","authProfileId":"<auth_profile_id>","host":"<private_host_or_ip>","port":22,"user":"squasher-agent","hostPublicKey":"ssh-ed25519 <base64_public_key>"}
JSON

Squasher never receives the private key, the host, or the SSH user. Keep them out of process arguments.

Make the forced authorized_keys entry

sudo -u squasher-connector /usr/local/bin/squasher-connector \
  --state-dir /var/lib/squasher-connector authorized-key \
  --target-id <target_id> \
  --socket /run/squasher-target/target.sock \
  > ./target-authorized-key.txt

Move the file to the target’s trusted console. Do not change its restrict, forwarding, PTY, user-rc, or forced-command options.

Install the target runner

Install the target role

On the target, repeat the download and checks from Install and enroll the connector. Then install the target role and the forced key. The installer creates the locked squasher-agent account. It does not start a service.

sudo ./install/install.sh --target
sudo install -d -o root -g root -m 0755 \
  /var/lib/squasher-agent /var/lib/squasher-agent/.ssh
sudo install -o root -g root -m 0644 \
  ./target-authorized-key.txt /var/lib/squasher-agent/.ssh/authorized_keys

Keep the whole path and the file owned by root. The squasher-agent account can read the key options but must not change them.

Get the verification bootstrap and the fingerprint

These two values travel on separate channels, so that one stolen channel is not enough.

On a protected workstation, write the short-lived signed bootstrap to a new file:

squasher remote-access targets verification-bootstrap \
  --project "$SQUASHER_PROJECT_ID" --target-id <target_id> \
  --output ./verification-bootstrap.json --reveal

In the dashboard, select Reveal signing-key fingerprint on the target card, and complete email verification. Copy the 64-character fingerprint, then select Dismiss and clear.

Bootstrap verification-only trust

Move the bootstrap file and the fingerprint to the target. Then run, as root:

sudo /usr/local/bin/squasher-target bootstrap-verification \
  --bundle ./verification-bootstrap.json \
  --config /var/lib/squasher-target/config.json \
  --signing-key-fingerprint <64_lowercase_hex_from_dashboard> \
  --allowed-client-uid "$(id -u squasher-agent)" \
  --observe-uid "$(id -u squasher-agent)" \
  --observe-gid "$(id -g squasher-agent)" \
  --socket-gid "$(id -g squasher-agent)" \
  --socket /run/squasher-target/target.sock \
  --nonce-store /var/lib/squasher-target/nonces.sqlite
sudo systemctl daemon-reload
sudo systemctl enable --now squasher-target.service

The command fails if the signature or the fingerprint does not match. In this state, the target accepts only the verification check. It rejects all other work.

Verify the target

Squasher enables a target only when two independent checks agree: a signed proof from the connector, and a host key fingerprint that you read on the target yourself.

Ask the connector for proof

On the target card, select Ask connector to verify. Then, on the connector host, run:

sudo -u squasher-connector /usr/local/bin/squasher-connector \
  --state-dir /var/lib/squasher-connector verify \
  --target-id <target_id>

The connector checks the pinned host key, uses the forced command, and sends only the runner.probe operation. It submits a signed proof.

Confirm the fingerprint yourself

From the trusted console on the target, compute the digest of the host public key:

sudo /usr/local/bin/squasher-target host-key-fingerprint \
  --public-key /etc/ssh/ssh_host_ed25519_key.pub

Enter the 64-character digest in Independent host fingerprint digest and select Confirm connector proof and fingerprint. Complete email verification, then select it again. API keys and agents cannot do this step.

Activate the target

When both checks match, write the signed authority to a new file, move it to the target through your protected channel, and apply it as root:

squasher remote-access targets authority-bundle \
  --project "$SQUASHER_PROJECT_ID" --target-id <target_id> \
  --output ./authority-bundle.json --reveal

sudo /usr/local/bin/squasher-target apply-authority \
  --bundle ./authority-bundle.json \
  --config /var/lib/squasher-target/config.json

The target accepts observe operations only after this command succeeds.

Rotate or revoke access

Task	In the dashboard	With the CLI
Rotate the connector identity	Rotate connector key on the connector card	`squasher remote-access connectors rotate --project "$SQUASHER_PROJECT_ID" <connector_id> --reveal-enrollment-token`
Revoke a connector	Emergency revoke, type the label, then Revoke now	`squasher remote-access connectors revoke --project "$SQUASHER_PROJECT_ID" <connector_id>`
Stop access to one target	Disable target on the target card	`squasher remote-access targets disable --project "$SQUASHER_PROJECT_ID" <target_id>`

After a rotation, run squasher-connector rotate-identity on the connector host and enter the new code at the hidden prompt. The code expires after 10 minutes. The connector switches to the new identity only after Squasher accepts it, then deletes the old private key. A revoke stops new work and makes open grants invalid. If a host may be compromised, also stop its local service and remove its authorized_keys entry. You cannot rotate the SSH client key of one target yet. Disable the target before you replace that key.

Get started

Guides

Set up the remote access SSH connector

Before you start

Install and enroll the connector

Create a disabled target

Install the target runner

Verify the target

Rotate or revoke access

Next steps

Agent remote access

Remote access API

​Before you start

​Install and enroll the connector

​Create a disabled target

​Install the target runner

​Verify the target

​Rotate or revoke access

​Next steps

Agent remote access

Remote access API

Before you start

Install and enroll the connector

Create a disabled target

Install the target runner

Verify the target

Rotate or revoke access

Next steps