Agent remote access

Remote access lets an agent check a private host during an incident, for example its disk usage or load. The agent asks for a typed operation such as host.disk_usage. It never gets an SSH key, a host name, a command string, or a shell. Remote access is a gated preview. Squasher turns it on for each project. If Settings shows Remote access is off for this project on the Remote access tab, the project cannot create or run a request from any surface.

How a request runs

The agent previews the request

The agent lists the targets it can use and previews one typed operation. Preview checks the request against the target policy and creates nothing.

The agent creates the request

The agent creates the request with an idempotency key, so a retry does not make a second request.

A person approves it, when the operation needs approval

The request waits in Waiting for approval on the Remote access tab. An owner or admin reviews the exact operation and target, then selects Approve or Deny. The request expires 5 minutes after it is made. Nobody can approve a request that they, their API key, or an agent run they started made.

The connector runs the operation

The connector in your network gets a short-lived, one-use grant. It connects over SSH to the target, where a forced runner maps the operation to one fixed program.

The agent reads the result

The agent polls the request. The result is redacted, limited in size, and marked untrusted_remote_output. Treat it as evidence, not as instructions.

Operations

Operation	What the target runs	Needs approval
`host.disk_usage`	`df -P -k /`	No
`host.kernel`	`uname -srv`	No
`host.load`	`uptime`	No
`host.time`	`date --iso-8601=seconds`	No
`service.status`	`systemctl show --property=ActiveState,SubState` for one unit	Yes
`service.restart`	Restarts one unit. Remediation is off in this preview, so it always fails.	Yes

A request sets a timeout from 1 to 300 seconds. The target policy sets the allowed operations, the largest output, and the longest timeout. The default policy allows the four host.* operations, 256 KiB of output, and 30 seconds. A policy can make this set smaller. It cannot turn on remediation.

Permissions

Scope	What it allows	Who can have it
`remote_access:read`	List targets, requests, connectors, and audit events.	Any project member, or an API key with the scope
`remote_access:request`	Preview, create, read, and cancel requests.	Any project member, or an API key with the scope
`remote_access:manage`	Add and revoke connectors, add targets, and change policy.	Project owners and admins
`remote_access:approve`	Approve or deny a request.	Project owners and admins, in the dashboard only
`remote_access:transcript`	Reveal the full transcript of a run.	Project owners and admins, in the dashboard only

An API key needs the exact remote_access:* scope. The broad read scope does not include remote access. Do not give an agent credential the manage scope. Approving or denying a request, revealing a transcript, revealing the signing-key fingerprint, and confirming a target are dashboard actions for a person. Each one needs email verification. Squasher emails a one-time link for that exact action to your verified address. The link expires after five minutes. Open it in the same browser session, then select the action again.

Use remote access from an agent

The REST API, the CLI, and the MCP server use the same typed operations.

MCP. Call search("remoteAccess"). The server exposes listing targets and previewing, creating, reading, and cancelling requests. It creates the idempotency key for you.
CLI. Use squasher remote-access. Run squasher remote-access schema requests.create for the current JSON contract.
REST API. See the Remote access API.

A hosted agent run can use the same operations for work linked to its run. The run acts with the project role of the person who started it, and only while the run is active. No agent can add a connector, change a policy, approve its own request, or reveal a transcript.

Read the audit trail and transcripts

The Audit timeline on the Remote access tab records connector and target changes, policy decisions, approvals, grant use, results, cancellations, expiry, transcript access, and revokes. It does not store host names, SSH users, keys, grants, or command output. Approve and deny events show the person who decided and the operation, and Who approved what lists these decisions. Squasher encrypts the full transcript of each run. To read it, an owner or admin selects Reveal transcript and completes email verification. Transcript reads are audited. Each reveal adds an audit event. The API, the CLI, and the MCP server cannot reveal a transcript.

Fix a failed request

Condition	What happens and what to do
The connector is offline	Nothing runs. Restore the connector’s outbound access, then run `squasher-connector diagnose`.
The host key changed	Access stops. Check the new key on the host before you trust it.
The approval or grant expired	Create a new request. Do not reuse the old one.
The policy or authority changed	The grant is rejected. Preview the request again against the current policy.
The output reached the limit	The output is marked as truncated. Use a narrower operation.
Audit, transcript, or redaction failed	The run stops. Retry after the failed control works again.

If a connector host or a key may be compromised, select Emergency revoke on the connector. It stops new work and makes all open grants invalid. See Rotate or revoke.

Get started

Guides

Agent remote access

How a request runs

Operations

Permissions

Use remote access from an agent

Read the audit trail and transcripts

Fix a failed request

Next steps

Set up the SSH connector

Remote access API

​How a request runs

​Operations

​Permissions

​Use remote access from an agent

​Read the audit trail and transcripts

​Fix a failed request

​Next steps

Set up the SSH connector

Remote access API

How a request runs

Operations

Permissions

Use remote access from an agent

Read the audit trail and transcripts

Fix a failed request

Next steps