API
Private Relay
Connect applications through the public API or your local endpoint
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:
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. Repeated inference requests will not repair an unavailable serving computer.
Use the public API#
Create an inference credential in 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 for working curl examples and 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:
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#
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.