amalgm

Install the local Amalgm computer runtime:

npm i -g amalgm
amalgm login
amalgm doctor
amalgm start

To move an existing install to the newest stable published build, run amalgm update. Set AMALGM_AUTO_UPDATE=1 when running amalgm start to let the CLI update itself to the latest stable release before launching.

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

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:

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:

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

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:

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.