# amalgm

Install the local Amalgm computer runtime:

```sh
npm i -g amalgm
amalgm login
amalgm doctor
amalgm start
```

To move an existing install to the newest stable published build immediately, run `amalgm update`.
`amalgm start` checks for updates before launch by default; set `AMALGM_AUTO_UPDATE=0` or `AMALGM_DISABLE_AUTO_UPDATE=1` to opt out.

`amalgm login` opens a browser approval page, then registers the machine and stores its local tunnel/computer record in `~/.amalgm/computer.json`.

After login, register local ground with the cloud-backed entity rail:

```sh
amalgm register path/to/file path/to/folder
```

`amalgm register` watches the selected local ground and saves its entity
records and file contents to the signed-in user's private Amalgm cloud
resource. Use `amalgm add <entity-uuid> [directory]` on another machine to
bring an existing cloud-backed workspace or file tree onto that machine. It
uses one verified current cloud snapshot, downloads its immutable file bytes,
preserves the UUIDs, and starts a local watcher. It does not replay old cloud
mutations to rebuild the tree.

If you start from the Amalgm web app or are setting up a remote/headless machine, create a setup code from the web app and run:

```sh
amalgm login --setup-code ABCD-EFGH-JKLM-NPQR
```

`amalgm doctor` checks the installed runtime, login record, service supervisor, required local ports, daemon state, and whether an HMAC proxy token is available.

`amalgm run` is the foreground runtime supervisor. It reads the declared service manifest, starts each local service, health-checks them, and restarts unhealthy children with backoff. In a container you control, make this the container command/entrypoint, ideally behind a tiny init such as Docker `--init`, `tini`, or the provider's init wrapper:

```sh
amalgm run
```

`amalgm start` is the host attachment helper. It installs/starts the best available launcher for the machine, then that launcher runs `amalgm run`:

- macOS host: LaunchAgent
- Linux host with real user systemd: systemd user service
- random/container shell where no service manager is available: portable best-effort watchdog

Running service-managed runtimes also check for updates in the background. Normal updates restart only when chat/tunnel work is idle; critical updates can restart immediately. If the runtime is not service-managed, background updates are installed but the running process stays on the old code until it is manually restarted.

The runtime supervisor keeps the declared local essentials alive:

- port monitor on `8081`
- Amalgm MCP on `8083`
- chat server on `8084`
- events/previews/artifact tunnel to `wire.events.amalgm.ai`
- chat tunnel to `amalgm-chat-gateway`

The npm supervisor binds local services to `127.0.0.1` by default and connects them outward through the registered Amalgm tunnels. For development without cloud registration, use `amalgm start --local-only`. For direct foreground debugging, use `amalgm run` or `amalgm start --foreground`.

Useful commands:

```sh
amalgm status
amalgm update
amalgm logs
amalgm logs chat-server
amalgm service status
amalgm stop
amalgm logout
```

The runtime in `runtime/` is generated from `amalgm-engine/runtime` during `prepack`, so Electron and the published npm package use the same machine-runtime tree. Local services require an unguessable runtime token for non-health endpoints, and proxy tokens are refreshed through the registered computer credential.