Getting started with managed deployments

This guide deploys the Workflows starter app as a managed deployment: you push the generated project to GitHub, and Mistral Cloud builds and runs the worker for you. No servers to manage, and no API key in the repository — the worker authenticates with a service-account token injected by the platform.

If you are new to Workflows, read Your first workflow first. It explains the concepts this guide builds on.

• A Mistral account on a paid plan. The Free plan cannot run managed deployments — see Quotas.
• Python 3.12 or later, and uv installed (uvx ships with uv).
• A GitHub account, with permission to create a repository in an organization or your personal account.

Run the Workflows CLI to generate a ready-to-run project:

uvx mistralai-workflows-cli@latest setup

uvx mistralai-workflows-cli@latest setup

The command scaffolds a Python project with the Workflows SDK, an example hello-world workflow, and a Dockerfile ready for managed deployments. For a walkthrough of the generated code, see Your first workflow — Scaffold your project.

Check that the worker runs before deploying. From the project directory:

make start-worker

make start-worker

Once the worker registers its workflows, stop it with Ctrl+C. The starter app keeps your API key out of the repository, but double-check before pushing: your local key must stay in an ignored file, never in a committed one.

Managed deployments build from a GitHub repository. Initialize one from the project directory:

cd <your-repo-name>
git init
git add .
git commit -m "Scaffold workflows starter app"

cd <your-repo-name>
git init
git add .
git commit -m "Scaffold workflows starter app"

Create an empty repository on GitHub, then push:

git remote add origin https://github.com/<your-org>/<your-repo-name>.git
git branch -M main
git push -u origin main

git remote add origin https://github.com/<your-org>/<your-repo-name>.git
git branch -M main
git push -u origin main

The repository can be public or private: Mistral Cloud clones it through the Mistral GitHub App, not through public HTTPS.

Managed deployments clone your code through the Mistral GitHub App, and two things must be in place before you deploy:

1. Install the Mistral GitHub App on the repositories you want to deploy. Go to github.com/apps/mistralai, click Configure, select your organization, and choose the repositories.
2. Connect GitHub in the console. Open Studio›GitHub App settings ↗ and add a credential.

If your repository already appears in the deployment creation dialog in the next step, the App is installed and you can skip ahead. For an organization repository you do not administer, ask an organization owner to install the App.

The repository list shown when you create a deployment contains only repositories where the App is installed and that your account can access. If a repository is missing from the list, the App is not installed on it.

Choose a unique deployment name. Two deployments with the same name steal each other's executions.

# /// script
# dependencies = [
#     "mistralai>=3.0",
# ]
# ///
import os

from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

deployment = client.workflows.deployments.create_deployment(
    name="<your-deployment-name>",
    spec={
        "github_url": "https://github.com/<your-org>/<your-repo-name>",
        "revision": "main",
    },
)
print(deployment.name)

# /// script
# dependencies = [
#     "mistralai>=3.0",
# ]
# ///
import os

from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

deployment = client.workflows.deployments.create_deployment(
    name="<your-deployment-name>",
    spec={
        "github_url": "https://github.com/<your-org>/<your-repo-name>",
        "revision": "main",
    },
)
print(deployment.name)

Wait for the deployment to become Active. This means the worker registered its workflows, which are listed on the deployment page. If the build fails, open the deployment details to read the error — most failures are Docker build or startup issues you can reproduce with Test the image locally.

Run the hello-world workflow like any other workflow:

# /// script
# dependencies = [
#     "mistralai>=3.0",
# ]
# ///
import os

from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

execution = client.workflows.execute_workflow(
    workflow_identifier="hello-world",
    input={"name": "World"},
)
print(execution.execution_id)

# /// script
# dependencies = [
#     "mistralai>=3.0",
# ]
# ///
import os

from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

execution = client.workflows.execute_workflow(
    workflow_identifier="hello-world",
    input={"name": "World"},
)
print(execution.execution_id)

The execution lands on your managed worker and returns the greeting from the starter app.

Push your changes to the deployed branch, then redeploy. Mistral Cloud resolves the branch to its latest commit, rebuilds the image, and restarts the worker.

# /// script
# dependencies = [
#     "mistralai>=3.0",
# ]
# ///
import os

from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

deployment = client.workflows.deployments.restart_deployment(
    name="<your-deployment-name>",
)
print(deployment.name)

# /// script
# dependencies = [
#     "mistralai>=3.0",
# ]
# ///
import os

from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

deployment = client.workflows.deployments.restart_deployment(
    name="<your-deployment-name>",
)
print(deployment.name)

• To give the worker credentials for external services, see Secrets.
• To use your own Dockerfile or a worker in a subdirectory, see How it works.
• If something goes wrong, see Troubleshooting.