Quickstart: deploy a workflow to Mistral

In this quickstart, you deploy a project scaffolded by the Mistral CLI as a managed deployment: you push the project to GitHub, and Mistral Cloud builds and runs the worker for you. There are no servers to manage and no API key in the repository: the worker authenticates with a service-account token that the platform injects.

If you are new to Workflows, start with Build your first workflow. It explains the concepts this quickstart builds on.

• A Mistral account with pay-as-you-go enabled, or an Enterprise plan. The Free plan cannot run managed deployments, and paid Pro or Team plans alone don't qualify — pay-as-you-go must be enabled on the organization. See Quotas.
• uv installed.
• A GitHub account, with permission to create a repository in an organization or your personal account.

Follow Your first workflow to install the Mistral CLI, scaffold a project with mistral workflows init, and add the hello-world workflow. The scaffold includes a Dockerfile ready for managed deployments.

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

mistral apps dev

mistral apps dev

Once the worker registers its workflows, stop it with Ctrl+C, then commit the workflow:

git add .
git commit -m "Add hello-world workflow"

git add .
git commit -m "Add hello-world workflow"

Managed deployments build from a GitHub repository. The scaffold already initialized a Git repository in the project directory.

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",
        "backend_spec": {
            "type": "mistral_cloud",
            "dockerfile_path": "deploy/docker/Dockerfile.worker",
        },
    },
)
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",
        "backend_spec": {
            "type": "mistral_cloud",
            "dockerfile_path": "deploy/docker/Dockerfile.worker",
        },
    },
)
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 hello-world workflow.

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.