---
title: Install Venom Cloud on a Mac
description: Run Venom Cloud on your own Mac from the command line, at http://localhost:8080, in Docker Desktop, OrbStack or Colima, with no root, started again at each login by a LaunchAgent.
section: deploy
order: 47
audience: [operator, user]
sources: [scripts/release/public/install-cloud.sh, scripts/release/cloud-pkg.sh, scripts/release/macos-cloud-pkg, scripts/test-cloud-pkg.sh, scripts/test-install-cloud.sh, docs/public/deploy/install-server.md, docs/adr/0074-selfhost-updates.md]
features: []
---

The [server installer](/docs/deploy/install-server) also runs on a Mac. There it sets up Venom Cloud for this computer only: the console is at `http://localhost:8080`, nothing listens on another network interface, and there is no certificate. Use it to try Venom Cloud, or to run it for yourself. For a public host name with HTTPS, install it on a Linux server.

## One click: the installer or the app {#one-click}

Each release has Venom Cloud for the Mac as an installer and as an app, both from the [releases page](https://github.com/elishahbiz/venom-releases/releases):

- `Venom-Cloud-<v>-macos.pkg`: open it and click through Installer. It puts **Venom Cloud.app** in Applications.
- `Venom-Cloud-<v>-macos.zip` (and `.dmg`, when the release has one): unzip it, or open the disk image, and drag **Venom Cloud** to Applications. It is the same app, so the result is the same.

The packages are not notarized unless the release was built with Developer ID certificates, so macOS may say it cannot check the app. For the `.pkg`, right-click it and choose Open, then Open again; for the app, right-click it in Applications and choose Open once. Or use System Settings, Privacy & Security, Open Anyway.

You need a container runtime that is already running (see below). The first time you open **Venom Cloud**:

1. With none running, a window says Venom Cloud needs Docker Desktop, OrbStack or Colima running, and the app quits. It installs and downloads nothing. Start one and open the app again.
2. With one running, a notification says setup has started. The app runs `install-cloud.sh --local --yes --no-docker-install --auto-update no --models later --version <v>` as you, not as root, with the release's own copy of the installer, so the install is in `~/.venom/cloud` as described below. The first start pulls Venom Cloud's images, which takes several minutes; that pull is the only download, the same one the command-line installer makes. Automatic updates are off and models are for later; you can change both in the console.
3. When it is done, your browser opens `http://localhost:8080/setup` and a window shows the one-time setup code. Enter it on the setup page. If setup fails, a window names the log, `~/Library/Logs/Venom-Cloud-setup.log`.

Opened again, the app starts the stack if it is down and opens the dashboard on its port. The same LaunchAgent as in the command-line install starts it at login.

The `.pkg` does one more thing: after it installs, if a container runtime is already running, it opens the app for the logged-in user, so the setup above starts at once, in the background. Installer does not wait for it. With no runtime running, or nobody logged in, it does nothing and the setup waits for your first open of the app. The package never fails because Docker is missing.

To uninstall, run `venom-cloud uninstall --keep-data` (see [Uninstall](#uninstall)), then drag **Venom Cloud** from Applications to the Trash. There is no uninstaller package.

## What you need

- macOS on Apple silicon or Intel, with at least 2 CPU cores, 2 GB of memory and 10 GB of free disk.
- A container runtime that is already running: [Docker Desktop](https://docs.docker.com/desktop/setup/install/mac-install/), [OrbStack](https://orbstack.dev) or [Colima](https://github.com/abiosoft/colima) (with `docker` and `docker-compose` from Homebrew). The installer never installs one. If `docker info` or `docker compose version` fails, it stops and names these three.
- The runtime needs about 2 GB of memory for the stack. Colima starts with 2 GB; `colima start --memory 4` gives it more. The installer warns when the runtime has less than 1800 MB.

## Install

Run it as your own user, not with `sudo`:

```bash
curl -fsSL https://raw.githubusercontent.com/elishahbiz/venom-releases/main/install-cloud.sh | sh
```

It asks for the admin email, the size profile, where models come from and whether to turn on automatic updates, the same questions as on a server, but not for a domain. At the end it prints `http://localhost:8080/setup` and the one-time setup code. Open that page in a browser on the same Mac.

For an unattended install (a script, or what the app above runs as you):

```bash
sh install-cloud.sh --local --yes --no-docker-install --auto-update no --models later
```

| Flag | Default on a Mac | What |
|---|---|---|
| `--local` | on | Only this computer: `http://localhost:PORT`, plain HTTP, the port published on `127.0.0.1` only. On Linux it is available by flag. |
| `--port N` | 8080 | The port, with `--local`. Pick another when 8080 is taken. |
| `--dir DIR` | `~/.venom/cloud` | Where the install lives. Keep it in your home folder: the container runtimes share it with their containers by default. |
| `--no-docker-install` | always | Never offer to install Docker. On Linux it stops the offer of Docker's own script; on a Mac nothing is ever offered. |

`--domain` and `--database-host` are refused on a Mac with a pointer to `--local`. A rerun keeps the secrets, the port and every earlier answer.

The macOS `openssl` (LibreSSL) cannot generate the Ed25519 signing keys. The installer then generates them with the `openssl` inside the Postgres image it pulls anyway, in the same format, and stops with an error if no key comes out. No other download is made.

## Where the files are

| Path | What |
|---|---|
| `~/.venom/cloud/.env` | The secrets and settings (mode 600). Back it up: `VENOM_VAULT_KEYS` opens what the vault sealed. |
| `~/.venom/cloud/docker-compose.yml`, `Caddyfile` | The stack. Caddy serves `http://localhost:8080` and publishes `127.0.0.1:8080` only. |
| `~/.venom/cloud/bin/venom-cloud` | The [`venom-cloud` command](/docs/deploy/install-server#the-venom-cloud-command). It is linked in `/usr/local/bin` when you can write there, else in `~/.local/bin` (the installer says when that is not on your `PATH`). |
| `~/.venom/cloud/backups/` | Backups, when they are on. |
| `~/.venom/cloud/logs/` | `tick.log` and `backup.log`, written by the LaunchAgents. |
| `~/Library/LaunchAgents/dev.usevenom.cloud.tick.plist` | Runs the tick (below). |

The database lives in a Docker volume of your container runtime, not in the install folder.

## Only this computer

The stack publishes one port, on `127.0.0.1`. Other machines on your network cannot open it. The console's address is `http://localhost:8080`; open it by that name, not as `http://127.0.0.1:8080`: Caddy answers only that name, and the console checks that changes come from the address in `VENOM_CLOUD_ORIGIN`. Over plain HTTP the console's cookies are not marked `Secure`; on an `https://` address they are.

Some features need Venom Cloud to be reachable from other machines: webhooks from other services, daemons on other computers, and calendar or form links you send to other people. For those, install on a Linux server with a domain.

## Your own database

The bundled Postgres container is the default. To use a Postgres server you already run, use the production profile with its URL in the environment:

```bash
VENOM_DATABASE_URL="postgres://venom:PASSWORD@db.example.net:5432/venom_cloud" sh install-cloud.sh --local --profile production --yes
```

The installer checks that the database answers and has pgvector, from a throwaway container. For a Postgres running on this Mac, use `host.docker.internal` as the host name: `localhost` inside a container is the container itself, and the installer refuses it. The production profile also turns on a daily backup at 03:27; see [Production](/docs/deploy/install-server#production-your-own-database-server-and-daily-backups).

## How it starts at login

There is no cron on a Mac, so the installer writes a per-user LaunchAgent, `dev.usevenom.cloud.tick`. launchd runs `venom-cloud tick --up` when you log in and every five minutes after:

- `--up` first checks whether Docker is running. If it is not (Docker Desktop is still starting after a login), it does nothing until the next run.
- When Docker runs and no container of the stack does, it starts the stack. A stack that is partly running, for example during a restore, is left alone.
- Then the tick does what it does on a server: it reports to the console, carries out an upgrade, rollback, backup or export an admin asked for, and runs automatic updates and scheduled backups when they are due. See [Update a self-hosted Venom Cloud](/docs/deploy/updates).

So after a restart, the console comes back once your container runtime is running. Turn on the runtime's own "start at login" setting to make that automatic. A Mac that is asleep or shut down runs no tick: an update window or a backup hour it sleeps through waits for the next one. With daily backups on, a second LaunchAgent, `dev.usevenom.cloud.backup`, runs the backup at 03:27, or at the next wake if the Mac was asleep.

launchd starts jobs with a short `PATH`, so the plist sets one that includes the folder `docker` was found in at install time, `/usr/local/bin`, `/opt/homebrew/bin`, `~/.orbstack/bin`, `~/.docker/bin` and `~/.rd/bin`. `DOCKER_HOST` and `DOCKER_CONTEXT`, when set at install time, are copied into it too.

There is one LaunchAgent per user, so one local install per macOS user account.

## Uninstall

```bash
venom-cloud uninstall --keep-data
```

It removes the LaunchAgents first (so the next tick does not start the stack again), stops the stack, and removes the `venom-cloud` link. `--keep-data` keeps the database volume; without it, `--yes` deletes it. `~/.venom/cloud` stays with your `.env` and backups: delete the folder yourself when you no longer need them.

## How it is tested

`scripts/test-cloud-pkg.sh` builds the `.pkg`, `.zip` and `.dmg` from a fake release and checks the payload, the bundle identifier, the `Info.plist` and that the app holds the release's `install-cloud.sh`. It runs the app's launcher under a temporary home folder with stand-ins for Docker, `osascript`, `open` and `curl`: no runtime (a dialog, nothing installed), a runtime and no install (the installer with exactly the flags above), and an existing install (`tick --up`, then the browser). It never installs the package.

`scripts/test-install-cloud.sh` runs the installer as if on a Mac, with stand-ins for `uname`, `sysctl`, `lsof`, `launchctl`, an `openssl` without Ed25519, Docker and the release server, under a temporary home folder. It checks the local files (the Caddyfile, the published port, the origin in `.env`), the key format, the LaunchAgent plist (with `plutil -lint` on macOS), that no Docker install is offered, that a missing key stops the install, `tick --up`, an upgrade, uninstall, and your own database.
