> ## Documentation Index > Fetch the complete documentation index at: https://docs.getcliq.io/llms.txt > Use this file to discover all available pages before exploring further. # Execute a run > Starts a run CliqHub has already validated and assigned to this daemon, and answers as soon as it starts. The run keeps CliqHub's `run_id`; a repeat of a run that is still going returns it again. Without `workspace_dir` the run gets a fresh folder under the daemon's workspace root (`ephemeral/`); a new path is registered as a workspace. The team must be installed here. If its local id has not caught up with CliqHub's yet, `scope` + `slug` find it. Agent and input checks still run: a run whose agents are not ready or whose inputs are missing is refused (`RUN_AGENT_NOT_READY`, `RUN_INPUTS_REQUIRED`, with what is missing in `details`). No credential is needed from this machine. From another host, send `Authorization: Bearer` with a dispatch token CliqHub signed for this daemon or a `cliq_tok_…` personal token of a user in the daemon's realm; this only works once the daemon is connected to CliqHub. See [Authentication](/daemon-api/overview#authentication). ## OpenAPI ````yaml /openapi/daemon-by-tag/daemon-commands.yaml post /v1/execute openapi: 3.1.0 info: title: cliqd API version: 1.9.48 description: >- HTTP API of `cliqd`, the local Cliq daemon. Generated from the daemon source by `scripts/generate_daemon_openapi.mjs` — do not edit by hand. See the [overview](/daemon-api/overview). servers: - url: http://127.0.0.1:4900 description: Local daemon (default port; `CLIQ_DAEMON_PORT` changes it) security: [] tags: - name: Daemon Hub commands description: >- How CliqHub hands work to this daemon: start or offer a run, cancel or resume one, install or uninstall a team, register a workspace and assign teams to it. CliqHub sends them when someone acts in CliqHub, over the daemon's CliqHub connection with a dispatch token. You rarely call them yourself; use the Teams, Workspaces and Runs endpoints instead. Every command carries `tx_id`, CliqHub's command id. A repeated `tx_id` returns the first reply instead of running the command again, and the daemon acknowledges each command back to CliqHub (`ok`, or `error` with the reason), including a body that fails validation. paths: /v1/execute: post: tags: - Daemon Hub commands summary: Execute a run description: >- Starts a run CliqHub has already validated and assigned to this daemon, and answers as soon as it starts. The run keeps CliqHub's `run_id`; a repeat of a run that is still going returns it again. Without `workspace_dir` the run gets a fresh folder under the daemon's workspace root (`ephemeral/`); a new path is registered as a workspace. The team must be installed here. If its local id has not caught up with CliqHub's yet, `scope` + `slug` find it. Agent and input checks still run: a run whose agents are not ready or whose inputs are missing is refused (`RUN_AGENT_NOT_READY`, `RUN_INPUTS_REQUIRED`, with what is missing in `details`). No credential is needed from this machine. From another host, send `Authorization: Bearer` with a dispatch token CliqHub signed for this daemon or a `cliq_tok_…` personal token of a user in the daemon's realm; this only works once the daemon is connected to CliqHub. See [Authentication](/daemon-api/overview#authentication). operationId: daemon_post_execute requestBody: required: true content: application/json: schema: type: object properties: run_id: type: string description: Hub-minted run id the daemon adopts workspace_dir: default: '' description: Workspace path; empty → an ephemeral workspace type: string manifest_yaml: type: string description: Team manifest (YAML) to run team_id: type: string description: Team id (Hub-minted) scope: description: Team scope hint when the local team id has not caught up type: string slug: description: Team slug hint when the local team id has not caught up type: string run_context: default: {} description: Run context (inputs, labels, id, reviewers) type: object properties: id: description: Caller correlation id type: string maxLength: 256 labels: description: Run labels type: object propertyNames: type: string additionalProperties: type: string inputs: description: Run inputs type: object propertyNames: type: string additionalProperties: {} reviewers: description: >- Reviewers per human phase chosen at run start ({ phase: [username] }) type: object propertyNames: type: string additionalProperties: type: array items: type: string run_name: description: Display name type: string execution_type: default: local description: Only `local` today type: string const: local queue_item_id: description: Hub queue correlation id (exclusive claim path) type: string tx_id: description: Hub command id (dedup + ack) type: string required: - run_id - manifest_yaml - team_id additionalProperties: {} examples: default: value: run_id: 0c8d7e6f-5a4b-4c3d-9e2f-1a0b9c8d7e6f workspace_dir: /home/dev/acme-api manifest_yaml: | name: code-review version: 1.4.0 phases: - name: review agent: claude-code team_id: 3f6c2a8e-6b1d-4c1e-9a57-0d2f4b8e91c4 scope: acme slug: code-review run_context: inputs: pr_url: https://github.com/acme/api/pull/42 reviewers: approve: - sshah run_name: fix-login-timeout tx_id: tx-5d2c9a responses: '200': description: Success. content: application/json: schema: type: object required: - ok - data properties: ok: type: boolean const: true data: $ref: '#/components/schemas/ExecuteAccepted' example: ok: true data: accepted: true run_id: 0c8d7e6f-5a4b-4c3d-9e2f-1a0b9c8d7e6f '400': description: >- `TEAM_NOT_INSTALLED` — The team is not installed on this daemon (by id, or by `scope` + `slug`). `RUN_INPUTS_REQUIRED` — Inputs the first phases need are missing. `details` has `missing_inputs` and `phase`. `RUN_AGENT_NOT_READY` — An agent the team needs is missing or not configured. `details.agents` says what to fix. `PAYLOAD_INVALID` — The body (query string for `GET`) fails the request schema. `details` lists each issue. `BAD_REQUEST` — The body is not valid JSON or is larger than the route allows (10 MB; artifact uploads more). content: application/json: schema: $ref: '#/components/schemas/ErrorReply' examples: TEAM_NOT_INSTALLED: summary: TEAM_NOT_INSTALLED value: ok: false error: code: TEAM_NOT_INSTALLED message: >- Team '3f6c2a8e-6b1d-4c1e-9a57-0d2f4b8e91c4' is not installed on this daemon RUN_INPUTS_REQUIRED: summary: RUN_INPUTS_REQUIRED value: ok: false error: code: RUN_INPUTS_REQUIRED message: The run needs inputs before its first phase details: missing_inputs: - name: pr_url required: true agent: claude-code phase: review RUN_AGENT_NOT_READY: summary: RUN_AGENT_NOT_READY value: ok: false error: code: RUN_AGENT_NOT_READY message: Agents the run needs are missing or unconfigured PAYLOAD_INVALID: summary: PAYLOAD_INVALID value: ok: false error: code: PAYLOAD_INVALID message: >- run_id: Invalid input: expected string, received undefined; manifest_yaml: Invalid input: expected string, received undefined; team_id: Invalid input: expected string, received undefined details: - path: run_id message: 'Invalid input: expected string, received undefined' - path: manifest_yaml message: 'Invalid input: expected string, received undefined' - path: team_id message: 'Invalid input: expected string, received undefined' BAD_REQUEST: summary: BAD_REQUEST value: ok: false error: code: BAD_REQUEST message: >- Request body could not be read: Unexpected token } in JSON at position 12 '401': description: >- `UNAUTHORIZED` — A caller on another host sent no `Authorization: Bearer` token, or one that does not verify (expired, wrong audience). content: application/json: schema: $ref: '#/components/schemas/ErrorReply' examples: UNAUTHORIZED: summary: UNAUTHORIZED value: ok: false error: code: UNAUTHORIZED message: Missing or invalid Authorization Bearer token '403': description: >- `WEB_REQUEST_REFUSED` — The request carries an `Origin` header (it came from a web page). `HOST_NOT_LOCAL` — A loopback caller addressed a `Host` other than localhost (DNS rebinding guard). `LOCAL_ONLY` — The daemon isn't connected to CliqHub (no dispatch key) and the caller is on another host. `FORBIDDEN` — A `cliq_tok_…` token's user is not in this daemon's realm ACL, or the ACL is not loaded yet. content: application/json: schema: $ref: '#/components/schemas/ErrorReply' examples: WEB_REQUEST_REFUSED: summary: WEB_REQUEST_REFUSED value: ok: false error: code: WEB_REQUEST_REFUSED message: cliqd doesn't accept requests from web pages HOST_NOT_LOCAL: summary: HOST_NOT_LOCAL value: ok: false error: code: HOST_NOT_LOCAL message: cliqd only answers requests addressed to localhost LOCAL_ONLY: summary: LOCAL_ONLY value: ok: false error: code: LOCAL_ONLY message: >- This cliqd isn't connected to CliqHub yet, so from another machine it only accepts a local token (minted by tokens/create on the machine running cliqd) FORBIDDEN: summary: FORBIDDEN value: ok: false error: code: FORBIDDEN message: Access denied — identity not in realm ACL '422': description: >- `TEAM_MANIFEST_INVALID` — `manifest_yaml` does not parse or validate. content: application/json: schema: $ref: '#/components/schemas/ErrorReply' examples: TEAM_MANIFEST_INVALID: summary: TEAM_MANIFEST_INVALID value: ok: false error: code: TEAM_MANIFEST_INVALID message: Team manifest failed validation '500': description: >- `INTERNAL_ERROR` — An unexpected daemon fault. The message names the request id; the cause is in the cliqd log. content: application/json: schema: $ref: '#/components/schemas/ErrorReply' examples: INTERNAL_ERROR: summary: INTERNAL_ERROR value: ok: false error: code: INTERNAL_ERROR message: >- cliqd hit an unexpected error (request 7f3a…). Details are in the cliqd log. security: - {} - DaemonBearer: [] components: schemas: ExecuteAccepted: type: object required: - accepted - run_id properties: accepted: type: boolean const: true description: The run was accepted and started; it is not finished. run_id: type: string description: The run id (CliqHub's). example: 0c8d7e6f-5a4b-4c3d-9e2f-1a0b9c8d7e6f ErrorReply: type: object description: >- Every failure. Switch on `error.code` — it is stable; `message` is for people and may change. required: - ok - error properties: ok: type: boolean const: false error: type: object required: - code - message properties: code: type: string description: Stable error code. See [Errors](/daemon-api/errors). example: TEAM_NOT_FOUND message: type: string description: What went wrong and, where possible, what to do. example: Team 'acme/code-review' not found details: description: >- Structured detail when there is some: the list of schema issues for `PAYLOAD_INVALID`, the agent problems for `TEAM_AGENT_CONFIG_REQUIRED`, … securitySchemes: DaemonBearer: type: http scheme: bearer description: >- Not needed from the same machine. From another host: a dispatch JWT CliqHub signed for this daemon, or a `cliq_tok_…` personal token whose user is in the daemon's realm. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.