Install Venom Cloud on a Mac
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.
The server installer 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
Each release has Venom Cloud for the Mac as an installer and as an app, both from the releases page:
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:
- 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.
- 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/cloudas 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. - When it is done, your browser opens
http://localhost:8080/setupand 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), 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, OrbStack or Colima (with
dockeranddocker-composefrom Homebrew). The installer never installs one. Ifdocker infoordocker compose versionfails, 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 4gives it more. The installer warns when the runtime has less than 1800 MB.
Install
Run it as your own user, not with sudo:
curl -fsSL https://raw.githubusercontent.com/elishahbiz/venom-releases/main/install-cloud.sh | shIt 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):
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. 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:
VENOM_DATABASE_URL="postgres://venom:PASSWORD@db.example.net:5432/venom_cloud" sh install-cloud.sh --local --profile production --yesThe 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.
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:
--upfirst 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.
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
venom-cloud uninstall --keep-dataIt 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.