Automation

Script it once, run it everywhere

Q: Should I use the deploy URL, the CLI or the API?

The deploy URL is simplest: one `curl -X POST`, no token, but your pipeline does not learn whether the deploy succeeded. The CLI with `--watch` waits and fails the job on a failed deploy. The API gives you the same in your own scripts.

Start deploys from your pipeline and fail the build when they fail. Run the same bash script on every server with one click, and tell your own systems about every deploy.

Start deploying Read the documentation

Four ways to start a deploy without clicking

Push to deploy
Link a GitHub, GitLab or Bitbucket repository and a webhook is added for you. Pushes to the site's branch deploy; other branches are ignored.
Deploy URL
One POST to a secret URL, no token needed. It answers 202, 409 when a deploy runs, or 422. Regenerate it any time.
Deploy CLI
deploy deploy shop.example.com --watch starts the deploy, streams its output and exits with its result.
REST API
POST a deployment, then follow its task until it succeeds or fails. JSON in, JSON out, 120 requests a minute per token.

CLI

Deploy from GitHub Actions in one step

The CLI is a single PHP file without dependencies, downloaded from your Vimonto Deploy address at /cli/deploy. GitHub's Ubuntu runners already have PHP, so there is nothing to install.

Create a token with only the Deploy scope and store it as a secret. With --watch, a failed deploy turns the pipeline red. The same command works in GitLab CI.

.github/workflows/deploy.yml

name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy shop.example.com
        run: php bin/deploy deploy shop.example.com --watch
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
          DEPLOY_URL: https://deploy.example.com
          DEPLOY_ORG: acme

REST API

An API for your own scripts

Personal API tokens act as you: they can do what your role allows, on the servers your teams give you, within the scopes you choose. Read views, Deploy starts and follows deploys for CI, and Write also creates and removes databases and runs backups and recipes. Tokens expire after 30, 90 or 365 days, or never, and only a hash is stored.

Long work runs as a task you can poll with GET /tasks/<id> for its status, step, progress and output. Errors are JSON with a message, and 409 responses carry the running task's ID.

List servers, sites and deployments; find a site by its domain
Start deploys and follow their tasks
Create and delete databases
List backups and run one now
List recipes and run one on several servers

API reference

MCP

Let your AI assistant deploy

Vimonto Deploy has a built-in MCP server, so assistants such as Claude Code, Claude Desktop, Cursor and VS Code can list your servers and sites, deploy a site and follow the deploy, read a failed task's output, create databases and run backups and recipes.

It signs in with a personal API token: the assistant can do exactly what the token's scopes and your role allow, on the servers you have access to. Nothing can be deleted through it.

Connect an assistant

Recipes

Saved bash scripts for every server

A recipe is a bash script you write once and run on one or more active servers, as root or the server user. Each server gets its own task, so you follow every output separately, and you can get one email report when all are done.

Variables such as {{server_name}}, {{ip_address}}, {{private_ip_address}} and {{server_type}} are filled in per server just before the script runs.

Recipe: clean up disk space

set -e
echo "Cleaning up on {{server_name}} ({{ip_address}})"
apt-get autoremove -y
journalctl --vacuum-time=14d
df -h /

Deploy hooks

Tell your own systems about every deploy

Switch on a site's Deploy hook and Vimonto Deploy sends a POST with JSON to your HTTPS endpoint after every deploy, successful or failed, without holding the deploy up. Use it for a chat bot, a changelog or an automation tool, and send Test deploy hook to check it.

Need email instead? Add up to 10 addresses, also outside the organization, that get an email whenever a deploy of the site fails.

Deploy hook payload (shortened)

{
    "event": "deployment.succeeded",
    "site": { "id": 12, "domain": "shop.example.com" },
    "server": { "id": 3, "name": "web-1" },
    "deployment": {
        "status": "succeeded",
        "branch": "main",
        "commit_message": "Fix the checkout total"
    }
}

Questions about automation

Should I use the deploy URL, the CLI or the API?

The deploy URL is simplest: one curl -X POST, no token, but your pipeline does not learn whether the deploy succeeded. The CLI with --watch waits and fails the job on a failed deploy. The API gives you the same in your own scripts.

Can I create servers or sites through the API?

Not yet. The API reads servers, sites, deployments, databases, backups, recipes and tasks; starts deploys; creates and removes databases; and runs backups and recipes.

What does the CLI need?

PHP 8.2 or newer with the curl extension, and an API token. It runs on macOS, Linux and WSL, and needs no SSH access to your servers: it only talks to the API over HTTPS.

Why does my pipeline get a 409?

A deploy of the site was already running, often because push to deploy started one. Turn off Deploy on every push for sites that CI deploys.

Who can run recipes?

Owners, administrators, managers and developers. Members limited to their teams can only run recipes on their own servers. See security and teams.

Your next deploy could be live before your coffee is.

Create an organization, connect a server and push. That is all.

Start deploying Read the docs