> 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: Deployments "og:image": "https://libretto.sh/docs/og/libretto-cloud-hosting/deployments.png" --- > Deploy workflow bundles to Libretto Cloud, then use the failure emails and debug tools when runs break. ### Before you deploy Libretto Cloud commands and API requests use `https://api.libretto.sh`. Issue an API key, then add it to your project `.env` file: ```dotenv theme={null} LIBRETTO_API_KEY= ``` ### Expected deploy directory `cloud deploy` uploads one package directory at a time. That directory must contain: * A `package.json` * An entry file for workflow discovery * The workflow files you want to deploy By default, Libretto looks for `index.ts` inside the directory you pass to `deploy`. Recommended layout: ```text my-automations/ ├── package.json ├── index.ts └── src/ └── workflows/ ├── check-eligibility.ts └── submit-prior-auth.ts ``` Each workflow file should default-export a `workflow(...)`. Then `index.ts` should export the workflows you want Libretto Cloud to discover: ```ts theme={null} export { default as checkEligibility } from "./src/workflows/check-eligibility"; export { default as submitPriorAuth } from "./src/workflows/submit-prior-auth"; ``` The API uses the workflow name from the `workflow("...")` call inside the file, not the filename or the export alias from `index.ts`. If your workflows live in a package inside a monorepo, run `cloud deploy` against that package directory instead of the monorepo root. The deploy command has two separate path concepts: * The positional argument is the package directory to bundle and upload. That directory must contain `package.json`. * `--entry-point` is the file inside that package directory that Libretto should use for workflow discovery. For example: ```bash theme={null} npx libretto cloud deploy my-automations --entry-point src/workflows/check-eligibility.ts ``` In that command: * `my-automations` is the package directory * `src/workflows/check-eligibility.ts` is the entry file relative to `my-automations` ### Deploy workflows Use `cloud deploy` to upload a workflow bundle to Libretto Cloud: ```bash theme={null} cd my-automations npx libretto cloud deploy . ``` That command expects: * `.` to contain `package.json` * `./index.ts` to be the deploy entry point * `index.ts` to export the workflows that should be deployed The positional argument to `deploy` is the source directory to package and upload. It is not the path to a workflow file. If you want to deploy from a different entry file, keep the source directory as the package root and use `--entry-point` relative to that directory: ```bash theme={null} npx libretto cloud deploy my-automations \ --description "payer portal workflows" \ --entry-point src/workflows/check-eligibility.ts ``` The CLI bundles the deploy artifact, uploads it to Libretto Cloud, then waits for the build to finish. When the build is ready, it prints the deployment id and the discovered workflow names. Use `--auto-repair` when failed jobs from this deployment should route to the autofix agent instead of the readonly debug agent. ### Run a deployed workflow After the deployment finishes, call the hosted jobs endpoint with the workflow name from your code. For example, if your workflow file looks like this: ```ts theme={null} // src/workflows/check-eligibility.ts import { workflow } from "libretto"; import { z } from "zod"; export default workflow( "check-eligibility", { input: z.object({ memberId: z.string(), }), output: z.object({ status: z.string(), }), startUrl: "https://example.com/eligibility", }, async ({ page }, input) => { return { status: "eligible", }; }, ); ``` then create the hosted job with `workflow: "check-eligibility"`. The `params` object must match the workflow input schema: ```bash theme={null} npx libretto cloud jobs create check-eligibility \ --params '{"memberId":"12345"}' \ --timeout-seconds 300 ``` That command returns a `job_id` immediately. The equivalent API request is: ```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 } }' ``` Use the returned id to fetch status or the final result: ```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": "" } }' ``` The `workflow` value must match the workflow name declared in code and discovered during deploy, not the deployment id, filename, or export alias. ### Schedule a deployed workflow Use `cloud schedules create` for recurring runs. The cron expression is standard 5-field cron, and the timezone defaults to `UTC`: ```bash theme={null} npx libretto cloud schedules create check-eligibility \ --cron "0 14 * * 1-5" \ --timezone America/Los_Angeles \ --params '{"memberId":"12345"}' ``` The command prints the schedule id and next fire time. Use `--params-file` instead of `--params` when the workflow input is too large to keep inline. ### Hosting options Libretto Cloud is the managed path. If you would rather use a different browser or infrastructure provider, use the alternative providers docs instead: * [Alternative providers overview](/alternative-providers/overview) * [Kernel](/alternative-providers/kernel) * [Browserbase](/alternative-providers/browserbase) * [Steel](/alternative-providers/steel) * [Deploy on GCP](/alternative-providers/gcp) * [Deploy on AWS](/alternative-providers/aws) This page covers the managed hosted-platform flow. The alternative provider pages are the right reference when you want a different managed browser provider or want to own the runtime, scheduler, and secrets infrastructure yourself. Start with the high-level cloud workflow. Create accounts, join organizations, and issue API keys. Manage plans and open the billing portal. Debug workflow failures and investigate hosted workflow runs.