> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squasher.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Remote Access API

> Preview, request, inspect, and revoke typed remote operations.

<Warning>
  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.
</Warning>

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:

```text theme={null}
https://api.squasher.ai/v1/projects/{project_id}/remote-access
```

Use the current [OpenAPI document](https://api.squasher.ai/openapi.json) as the source for exact request and response schemas.

## Agent-safe workflow

| Action                 | Method and path                      | Scope                   |
| ---------------------- | ------------------------------------ | ----------------------- |
| List sanitized targets | `GET /targets`                       | `remote_access:read`    |
| Preview a request      | `POST /requests/preview`             | `remote_access:request` |
| Create a request       | `POST /requests`                     | `remote_access:request` |
| Read request state     | `GET /requests/{request_id}`         | `remote_access:request` |
| Cancel a request       | `POST /requests/{request_id}/cancel` | `remote_access:request` |

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

| Resource                                             | Typical actions                              | Access                 |
| ---------------------------------------------------- | -------------------------------------------- | ---------------------- |
| `/connectors`                                        | Create, rotate, read, and revoke             | `remote_access:manage` |
| `GET /setup-targets`                                 | Read targets in every setup state            | `remote_access:manage` |
| `POST /targets`                                      | Create a disabled target intent              | `remote_access:manage` |
| `/targets/{target_id}/verification-bootstrap/reveal` | Reveal signed pre-trust setup material       | `remote_access:manage` |
| `/targets/{target_id}/authority-bundle/reveal`       | Reveal signed post-verification authority    | `remote_access:manage` |
| `/targets/{target_id}/policy`, `/policies/validate`  | Read, validate, and append a policy revision | `remote_access:manage` |
| `/approvals`                                         | Read sanitized pending review context        | Authenticated user     |
| `/executions`                                        | Read safe execution state                    | `remote_access:read`   |
| `/audit`                                             | Read the safe audit timeline                 | `remote_access:read`   |

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:

```text theme={null}
POST /targets/{target_id}/verification-requests
```

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

```json theme={null}
{
  "target_id": "11111111-1111-4111-8111-111111111111",
  "operation": {
    "id": "host.disk_usage",
    "parameters": {}
  },
  "timeout_seconds": 15
}
```

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.

## Related docs

* [Agent remote access](/features/remote-access)
* [SSH connector setup](/integrations/remote-access)
* [MCP](/integrations/mcp)
* [CLI Reference](/integrations/cli-reference)