Start Here
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#
- Sign in and open Computers.
- 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.
- Copy the macOS / Linux or Windows command shown by the form.
- Run the exact command on the target computer within 10 minutes. It includes a sensitive, short-lived installation credential.
- 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.
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#
| Command | Use |
|---|---|
actual | Start the daemon if needed and inspect its state. |
actual status --format json | Inspect structured state; api.url is the actual local API endpoint. |
actual stop | Stop the daemon, interrupting active work. |
actual restart | Restart the daemon, interrupting active work. |
actual models search "query" | Find downloadable models. |
actual models jobs | Inspect download jobs owned by the current daemon. |
actual models list | List installed models and their stable selectors. |
actual models load | Choose an installed model interactively. |
actual models unload | Unload the current model. |
actual logs --tail 100 --once | Read recent client logs and exit. |
actual relay status | Inspect relay settings and connection state. |
actual clusters --format json | Inspect 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#
| Option | Meaning |
|---|---|
--model MODEL | Start with the selected installed model. |
--port PORT | Bind the local API to an explicit port; fail if it is unavailable. |
--alone | Compatibility flag for standalone mode, which is already the default. |
--offline | Disable relay, telemetry, and LAN clustering. Can start without a model. |
--log-level LEVEL | Set log verbosity: off, error, warn, info, debug, or trace. |
--log-file PATH | Set the log destination for a daemon being started. |
--no-prevent-sleep | Allow the host to sleep while serving. |
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 loginand 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.