Register a custom Runner

HTTP200 establishes record and ownership creation. phase=pending does not mean Edge connected. Execute connect_cmd on the target host; it contains credentials and must not enter shared logs. Bounded replay with the same request identifier does not update the name.

POST https://api.moi.matrixorigin.cn/v5/agent-runners/custom

Before you call this API

Set BASE_URL to the product API prefix https://api.moi.matrixorigin.cn/v5. For private deployments, use the corresponding product API URL.

Prepare identity and identifiers.

Request

curl --request POST \
  "$BASE_URL/agent-runners/custom" \
  --header "X-API-Key: $MOI_KEY" \
  --header "X-Workspace-ID: $WORKSPACE_ID" \
  --header "X-Request-ID: $REQUEST_ID" \
  --header "Content-Type: application/json" \
  --data @- <<JSON
{"name": "示例Runner"}
JSON

Parameter

Location

Type

Required

Description

X-Workspace-ID

Headers

string

Yes

Target Workspace in the same environment; there is no Workspace path segment.

name

Body

string

Yes

Nonempty Runner name; must be unique within the Workspace.

X-Request-ID

Headers

string

Condition

Correlates/replays the same registration operation, with source verified by the formal boundary. Use a new value for a different registration task.

Successful response

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": "runner-example",
    "workspace_id": "workspace-example",
    "user_id": "user-example",
    "name": "示例Runner",
    "runner_type": "custom",
    "edge_agent_id": "runner-runner-example",
    "phase": "pending",
    "token_expires_at": "2026-12-12T01:00:00Z",
    "created_at": "2026-11-12T01:00:00Z",
    "updated_at": "2026-11-12T01:00:00Z",
    "connect_cmd": "astra-edge --edge-id runner-runner-example --server-url wss://edge.example.invalid --token example-edge-token --reconnect true"
  }
}

Field

Type

Description

code

string

OK on success.

msg

string

Response information; OK on success.

data

object

Response objects and omission conditions.

Error responses

Errors and recovery boundaries distinguishes Runner, Edge renewal, and compute observations. They do not share one numeric error table.

Last updated on