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/<run_id>); 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.
POST
/
v1
/
execute
Execute a run
curl --request POST \
--url http://127.0.0.1:4900/v1/execute \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"run_id": "0c8d7e6f-5a4b-4c3d-9e2f-1a0b9c8d7e6f",
"workspace_dir": "/home/dev/acme-api",
"manifest_yaml": "name: code-review\nversion: 1.4.0\nphases:\n - name: review\n agent: claude-code\n",
"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"
}
'import requests
url = "http://127.0.0.1:4900/v1/execute"
payload = {
"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"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
run_id: '0c8d7e6f-5a4b-4c3d-9e2f-1a0b9c8d7e6f',
workspace_dir: '/home/dev/acme-api',
manifest_yaml: 'name: code-review\nversion: 1.4.0\nphases:\n - name: review\n agent: claude-code\n',
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'
})
};
fetch('http://127.0.0.1:4900/v1/execute', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_PORT => "4900",
CURLOPT_URL => "http://127.0.0.1:4900/v1/execute",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "http://127.0.0.1:4900/v1/execute"
payload := strings.NewReader("{\n \"run_id\": \"0c8d7e6f-5a4b-4c3d-9e2f-1a0b9c8d7e6f\",\n \"workspace_dir\": \"/home/dev/acme-api\",\n \"manifest_yaml\": \"name: code-review\\nversion: 1.4.0\\nphases:\\n - name: review\\n agent: claude-code\\n\",\n \"team_id\": \"3f6c2a8e-6b1d-4c1e-9a57-0d2f4b8e91c4\",\n \"scope\": \"acme\",\n \"slug\": \"code-review\",\n \"run_context\": {\n \"inputs\": {\n \"pr_url\": \"https://github.com/acme/api/pull/42\"\n },\n \"reviewers\": {\n \"approve\": [\n \"sshah\"\n ]\n }\n },\n \"run_name\": \"fix-login-timeout\",\n \"tx_id\": \"tx-5d2c9a\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("http://127.0.0.1:4900/v1/execute")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"run_id\": \"0c8d7e6f-5a4b-4c3d-9e2f-1a0b9c8d7e6f\",\n \"workspace_dir\": \"/home/dev/acme-api\",\n \"manifest_yaml\": \"name: code-review\\nversion: 1.4.0\\nphases:\\n - name: review\\n agent: claude-code\\n\",\n \"team_id\": \"3f6c2a8e-6b1d-4c1e-9a57-0d2f4b8e91c4\",\n \"scope\": \"acme\",\n \"slug\": \"code-review\",\n \"run_context\": {\n \"inputs\": {\n \"pr_url\": \"https://github.com/acme/api/pull/42\"\n },\n \"reviewers\": {\n \"approve\": [\n \"sshah\"\n ]\n }\n },\n \"run_name\": \"fix-login-timeout\",\n \"tx_id\": \"tx-5d2c9a\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://127.0.0.1:4900/v1/execute")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"run_id\": \"0c8d7e6f-5a4b-4c3d-9e2f-1a0b9c8d7e6f\",\n \"workspace_dir\": \"/home/dev/acme-api\",\n \"manifest_yaml\": \"name: code-review\\nversion: 1.4.0\\nphases:\\n - name: review\\n agent: claude-code\\n\",\n \"team_id\": \"3f6c2a8e-6b1d-4c1e-9a57-0d2f4b8e91c4\",\n \"scope\": \"acme\",\n \"slug\": \"code-review\",\n \"run_context\": {\n \"inputs\": {\n \"pr_url\": \"https://github.com/acme/api/pull/42\"\n },\n \"reviewers\": {\n \"approve\": [\n \"sshah\"\n ]\n }\n },\n \"run_name\": \"fix-login-timeout\",\n \"tx_id\": \"tx-5d2c9a\"\n}"
response = http.request(request)
puts response.read_body{
"ok": true,
"data": {
"accepted": true,
"run_id": "0c8d7e6f-5a4b-4c3d-9e2f-1a0b9c8d7e6f"
}
}
Authorizations
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.
Body
application/json
Hub-minted run id the daemon adopts
Team manifest (YAML) to run
Team id (Hub-minted)
Workspace path; empty → an ephemeral workspace
Team scope hint when the local team id has not caught up
Team slug hint when the local team id has not caught up
Run context (inputs, labels, id, reviewers)
Show child attributes
Show child attributes
Display name
Only local today
Allowed value:
"local"Hub queue correlation id (exclusive claim path)
Hub command id (dedup + ack)
⌘I
Execute a run
curl --request POST \
--url http://127.0.0.1:4900/v1/execute \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"run_id": "0c8d7e6f-5a4b-4c3d-9e2f-1a0b9c8d7e6f",
"workspace_dir": "/home/dev/acme-api",
"manifest_yaml": "name: code-review\nversion: 1.4.0\nphases:\n - name: review\n agent: claude-code\n",
"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"
}
'import requests
url = "http://127.0.0.1:4900/v1/execute"
payload = {
"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"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
run_id: '0c8d7e6f-5a4b-4c3d-9e2f-1a0b9c8d7e6f',
workspace_dir: '/home/dev/acme-api',
manifest_yaml: 'name: code-review\nversion: 1.4.0\nphases:\n - name: review\n agent: claude-code\n',
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'
})
};
fetch('http://127.0.0.1:4900/v1/execute', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_PORT => "4900",
CURLOPT_URL => "http://127.0.0.1:4900/v1/execute",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "http://127.0.0.1:4900/v1/execute"
payload := strings.NewReader("{\n \"run_id\": \"0c8d7e6f-5a4b-4c3d-9e2f-1a0b9c8d7e6f\",\n \"workspace_dir\": \"/home/dev/acme-api\",\n \"manifest_yaml\": \"name: code-review\\nversion: 1.4.0\\nphases:\\n - name: review\\n agent: claude-code\\n\",\n \"team_id\": \"3f6c2a8e-6b1d-4c1e-9a57-0d2f4b8e91c4\",\n \"scope\": \"acme\",\n \"slug\": \"code-review\",\n \"run_context\": {\n \"inputs\": {\n \"pr_url\": \"https://github.com/acme/api/pull/42\"\n },\n \"reviewers\": {\n \"approve\": [\n \"sshah\"\n ]\n }\n },\n \"run_name\": \"fix-login-timeout\",\n \"tx_id\": \"tx-5d2c9a\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("http://127.0.0.1:4900/v1/execute")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"run_id\": \"0c8d7e6f-5a4b-4c3d-9e2f-1a0b9c8d7e6f\",\n \"workspace_dir\": \"/home/dev/acme-api\",\n \"manifest_yaml\": \"name: code-review\\nversion: 1.4.0\\nphases:\\n - name: review\\n agent: claude-code\\n\",\n \"team_id\": \"3f6c2a8e-6b1d-4c1e-9a57-0d2f4b8e91c4\",\n \"scope\": \"acme\",\n \"slug\": \"code-review\",\n \"run_context\": {\n \"inputs\": {\n \"pr_url\": \"https://github.com/acme/api/pull/42\"\n },\n \"reviewers\": {\n \"approve\": [\n \"sshah\"\n ]\n }\n },\n \"run_name\": \"fix-login-timeout\",\n \"tx_id\": \"tx-5d2c9a\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://127.0.0.1:4900/v1/execute")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"run_id\": \"0c8d7e6f-5a4b-4c3d-9e2f-1a0b9c8d7e6f\",\n \"workspace_dir\": \"/home/dev/acme-api\",\n \"manifest_yaml\": \"name: code-review\\nversion: 1.4.0\\nphases:\\n - name: review\\n agent: claude-code\\n\",\n \"team_id\": \"3f6c2a8e-6b1d-4c1e-9a57-0d2f4b8e91c4\",\n \"scope\": \"acme\",\n \"slug\": \"code-review\",\n \"run_context\": {\n \"inputs\": {\n \"pr_url\": \"https://github.com/acme/api/pull/42\"\n },\n \"reviewers\": {\n \"approve\": [\n \"sshah\"\n ]\n }\n },\n \"run_name\": \"fix-login-timeout\",\n \"tx_id\": \"tx-5d2c9a\"\n}"
response = http.request(request)
puts response.read_body{
"ok": true,
"data": {
"accepted": true,
"run_id": "0c8d7e6f-5a4b-4c3d-9e2f-1a0b9c8d7e6f"
}
}