> Agent-readable docs index: /docs/llms.txt. Full docs in one file: /docs/llms-full.txt. Download /docs/docs.zip to grep all markdown files locally.

---
title: Libretto Cloud Hosting
sidebarTitle: Overview
"og:image": "https://libretto.sh/docs/og/libretto-cloud-hosting/overview.png"
---

> The hosted platform for Libretto. Deploy workflows, run them through a managed API, schedule workflow runs, and investigate failures.

Libretto Cloud is the easiest way to host and run workflows. Sign up, run one deploy command from the CLI, and your workflow is live behind a managed API. If you'd rather use a different browser or infrastructure provider, see [alternative providers](/alternative-providers/overview). The Libretto Cloud API URL is `https://api.libretto.sh`.

### Why use Libretto Cloud

Use Libretto Cloud when you want to ship and run workflows without owning the runtime infrastructure yourself.

* Libretto Cloud runs the browser layer for you, so you do not have to manage proxies, browser sessions, or CAPTCHA handling yourself. For location-sensitive workflows, you can still choose the hosted browser's residential proxy location.
* By default, when a run fails, Libretto Cloud automatically analyzes the failure and emails you a summary, along with the recordings, screenshots, logs, and other debug context you need to understand what broke.
* Deployments can also enable auto-repair, which routes failed jobs to the autofix agent instead of only sending debug context.
* You can build, debug, and deploy workflow packages from the same CLI instead of stitching together separate tools for local development, browsers, and hosting.

### Set up Libretto Cloud

<Steps>
  <Step title="Create a user account and organization">
    Create a new Libretto Cloud account with:

    ```bash theme={null}
    npx libretto cloud auth signup
    ```

    If you are joining an existing organization, open the invitation link from your email instead.

    See [Create a new user account and organization](/libretto-cloud-hosting/authentication#create-a-new-user-account-and-organization).
  </Step>

  <Step title="Create an API key">
    Issue an API key for your project or environment:

    ```bash theme={null}
    npx libretto cloud auth api-key issue --label laptop-dev
    ```

    Store the printed key as `LIBRETTO_API_KEY` in your `.env` file:

    ```dotenv theme={null}
    # .env
    LIBRETTO_API_KEY=<issued-key>
    ```

    See [Issue an API key](/libretto-cloud-hosting/authentication#issue-an-api-key).
  </Step>

  <Step title="Set up a webhook">
    If you want your system to receive results and failure responses from your browser automations, create a webhook endpoint so Libretto Cloud can send `job.completed` and `job.failed` events back to you:

    ```bash theme={null}
    curl -X POST "https://api.libretto.sh/v1/webhooks/create" \
      -H "x-api-key: $LIBRETTO_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "json": {
          "url": "https://example.com/libretto/webhooks",
          "signing_secret": "replace-with-your-secret",
          "description": "production job webhooks",
          "active": true
        }
      }'
    ```

    Stored tenant webhooks are best for long-lived destinations. Per-job or per-schedule callbacks are better for one-off or dev endpoints.

    See [Create a stored webhook endpoint](/libretto-cloud-api/webhooks#create-a-stored-webhook-endpoint).
  </Step>

  <Step title="Deploy a workflow">
    Change into the workflow package directory before deploying. The directory you pass to `deploy` is the package directory that gets bundled and uploaded, and it must contain `package.json`:

    ```text
    my-automations/
    ├── package.json
    ├── index.ts
    └── src/
        └── workflows/
            └── check-eligibility.ts
    ```

    Then run deploy from that directory:

    ```bash theme={null}
    cd my-automations
    npx libretto cloud deploy .
    ```

    See [Expected deploy directory](/libretto-cloud-hosting/deployments#expected-deploy-directory) and [Deploy workflows](/libretto-cloud-hosting/deployments#deploy-workflows).
  </Step>

  <Step title="Run the workflow">
    After deploy, call the Libretto Cloud jobs API with the workflow name declared in your code:

    ```bash theme={null}
    curl -X POST "https://api.libretto.sh/v1/jobs/create" \
      -H "x-api-key: $LIBRETTO_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "json": {
          "workflow": "check-eligibility",
          "params": {
            "memberId": "12345"
          },
          "timeout_seconds": 300
        }
      }'
    ```

    Then fetch the result with the returned job id:

    ```bash theme={null}
    curl -X POST "https://api.libretto.sh/v1/jobs/get" \
      -H "x-api-key: $LIBRETTO_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "json": {
          "id": "<job-id>"
        }
      }'
    ```

    See [Run a deployed workflow](/libretto-cloud-hosting/deployments#run-a-deployed-workflow) and [Jobs](/libretto-cloud-api/jobs-and-logs#jobs).
  </Step>
</Steps>

### Libretto Cloud CLI

<CardGroup cols={3}>
  <Card title="Authentication" icon="key" href="/libretto-cloud-hosting/authentication">
    Sign in, invite teammates, and issue API keys.
  </Card>

  <Card title="Deployments" icon="rocket" href="/libretto-cloud-hosting/deployments">
    Deploy workflow bundles to Libretto Cloud.
  </Card>

  <Card title="Observability and Debugging" icon="bug" href="/libretto-cloud-hosting/observability-and-debugging">
    Debug workflow failures and investigate hosted workflow runs.
  </Card>

  <Card title="Billing" icon="credit-card" href="/libretto-cloud-hosting/billing">
    Check plan status and manage payment details.
  </Card>
</CardGroup>

### Libretto Cloud API

* [Overview](/libretto-cloud-api/overview)
* [Sessions](/libretto-cloud-api/sessions)
* [Deployments and Workflows](/libretto-cloud-api/deployments-and-workflows)
* [Jobs and Logs](/libretto-cloud-api/jobs-and-logs)
* [Credentials](/libretto-cloud-api/credentials)
* [Webhooks](/libretto-cloud-api/webhooks)
* [Schedules](/libretto-cloud-api/schedules)