# Private Relay

Private Relay lets an external application reach models on your computers through `https://api.actual.inc`. You need an inference credential, a connected computer, and a model loaded and ready to serve.

## Where inference runs and how requests travel

Model execution and request transport are separate. Owning the serving computer does not mean a request stays on the device where you type it.

| Use                                                                                 | Model execution                                                      | Request path                                                                                                 |
| ----------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Same-machine application using a loopback endpoint, with standalone local execution | That computer                                                        | Its local API, without the public relay for inference.                                                       |
| Web chat                                                                            | The selected eligible computer or cluster                            | Browser → Actual web platform → Private Relay → serving computer(s). The web proxy handles the request body. |
| Application using `api.actual.inc`                                                  | An eligible owned or shared cluster; pin the destination when needed | Application → public relay → serving computer(s).                                                            |
| Multi-computer cluster                                                              | Participating computers                                              | Inference data can move between cluster members.                                                             |
| Explicit offline mode                                                               | One standalone computer                                              | Local API; public relay and LAN clustering are unavailable.                                                  |

The web chat label identifies the selected destination, or the destination sent with an active request. It does not claim successful execution before a response arrives. An offline or removed selection must be reconnected or explicitly changed.

Tools and integrations can send data to other services. Local inference does not describe all application network activity, model downloads, logging, or telemetry. Check the calling application's own settings. Encrypted transport does not mean that every service on the request path is unable to access its content.

## Enable and inspect

On the serving computer:

```bash
actual relay on
actual relay status
actual status
```

Enabled, connected, and ready for inference are separate states. After enabling relay, wait for the reported connection to succeed and confirm the expected model is loaded.

If connection or verification fails, inspect the reported error and [client logs](/docs/logs-and-telemetry). Repeated inference requests will not repair an unavailable serving computer.

## Use the public API

Create an inference credential in [User > Keys](/user/keys). Configure your application with `https://api.actual.inc/v1` when it expects an OpenAI-compatible base URL.

List models, choose a returned model ID, and optionally pin requests with `X-Cluster-ID`. Follow [API Quickstart](/docs/api-quickstart) for working curl examples and [API Reference](/docs/api-reference) for supported routes.

The selected computer or cluster runs the model. Keep credentials private and check the connected application's own storage and privacy settings.

## Use a local endpoint

For an application running on the same computer, inspect:

```bash
actual status --format json
```

Use the URL in `api.url`. Actual prefers port 8080 but may choose another port when that default is occupied. If an application requires an OpenAI-compatible base URL, append `/v1` to the reported URL.

Local loopback access does not use the public relay credential. Do not put a credential into a URL or query parameter.

On macOS builds with the menu app, the API mode is shown as **API · Private Relay** or **API · Localhost**.

## Disable relay

```bash
actual relay off
```

This disables remote relay access while allowing the local API to remain available. Disabling relay is different from explicit offline operation: starting Actual with `--offline` disables relay, Actual telemetry, and LAN clustering. Offline mode is local and standalone. Restore online operation before expecting the public endpoint to reach that computer.

If the public API returns no eligible model or a service-unavailable error, recheck the computer, connection, selected cluster, and loaded model. See [Model Discovery](/docs/model-discovery).