---
title: "POST /experimental/launch-runs"
method: POST
path: "/experimental/launch-runs"
tags: ["Launch Runs"]
---

# POST /experimental/launch-runs

`POST /experimental/launch-runs`

Creates a launch run and starts the CloudLaunch workflow against it.

## Headers

- `Authorization` string

## Request body

- object
  - `workspaceName` string, required
  - `skill` string, required — The plugin to install and the skill to run. A value without a `file:` prefix means a registry ref (either a full `workspace/plugin[@version]` or a bare `plugin[@version]` name resolved across the workspaces the caller can see); a value with a `file:` prefix means a local plugin path inside the cloned repo (e.g. file:apps/cli/plugins/agent-enablement). Either form may carry a trailing `#skill` selector (e.g. `workspace/plugin@1.0.0#implement-ticket` or `file:apps/cli/plugins/agent-enablement#implement-ticket`) that installs the whole plugin and launches the one named skill; it is required when the plugin exposes more than one skill. This is a wire convention: the value is stored verbatim and interpreted downstream by the launch recipe.
  - `repo` string, required
  - `baseBranch` string
  - `snapshot` string — Commit SHA or tag pinning the repo snapshot for this run. Pins the checked-out repository, not the sandbox runtime image. Use `sandboxSnapshot` for the latter.
  - `sandboxSnapshot` string — Operational override selecting the sandbox runtime image the launch run is created from. Distinct from `snapshot`, which pins the checked-out repository. When omitted the run falls back to the configured default.
  - `workdir` string
  - `agent` string
  - `model` string
  - `encryptedEnvUpload` object — Reference to an encrypted-input upload (e.g. an env-file) delivered to the launch sandbox. Must be an existing, viewable, encrypted upload. Mutually exclusive with `environmentId`.
    - `uploadKey` string, required
  - `environmentId` string, uuid — Id of a workspace environment whose sealed `.env` payload is opened server-side at launch and delivered to the sandbox. Must belong to the launch workspace. A live reference resolved when each run starts, so environment edits affect subsequently started and resumed runs and a deleted environment fails the launch.
  - `uploads` object — Additional upload keys (context archives, config tarballs) keyed by a caller-defined logical name. Each must be an existing, viewable upload.
  - `inputs` object — Skill-specific inputs forwarded to the launched skill, keyed by the skill's own placeholder names (e.g. ISSUE_IDENTIFIER, ISSUE_TITLE, ISSUE_DESCRIPTION).
  - `instructions` string — Free-text instructions appended to the skill prompt the launch agent runs, mirroring the local `--instructions` flag. Distinct from the structured `inputs` channel.
  - `label` string
  - `metadata` object

## Response `201`

Default Response

- object
  - `links` object, required
    - `self` string, uri, required
  - `data` object, required
    - `id` string, uuid, required
    - `type` 'launch-run', required
    - `attributes` object, required
      - `workflowId` string, nullable, required
      - `status` union, required
        - 'pending'
        - 'completed'
        - 'failed'
      - `label` string, nullable, required
      - `createdBy` string, uuid, nullable, required
      - `createdAt` string, date-time, required

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `500` — Internal Server Error

---

[API](https://skmtc.net/tessl/apis/tessl-api.md) · [All operations](https://skmtc.net/tessl/apis/tessl-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tessl/tessl-api/versions/fbb186825642/schema)