Machine Installation

Install flow overview, verification steps, and cluster join basics

Install Actual on the computer that will run the model. The website generates a short-lived command for installation and authorization; startup and model readiness are separate checks.

Install from Computers

  1. Sign in and open Computers.
  2. Choose Add lead computer for a new lead. To add a child, select the intended cluster and choose Add child computer. Management controls require access to manage that computer.
  3. Copy the macOS / Linux or Windows command shown by the form.
  4. Run the exact command on the target computer within 10 minutes. It includes a sensitive, short-lived installation credential.
  5. Wait for download and authorization to finish. Open a fresh terminal to pick up PATH changes.

Copy the current command instead of substituting an old code or assuming a release-channel selector is available. Build and channel availability can differ by account. See the macOS, Linux, or Windows guide.

Adding a child associates it with the chosen cluster in the platform. See Clustering to target and verify that cluster through the public API; a shared name alone does not establish distributed execution.

Install many computers

To enroll a fleet without generating a command per computer, create a reusable Machine install (fleet) key in User > Keys and run its install command, or actual login <key>, on each computer. See Machine install keys for fleets. The option is rolling out gradually and may not appear for your account yet.

Authorize or re-authorize

Run actual login if the installer did not finish authorization. The CLI prints an eight-character code, formatted XXXX-XXXX, and a URL such as https://actual.inc/device?code=XXXX-XXXX.

Open the exact URL in your browser and sign in to the intended account. With a valid pending code, the page authorizes automatically. Keep the CLI running while it polls. Device codes expire after 5 minutes; run actual login again for a new code if one expires. This is separate from the 10-minute installation credential.

Use actual whoami to inspect the signed-in identity. If the computer appears under the wrong account, resolve that login before proceeding.

Start and verify

Run these commands after installation:

actual --version
actual whoami
actual
actual status
actual status --format json

Bare actual ensures the daemon is running in the background and returns to the shell. It may start with no model loaded. actual status reports the model, relay state, endpoint, log file, version, and update channel; inspect the reported values rather than looking for a literal health: ok line.

Confirm that the computer appears online in Computers. Then download and load a model. Installation and login alone do not make inference ready.

Daily commands

CommandUse
actualStart the daemon if needed and inspect its state.
actual status --format jsonInspect structured state; api.url is the actual local API endpoint.
actual stopStop the daemon, interrupting active work.
actual restartRestart the daemon, interrupting active work.
actual models search "query"Find downloadable models.
actual models jobsInspect download jobs owned by the current daemon.
actual models listList installed models and their stable selectors.
actual models loadChoose an installed model interactively.
actual models unloadUnload the current model.
actual logs --tail 100 --onceRead recent client logs and exit.
actual relay statusInspect relay settings and connection state.
actual clusters --format jsonInspect clusters through the authenticated CLI.

For scripts, pass the stable selector from actual models list to actual models load. Use actual models cancel JOB_ID to cancel a download, replacing JOB_ID with the ID from actual models jobs. Closing the terminal does not cancel a background download; job history can be unavailable after a restart.

Startup options

OptionMeaning
--model MODELStart with the selected installed model.
--port PORTBind the local API to an explicit port; fail if it is unavailable.
--aloneCompatibility flag for standalone mode, which is already the default.
--offlineDisable relay, telemetry, and LAN clustering. Can start without a model.
--log-level LEVELSet log verbosity: off, error, warn, info, debug, or trace.
--log-file PATHSet the log destination for a daemon being started.
--no-prevent-sleepAllow the host to sleep while serving.
--ctx-size TOKENSOverride the context size instead of sizing it from device memory.
--attach URLAttach to an OpenAI-compatible engine you manage yourself. Requires --model; the engine keeps control of loading and tuning. Set ACTUAL_ATTACH_API_KEY if the engine requires a bearer token.

The local API prefers port 8080 but can choose another port when the default is occupied. Read api.url from actual status --format json. Startup flags do not reconfigure a daemon that is already running; deliberately restart it when changing startup settings.

Recover from a failed first run

  • If the install command expired, copy a fresh command from Computers.
  • If the CLI is missing, open a new shell and inspect the command path using the platform guide.
  • If login is incomplete, run actual login and complete the new device URL.
  • If the daemon is stopped, run actual.
  • If no model is installed, download one before opening the load picker.
  • If a model fails to load, inspect memory availability and Logs & Telemetry.
  • If shared-computer controls are absent, check the owner and organization permissions.