Skip to main content

Documentation Index

Fetch the complete documentation index at: https://libretto.sh/docs/llms.txt

Use this file to discover all available pages before exploring further.

The hosted platform for Libretto. Deploy workflows, run them through a managed API, schedule workflow runs, and investigate failures.
Libretto Cloud is in beta and under active development. APIs and behavior may change as the managed platform evolves.
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 run workflows on infrastructure you control, see the self-hosting 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.
  • 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.
  • 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

1

Create a user account and organization

Create a new Libretto Cloud account with:
npx libretto experimental auth signup
If you are joining an existing organization, use accept-invite instead.See Create a new user account and organization.
2

Create an API key

Issue an API key for your project or environment:
npx libretto experimental auth api-key issue --label laptop-dev
Store the printed key as LIBRETTO_API_KEY in your .env file:
# .env
LIBRETTO_API_KEY=<issued-key>
See Issue an API key.
3

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:
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.
4

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:
my-automations/
├── package.json
├── index.ts
└── src/
    └── workflows/
        └── check-eligibility.ts
Then run deploy from that directory:
cd my-automations
npx libretto experimental deploy .
See Expected deploy directory and Deploy workflows.
5

Run the workflow

After deploy, call the Libretto Cloud jobs API with the workflow name declared in your code:
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:
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 and Jobs.

​
Libretto Cloud CLI

Authentication

Sign in, invite teammates, and issue API keys.

Deployments

Deploy workflow bundles and investigate hosted failures.

Billing

Check plan status and manage payment details.

​
Libretto Cloud API