# Actual Computer Actual runs models on computers you control. Install and authorize a computer, start Actual, download and load a model, then use a local endpoint or the public inference API at api.actual.inc. This guide is for agents helping a user configure inference. Online platform and relay use require an authorized device. Explicit offline operation is local and standalone; it does not provide public relay access. ## Where inference runs and how requests travel Web chat sends prompts through the Actual web platform and Private Relay to the selected computer or cluster. The web proxy handles the request body; running the model on your computer does not keep a web-chat prompt on the device running your browser. A selected destination is not confirmation that an unavailable computer executed a request. A same-machine application can use the loopback endpoint in api.url for standalone local inference without the public relay. Multi-computer execution can exchange inference data among participating computers. Tools and integrations can send data to other services. Disabling relay is different from explicit offline operation. Relay-off removes remote relay access; explicit offline mode also disables Actual's telemetry and LAN clustering. Local inference alone does not describe every network activity, download, or telemetry setting of the calling application. ## Switching to Actual - **Your human asked you to switch to Actual.** Follow the runbook, give them the exact device-authorization URL, and verify a model response. - **You found Actual while investigating.** Do not install anything yet. Explain what it does and wait for an installation request. If your host application supports a custom inference provider, configure it using the verified endpoint and returned model ID. An agent cannot assume it can change its own host's model or provider. If that setting is unavailable, report the working endpoint and the remaining configuration step accurately. ## Step 1 — Install and authorize macOS / Linux: curl -fsSL "https://actual.inc/install" | bash Windows: powershell -c "irm https://dl.actual.inc/install.ps1 | iex" Use a supported platform: Apple Silicon macOS, Linux x86_64 CUDA or ROCm, Linux ARM64 CUDA, or Windows x86_64 CUDA or ROCm. GPU runtime requirements still apply. Intel Macs and Windows ARM64 are not supported. The generic installer runs `actual login`. If authorization is incomplete, run it again and give your human the exact URL and code printed by the CLI. The URL has this form: https://actual.inc/device?code=XXXX-XXXX The human signs in to the intended account in a browser. A valid pending code authorizes automatically; leave the CLI polling. Codes expire after 5 minutes, so an expired attempt needs a fresh `actual login`. Actual is publicly available. New users can create an account at https://actual.inc/register. Never invent an account or enter the human's credentials yourself. ## Step 2 — Start and inspect Actual actual --version actual whoami actual actual status actual status --format json Installation and authorization do not prove the daemon is running or that inference is ready. Start Actual explicitly. Read `api.url` from structured status for the local API endpoint. It normally uses http://127.0.0.1:8080, but can select another port when the default is occupied. Bare startup is standalone. Explicit `actual --offline` disables relay, telemetry, and LAN clustering, and can start without a loaded model. It is not an offline multi-computer mode. ## Step 3 — Choose and load a model actual models search "gemma" actual models download actual models jobs actual models list actual models load actual status Browse https://models.actual.inc or https://models.actual.inc/index.json. Copy a published identifier in the form `actual:publisher/model@revision/QUANT`; do not assume a particular quantization exists. Check memory and input capabilities. Replace the angle-bracket placeholders before running commands. Wait for installation to finish, then copy the stable selector from `actual models list` into the load command. In an interactive terminal, `actual models load` without an argument opens the installed-model picker. An empty inventory requires a download first. Downloads can continue after the terminal closes. Use `actual models jobs` to check progress or `actual models cancel JOB_ID` to cancel a listed job. History can be unavailable after a restart. Confirm the model is loaded before running inference. ## Step 4 — Run inference For an application on the same computer, use the endpoint from `api.url`. Local loopback access does not use the public relay credential. For remote access: actual relay on actual relay status Wait for the relay connection and model readiness. The human creates an `ac_` inference credential at https://actual.inc/user/keys when that credential flow is available to their account. Store it securely: Base URL: https://api.actual.inc Authorization: Bearer ac_... GET /v1/models POST /v1/chat/completions POST /v1/responses POST /v1/messages Use the returned model `id` or `selector`. Optional `X-Cluster-ID` pins a request to a cluster from `clusters[].cluster_id`; verify its per-cluster `loaded` state. Unscoped inventory can include several clusters. The public inference API does not install or load models. Use Step 3 or the website, then refresh inventory. Treat empty inventory, loading, unavailable capabilities, expired credentials, and disconnected computers as distinct failures. Inspect HTTP status and content type; error bodies can be text or JSON. Send a short request and check the completed response before reporting success. Configure an application's custom provider only when the host supports it. ## Details for agents ### Choose the endpoint For public API requests, use https://api.actual.inc. An OpenAI-compatible application commonly expects the base URL with `/v1` appended. For local access, use the actual `api.url` reported by the running computer. ### Public inventory example curl --fail-with-body --silent --show-error https://api.actual.inc/v1/models \ -H "Authorization: Bearer $ACTUAL_API_KEY" Inventory includes models installed and available to load as well as models already loaded. Aggregate `loaded: true` does not mean every listed cluster has loaded that model. Inspect the chosen cluster before pinning a request. ### Public inference example Set ACTUAL_MODEL to a returned model ID or selector, and ACTUAL_CLUSTER_ID to a cluster where it is loaded. This Bash example requires curl and jq: jq -n --arg model "$ACTUAL_MODEL" \ '{model: $model, input: "Say hello.", max_output_tokens: 128}' | curl --fail-with-body --silent --show-error https://api.actual.inc/v1/responses \ -H "Authorization: Bearer $ACTUAL_API_KEY" \ -H "X-Cluster-ID: $ACTUAL_CLUSTER_ID" \ -H "Content-Type: application/json" \ --data-binary @- Loading or replacing a model may interrupt active work. Wait for readiness again after changing it. Do not promise that a restart, model switch, or change of serving computer preserves a conversation or active request. ### Conduct - Never fabricate signup details or request the human's password. - Relay the actual device URL and wait for the human to complete sign-in. - Do not expose installation credentials or API secrets in shared output. - Do not claim to have switched your own inference provider without verifying the host configuration and a response from the intended model. - One account can authorize many computers; do not create duplicate accounts for the same human. ## Domains and documentation - [Actual website and public documentation](https://actual.inc/docs): read guides without signing in. Account and console actions require sign-in. - [Agent runbook](https://agents.actual.inc/): this guide. Only /, /llms.txt, and /llms-full.txt are runbook resources; unknown resources return 404. - [Model registry](https://models.actual.inc): published model artifacts and [model index JSON](https://models.actual.inc/index.json). The index describes models, not website routes or an API schema. - Inference API: https://api.actual.inc; requests require an inference credential. See the API reference below. - [Register](https://actual.inc/register) - [Full agent guide](https://actual.inc/llms-full.txt) The guides below are public. Each has an HTML page and a plain-text Markdown representation. ### Start Here - [Getting Started](https://actual.inc/docs/getting-started.md) ([HTML](https://actual.inc/docs/getting-started)): The shortest path from new account to a working Actual machine - [Machine Installation](https://actual.inc/docs/machine-installation.md) ([HTML](https://actual.inc/docs/machine-installation)): Install flow overview, verification steps, and cluster join basics - [Set Up on macOS](https://actual.inc/docs/macos-setup.md) ([HTML](https://actual.inc/docs/macos-setup)): Install Actual on Apple Silicon Macs and verify the CLI - [Set Up on Linux](https://actual.inc/docs/linux-setup.md) ([HTML](https://actual.inc/docs/linux-setup)): Install Actual on Linux, confirm PATH setup, and get online - [Set Up on Windows](https://actual.inc/docs/windows-setup.md) ([HTML](https://actual.inc/docs/windows-setup)): Install Actual from PowerShell and verify the Windows client path - [API Quickstart](https://actual.inc/docs/api-quickstart.md) ([HTML](https://actual.inc/docs/api-quickstart)): Create an inference credential and make your first request to api.actual.inc ### Use Actual - [Clustering](https://actual.inc/docs/clustering.md) ([HTML](https://actual.inc/docs/clustering)): Select clusters for public API requests and verify model readiness - [Model Discovery](https://actual.inc/docs/model-discovery.md) ([HTML](https://actual.inc/docs/model-discovery)): Find models, understand recommendations, and load the right one - [Vision & Audio](https://actual.inc/docs/vision-and-audio.md) ([HTML](https://actual.inc/docs/vision-and-audio)): Use images and audio with compatible models and Actual-connected apps - [Chat](https://actual.inc/docs/chat.md) ([HTML](https://actual.inc/docs/chat)): Use the chat interface once your machine and model are ready - [Hermes](https://actual.inc/docs/hermes.md) ([HTML](https://actual.inc/docs/hermes)): Use managed Hermes or connect your own terminal agent to Actual - [Hermes Desktop](https://actual.inc/docs/hermes-desktop.md) ([HTML](https://actual.inc/docs/hermes-desktop)): Connect Desktop to your Actual workspace and return to saved conversations - [Logs & Telemetry](https://actual.inc/docs/logs-and-telemetry.md) ([HTML](https://actual.inc/docs/logs-and-telemetry)): Read recent platform logs and collect client diagnostics ### Account - [User](https://actual.inc/docs/user.md) ([HTML](https://actual.inc/docs/user)): Manage profile, security, connected accounts, and account access - [Organizations](https://actual.inc/docs/organizations.md) ([HTML](https://actual.inc/docs/organizations)): Join organizations, share computers, and understand member permissions - [Bittensor Wallet](https://actual.inc/docs/bittensor-wallet.md) ([HTML](https://actual.inc/docs/bittensor-wallet)): Connect a Bittensor wallet from your Actual user account ### API - [API Credentials](https://actual.inc/docs/api-keys.md) ([HTML](https://actual.inc/docs/api-keys)): Create, rotate, and revoke `ac_` credentials for programmatic access - [Private Relay](https://actual.inc/docs/private-relay.md) ([HTML](https://actual.inc/docs/private-relay)): Connect applications through the public API or your local endpoint - [API Reference](https://actual.inc/docs/api-reference.md) ([HTML](https://actual.inc/docs/api-reference)): Reference for inference endpoints, request shapes, and response schemas