# Machine Installation

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](/console/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](/docs/macos-setup), [Linux](/docs/linux-setup), or [Windows](/docs/windows-setup) guide.

Adding a child associates it with the chosen cluster in the platform. See [Clustering](/docs/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:

```bash
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](/console/computers). Then [download and load a model](/docs/model-discovery). 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 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](/docs/logs-and-telemetry).
- If shared-computer controls are absent, check the owner and [organization permissions](/docs/organizations).