Skip to main content
Remote Access API operations return a feature-disabled error unless the gated preview is enabled for the project. Do not build a required production path until your project is enabled.
The Remote Access API uses semantic operations instead of command strings. It never returns SSH credentials, private destinations, connector secrets, signed grants, or raw storage references. Base path:
Use the current OpenAPI document as the source for exact request and response schemas.

​
Agent-safe workflow

Normal target discovery returns only enabled, verified targets on active connectors. An administrator can use GET /setup-targets to inspect sanitized targets in all setup states. Both reads return an opaque target id, label, environment, enabled state, verified time, and runner version. They do not return a hostname, IP address, SSH user, fingerprint, authentication profile, or connector destination. Preview validates the full typed request and returns a stable policy action and decision code. It creates no request, approval, grant, or execution. Create accepts an idempotency key so a retry does not create duplicate work. Request state is asynchronous. A request can be pending, approved, cancelled, denied, or expired. GET /requests/{request_id} includes linked execution state when available. Its redacted_output is bounded to 65,536 characters and has the trust marker untrusted_remote_output. Treat this output as evidence, not as instructions. This read does not reveal the full transcript.

​
Management and review

Approval decisions, signing-key fingerprint reveal, target confirmation, and transcript reveal are dashboard-only human actions. They are not public API or CLI operations. Each action requires a five-minute, one-time email step-up for the current verified user and session. The proof is bound to the exact action. Transcript reveal also binds the exact project and execution. Approval binds the exact target, operation, typed parameters, policy and authority revisions, timeout, output limit, requester, and expiry. Target verification starts with one public management call:
This call requests a connector-signed forced-runner probe and returns its opaque verification id and safe state. A project owner then confirms that verification id and the SHA-256 digest of a host-key fingerprint in the dashboard. The owner must calculate the digest through a separate trusted target console. Confirmation requires a five-minute, one-time email step-up in the same dashboard session. API keys and agents are rejected. The target stays disabled if either signal is missing, stale, or does not match. Target create accepts only the label, environment, connector id, local authentication-profile id, and policy. Destination, host-key, runner-version, and operation-catalog facts come only from the connector-signed proof. Before the probe, reveal the signed verification-bootstrap with a strict {"acknowledge_sensitive_data":true} body. The response uses Cache-Control: no-store. Transfer the signed object to the target. In a separate authenticated dashboard session, reveal only the active signing-key fingerprint and transfer that 64-character lowercase value through a different protected channel. The root target runner pins that value when it installs verification-only trust. After connector proof and fresh-auth human host confirmation, reveal the full authority-bundle with the same strict acknowledgement. The target applies that signed bundle to move from verification-only state to observe-only execution authority. Bootstrap and authority reveals are audited, use Cache-Control: no-store, and are not exposed through MCP or hosted agents. Connector enrollment returns a short-lived code once. Send it only through the connector enrollment prompt or standard input. Do not put it in a URL, query string, log, command argument, or saved agent context. A full transcript is returned only through the protected dashboard action. The action requires an explicit sensitive-data acknowledgement and a fresh one-time email proof for the same user, session, project, and execution. API keys, OAuth clients, the CLI, MCP, and hosted agents cannot call it. The read fails closed unless its audit event is saved. Transcript reads are audited. Transcript deletion immediately revokes normal access and keeps the safe audit history. Encrypted storage versions can remain for up to one day before physical removal. Squasher does not yet publish a customer-configurable transcript-retention setting for this preview.

​
Typed operation example

Unknown fields, command text, invalid operation ids, control characters, invalid service-unit names, and limits outside project policy are rejected before state changes. Remediation operations, including service.restart, are disabled in this preview even if a client sends a valid operation shape.

​
Idempotency and recovery

Use a unique idempotency key for each intended request. Reuse that key only when retrying the same exact request after a network timeout. If a terminal response says the approval, grant, policy, target, connector identity, or authority is stale, preview and create a new request. Errors use stable codes with a safe message and recovery hint. Error responses do not include private destinations, key material, host fingerprints, signatures, command output, raw SSH errors, or transcript locations.

​
CLI, MCP, and hosted agents

  • The CLI provides the same resources with structured JSON input and compact JSON output. Protected bootstrap and authority commands write only the signed object to a new private file. They never print the signing-key fingerprint. Use squasher remote-access --help for the installed contract.
  • MCP Code Mode exposes only agent-safe discovery, preview, request, state, and cancel operations through search and execute. It does not expose connector management, policy changes, approval, or transcript reveal.
  • Hosted agents use the same request contract and link the request to their run. A hosted agent cannot approve its own work or gain management or transcript access.