agentrix-run

agentrix-run submits an Agentrix CI run from a command line or CI job. Use it when you want a pipeline to ask an Agentrix agent to review a pull request, summarize a change, produce structured output, or start an asynchronous task that you can inspect in the Agentrix app.

It is separate from the main agentrix daemon CLI. agentrix-run talks to the Agentrix API, creates a CI run, and either streams events until the task finishes or returns after creating the run.

Requirements

• Node.js 20 or newer in the CI job.
• An Agentrix API key with access to the target organization and repository.
• A reachable Agentrix API endpoint. The public cloud endpoint defaults to https://agentrix.xmz.ai.
• A repository registered in Agentrix. In GitHub Actions and GitLab CI, agentrix-run can detect the current repository from CI environment variables.
• A runner ID, unless your Agentrix deployment has a default cloud runner configured or the selected companion agent is already bound to a machine.
• For --resume, an existing task ID. Resume mode does not need repository context or a runner ID.

Set the API key as an environment variable:

export AGENTRIX_API_KEY=<your-api-key>

You can pass the key as --api-key. Use --base-url or AGENTRIX_BASE_URL only when you need to override the default public cloud API URL.

Security Mode

agentrix-run creates CI runs through the Agentrix API. When you pass a machine-* runner ID, the task executes on that local machine, but the CI run is still a plaintext CI mode task: the prompt and CI context are sent to the API as regular request data and stored as regular task events.

This is different from local tasks started from the Agentrix app, where the app has the user's local encryption material and can submit encryptedMessage, dataEncryptionKey, and ownerEncryptedDataKey. Do not put secrets in --prompt; keep secrets in CI secret stores or machine-local configuration.

Run from a shell

Pin the npm package version in CI. The repository currently publishes @agentrix/agentrix-run.

npx --yes @agentrix/[email protected] \
  --agent codex \
  --prompt "Review this change and return one short summary sentence." \
  --response-mode stream \
  --runner-id cloud-default

If you are running outside GitHub Actions or GitLab CI, pass the repository context yourself:

npx --yes @agentrix/[email protected] \
  --agent codex \
  --prompt "Review this branch." \
  --repo '{"gitServerId":"github","owner":"xmz-ai","name":"agentrix"}' \
  --base-ref develop \
  --head-ref feature/demo \
  --pr-number 123 \
  --runner-id cloud-default

You can also append a message to an existing task. agentrix-run reuses that task's execution context; if the worker is online, the message is delivered to the agent, and if the worker has exited, the backend resumes the task:

npx --yes @agentrix/[email protected] \
  --resume task-abc123 \
  --prompt "Continue checking the failing tests and return the final conclusion." \
  --response-mode stream

Response modes

Mode	Behavior	Exit code
stream	Creates the run, streams task events, waits for a terminal status, and exits when the run finishes. This is the default.	0 only when the final status is completed; non-zero for failed, canceled, or timeout.
async	Creates the run and prints the run metadata without waiting for completion.	0 if the run was created.

With --resume, response modes have the same meaning: stream keeps observing the task after the message is accepted, and async only confirms that the backend accepted the message.

In stream mode, stdout contains JSON lines for streamed events:

{"type":"run.created","data":{"runId":"run-..."}}
{"type":"task.event","data":{}}
{"type":"run.completed","data":{"runId":"run-...","status":"completed","result":"...","detailUrl":"..."}}

In async mode, stdout prints standard fields:

run_id=run-abc123
status=queued
detail_url=https://agentrix.xmz.ai/tasks/task-abc123

Use --result-file when another CI step needs to read the result:

npx --yes @agentrix/[email protected] \
  --agent codex \
  --prompt "Summarize this PR." \
  --result-file agentrix-result.json

The result file is JSON:

{
  "runId": "run-abc123",
  "status": "completed",
  "result": "Short summary text.",
  "structuredOutput": null,
  "detailUrl": "https://agentrix.xmz.ai/tasks/task-abc123"
}

Structured output

Pass a JSON Schema string with --output-schema. agentrix-run normalizes object schemas for strict structured output: object nodes get additionalProperties: false, and every declared property is added to required.

npx --yes @agentrix/[email protected] \
  --agent codex \
  --prompt "Summarize this change." \
  --output-schema '{"type":"object","properties":{"summary":{"type":"string"},"risk":{"type":"string"}}}' \
  --result-file agentrix-result.json

The normalized structured output is written under structuredOutput in the result file and exposed as structured-output-json by the GitHub Action.

GitHub Actions

Use the public action wrapper for GitHub Actions:

name: Agentrix

on:
  pull_request:

jobs:
  agentrix:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - id: agentrix
        uses: xmz-ai/agentrix-run-action@v1
        with:
          api-key: ${{ secrets.AGENTRIX_API_KEY }}
          agent: codex
          prompt: >-
            Review this PR and return one short summary sentence.
          runner-id: cloud-default

      - name: Print result
        run: |
          echo "run id: ${{ steps.agentrix.outputs.run-id }}"
          echo "status: ${{ steps.agentrix.outputs.status }}"
          echo "detail url: ${{ steps.agentrix.outputs.detail-url }}"
          echo "result: ${{ steps.agentrix.outputs.result }}"

The action automatically detects repository owner, repository name, ref, commit SHA, pull request base/head refs, pull request number, event name, and workflow run URL from GitHub Actions environment variables.

GitHub Action inputs

Input	Required	Description
agent	Yes	Agent ID or name, for example codex.
prompt	Yes	Prompt text sent to Agentrix.
base-url	No	Agentrix API base URL override. Defaults to https://agentrix.xmz.ai.
api-key	Yes	Agentrix API key. Store it in GitHub Actions secrets.
title	No	Custom task title in Agentrix.
output-schema	No	JSON Schema string for structured output.
repo	No	JSON repository override. Use this when auto-detection is not enough.
git-server-id	No	Git server ID used for the auto-detected repository. Defaults to github.
response-mode	No	stream or async. Defaults to stream.
issue-number	No	Issue number override. Pull request numbers are detected from the event payload.
branch-name	No	Explicit task checkout branch. When set, it overrides the auto-detected PR/MR head branch for workspace checkout.
timeout	No	HTTP read timeout; in stream mode it is also the total wait timeout, in seconds. Defaults to 30 seconds for async and 1800 seconds for stream.
capability-profile	No	Capability profile passed to execution.
runner-id	Usually yes	Runner ID, such as a cloud-* or machine-* ID. You can omit it only when your deployment has a default cloud runner or the selected companion agent is machine-bound.

GitHub Action outputs

Output	Description
run-id	Agentrix run ID.
status	Final run status in stream mode, or creation status in async mode.
detail-url	Agentrix task URL.
result	Final result text. Empty in async mode.
structured-output-json	Final structured output as a JSON string. null when no structured output exists.

GitLab CI

For GitLab CI, add a hidden .agentrix-run job to your .gitlab-ci.yml or to a shared CI template that your projects can include:

.agentrix-run:
  image: node:20-alpine
  variables:
    AGENTRIX_RESPONSE_MODE: stream
  script:
    - |
      set -eu
      set -- \
        --agent "$AGENTRIX_AGENT" \
        --prompt "$AGENTRIX_PROMPT" \
        --response-mode "${AGENTRIX_RESPONSE_MODE:-stream}" \
        --runner-id "$AGENTRIX_RUNNER_ID"

      if [ -n "${AGENTRIX_TITLE:-}" ]; then
        set -- "$@" --title "$AGENTRIX_TITLE"
      fi
      if [ -n "${AGENTRIX_OUTPUT_SCHEMA:-}" ]; then
        set -- "$@" --output-schema "$AGENTRIX_OUTPUT_SCHEMA"
      fi
      if [ -n "${AGENTRIX_REPO:-}" ]; then
        set -- "$@" --repo "$AGENTRIX_REPO"
      fi
      if [ -n "${AGENTRIX_BRANCH_NAME:-}" ]; then
        set -- "$@" --branch-name "$AGENTRIX_BRANCH_NAME"
      fi
      if [ -n "${AGENTRIX_TIMEOUT:-}" ]; then
        set -- "$@" --timeout "$AGENTRIX_TIMEOUT"
      fi
      if [ -n "${AGENTRIX_CAPABILITY_PROFILE:-}" ]; then
        set -- "$@" --capability-profile "$AGENTRIX_CAPABILITY_PROFILE"
      fi
      if [ -n "${AGENTRIX_RESULT_FILE:-}" ]; then
        set -- "$@" --result-file "$AGENTRIX_RESULT_FILE"
      fi
      if [ -n "${AGENTRIX_BASE_URL:-}" ]; then
        set -- "$@" --base-url "$AGENTRIX_BASE_URL"
      fi

      npx --yes @agentrix/agentrix-run "$@"

Then extend the hidden job from a visible pipeline job:

agentrix_review:
  extends: .agentrix-run
  variables:
    AGENTRIX_AGENT: codex
    AGENTRIX_PROMPT: Review this merge request and return one short summary sentence.
    AGENTRIX_RESPONSE_MODE: stream
    AGENTRIX_RUNNER_ID: cloud-default

Store AGENTRIX_API_KEY as a masked CI variable. GitLab CI detection reads project path, commit ref, commit SHA, merge request source/target branches, merge request IID, job URL, and pipeline URL from the standard GitLab environment.

Pipelines Triggered by the Daemon Webhook

When a GitLab pipeline is triggered by the Agentrix daemon webhook bridge, the daemon normalizes the GitLab webhook into GITLAB_BRIDGE_EVENT_NAME and GITLAB_BRIDGE_EVENT_ACTION, then sets issue, MR, pipeline, and comment variables with the same GITLAB_BRIDGE_* prefix. Standard GitLab variables are still available, so agentrix-run can auto-detect the repository and commit from CI_PROJECT_PATH, CI_COMMIT_REF_NAME, and CI_COMMIT_SHA.

Use one job per webhook class and gate each job with rules on the normalized event variables:

agentrix_issue_triage:
  extends: .agentrix-run
  rules:
    - if: '$GITLAB_BRIDGE_EVENT_NAME == "issues"'
      when: on_success
    - when: never
  variables:
    AGENTRIX_AGENT: codex
    AGENTRIX_RESPONSE_MODE: stream
    AGENTRIX_RUNNER_ID: cloud-default
    AGENTRIX_TITLE: "Issue #$GITLAB_BRIDGE_ISSUE_NUMBER: $GITLAB_BRIDGE_EVENT_ACTION"
    AGENTRIX_PROMPT: >-
      Review GitLab issue #$GITLAB_BRIDGE_ISSUE_NUMBER in this repository.
      Event action: $GITLAB_BRIDGE_EVENT_ACTION.
      Issue title: $GITLAB_BRIDGE_ISSUE_TITLE.
      Decide whether this needs agent work, and return a short triage summary.

MR review job:

agentrix_mr_review:
  extends: .agentrix-run
  rules:
    - if: '$GITLAB_BRIDGE_EVENT_NAME == "pull_request" && ($GITLAB_BRIDGE_EVENT_ACTION == "opened" || $GITLAB_BRIDGE_EVENT_ACTION == "reopened" || $GITLAB_BRIDGE_EVENT_ACTION == "synchronize")'
      when: on_success
    - when: never
  variables:
    AGENTRIX_AGENT: codex
    AGENTRIX_RESPONSE_MODE: stream
    AGENTRIX_RUNNER_ID: cloud-default
    AGENTRIX_TITLE: "MR !$GITLAB_BRIDGE_PR_NUMBER review"
    AGENTRIX_PROMPT: >-
      Review GitLab merge request !$GITLAB_BRIDGE_PR_NUMBER.
      Source branch: $GITLAB_BRIDGE_HEAD_REF.
      Target branch: $GITLAB_BRIDGE_BASE_REF.
      Return concise findings and suggested fixes.

Comment job. The daemon forwards supported non-system comments by default:

agentrix_comment_command:
  extends: .agentrix-run
  rules:
    - if: '$GITLAB_BRIDGE_EVENT_NAME == "issue_comment"'
      when: on_success
    - when: never
  variables:
    AGENTRIX_AGENT: codex
    AGENTRIX_RESPONSE_MODE: stream
    AGENTRIX_RUNNER_ID: cloud-default
    AGENTRIX_TITLE: "Agentrix comment command"
    AGENTRIX_PROMPT: >-
      Handle this GitLab comment.
      Issue: $GITLAB_BRIDGE_ISSUE_NUMBER.
      Merge request: $GITLAB_BRIDGE_PR_NUMBER.
      Comment: $GITLAB_BRIDGE_COMMENT_BODY

Pipeline-failure diagnosis job. Pipeline webhooks are forwarded as workflow_run events, including pipelines created by trigger tokens:

agentrix_pipeline_failed:
  extends: .agentrix-run
  rules:
    - if: '$GITLAB_BRIDGE_EVENT_NAME == "workflow_run" && $GITLAB_BRIDGE_EVENT_ACTION == "completed" && $GITLAB_BRIDGE_WORKFLOW_RUN_CONCLUSION == "failure"'
      when: on_success
    - when: never
  variables:
    AGENTRIX_AGENT: codex
    AGENTRIX_RESPONSE_MODE: stream
    AGENTRIX_RUNNER_ID: cloud-default
    AGENTRIX_TITLE: "Pipeline $GITLAB_BRIDGE_WORKFLOW_RUN_ID failed"
    AGENTRIX_PROMPT: >-
      Diagnose failed GitLab pipeline $GITLAB_BRIDGE_WORKFLOW_RUN_ID.
      Ref: $GITLAB_BRIDGE_WORKFLOW_RUN_REF.
      SHA: $GITLAB_BRIDGE_WORKFLOW_RUN_SHA.
      Pipeline URL: $GITLAB_BRIDGE_WORKFLOW_RUN_URL.
      Explain the likely cause and propose the smallest fix.

For other action-specific handling, split jobs with stricter rules:

agentrix_issue_closed:
  extends: .agentrix-run
  rules:
    - if: '$GITLAB_BRIDGE_EVENT_NAME == "issues" && $GITLAB_BRIDGE_EVENT_ACTION == "closed"'
      when: on_success
    - when: never
  variables:
    AGENTRIX_AGENT: codex
    AGENTRIX_PROMPT: "Summarize the closing state of GitLab issue #$GITLAB_BRIDGE_ISSUE_NUMBER."
    AGENTRIX_RESPONSE_MODE: async
    AGENTRIX_RUNNER_ID: cloud-default

Do not rely on CI_PIPELINE_SOURCE alone to separate sources. Daemon-triggered pipelines are usually trigger pipelines in GitLab, so prefer GITLAB_BRIDGE_EVENT_NAME and GITLAB_BRIDGE_EVENT_ACTION for routing.

CLI options

Option	Required	Description
--agent <agent>	Required for new runs	Agent ID or name.
--resume <task-id>	No	Append the --prompt message to an existing task. When set, agentrix-run does not create a new CI run and does not require --agent.
--prompt <prompt>	Yes	Prompt text sent to Agentrix.
--title <text>	No	Custom task title in Agentrix.
--client-task-id <id>	No	Stable business key for idempotent creation. Retries with the same API user and key return the same run; the first request wins.
--repo <json>	Usually auto-detected	JSON repository object. It must include gitServerId and either serverRepoId or owner plus name.
--output-schema <json>	No	JSON Schema string for structured output. Object schemas are normalized for strict output.
--ref <ref>	No	Git ref for the run. Overrides auto-detected CI ref.
--sha <sha>	No	Commit SHA for the run. Overrides auto-detected CI SHA.
--base-ref <ref>	No	Base/target branch for a pull request or merge request. Sent to the API as git.baseRef.
--head-ref <ref>	No	Head/source branch for a pull request or merge request. Sent to the API as git.headRef.
--head-sha <sha>	No	Head/source commit for a pull request or merge request. Sent to the API as git.headSha.
--checkout-ref <ref>	No	Explicit ref used to initialize the workspace. This is the only source of git.checkoutRef.
--checkout-sha <sha>	No	Explicit SHA used to initialize the workspace. This is the only source of git.checkoutSha.
--branch-name <name>	No	Explicit task working branch. Sent to the API as git.branchName; this creates an explicit task branch binding.
--pr-number <number>	No	Pull request or merge request number. Must be a positive integer.
--issue-number <number>	No	Issue number. Must be a positive integer.
--response-mode <stream|async>	No	stream waits for completion; async only creates the run. Defaults to stream.
--timeout <seconds>	No	HTTP read timeout; in stream mode it is also the total wait timeout. Defaults to 30 for async and 1800 for stream. Must be a positive integer. The connect timeout is fixed at 10 seconds.
--capability-profile <name>	No	Capability profile passed to execution.
--runner-id <cloud-id|machine-id>	Usually yes	Specific runner to use, for example cloud-default or machine-.... You can omit it only when your deployment has a default cloud runner or the selected companion agent is machine-bound.
--result-file <path>	No	Write run result JSON to this path.
--base-url <url>	No	Agentrix API base URL override. Defaults to https://agentrix.xmz.ai; takes precedence over AGENTRIX_BASE_URL.
--api-key <api-key>	Required unless AGENTRIX_API_KEY is set	Agentrix API key. Prefer environment variables or CI secrets.
--metadata <key=value>	No	Add metadata to the run. Repeat the flag for multiple entries.
--help	No	Print command help.

Repository JSON

--repo accepts a JSON object with this shape:

{
  "gitServerId": "github",
  "owner": "xmz-ai",
  "name": "agentrix"
}

You can also identify a repository by server-side repository ID:

{
  "gitServerId": "github",
  "serverRepoId": "repo-abc123"
}

When a CI provider is detected, explicit values in --repo override detected values.

Branch context and worker environment

agentrix-run sends branch context to the API under CreateCiRunRequest.git:

Explicit CLI options always win. Automatic git.ref and git.sha detection describes the current CI job checkout only: GitHub uses GITHUB_REF and GITHUB_SHA; GitLab uses CI_COMMIT_REF_NAME and CI_COMMIT_SHA. Bridge variables never replace those fields.

CLI option	API field	Meaning
--base-ref	git.baseRef	PR/MR target branch, for example main.
--head-ref	git.headRef	PR/MR source branch, for example feature/demo.
--head-sha	git.headSha	PR/MR source commit.
--checkout-ref	git.checkoutRef	Ref used as the workspace start point.
--checkout-sha	git.checkoutSha	SHA used as the workspace start point.
--branch-name	git.branchName	Explicit task working branch override.

The API maps these values into controlled Agentrix task fields:

• git.baseRef becomes task baseBranch.
• git.headRef and git.headSha remain observed PR/MR head context.
• git.ref and git.sha are current-job facts; they are not promoted into checkout instructions or MR head fields.
• Only explicit git.checkoutRef and git.checkoutSha define the workspace initialization start point.
• git.checkoutSha is used only when explicitly provided; git.sha and git.headSha are not promoted to it.
• git.branchName becomes task branchName when provided.
• If git.branchName is omitted, task branchName stays unset and branch binding stays none.

The worker initializes unbound CI workspaces from an explicit checkoutSha; otherwise it uses checkoutRef or the base branch without binding the task to that local branch. Explicit branchName tasks still use that branch as a strong task branch binding.

The final agent process receives protected environment variables derived from those task fields:

Worker env	Source task field	Meaning
AGENTRIX_BASE_REF	baseBranch	Target/base branch.
AGENTRIX_HEAD_REF	headRef	Observed PR/MR source branch.
AGENTRIX_HEAD_SHA	headSha	Observed PR/MR source commit.
AGENTRIX_CHECKOUT_REF	checkoutRef	Workspace initialization ref.
AGENTRIX_CHECKOUT_SHA	checkoutSha	Workspace initialization SHA.
AGENTRIX_TASK_BRANCH	branchName	Bound task branch when one exists.
AGENTRIX_TASK_BRANCH_BINDING	branchBinding	Task branch binding mode.

These worker environment values are platform task context. They override user-provided agent environment variables with the same names.

Environment variables

Variable	Used by	Description
AGENTRIX_BASE_URL	CLI, GitHub Action child process, GitLab template	Optional Agentrix API base URL override. Defaults to https://agentrix.xmz.ai; ignored when --base-url is passed.
AGENTRIX_API_KEY	CLI, GitHub Action child process, GitLab template	API key used as the bearer token. Ignored when --api-key is passed.
AGENTRIX_GIT_SERVER_ID	CI auto-detection	Git server ID for the detected repository. Defaults to github in GitHub Actions and gitlab in GitLab CI.
CI_COMMIT_REF_NAME / CI_COMMIT_SHA	GitLab CI auto-detection	Current GitLab job ref and commit. These are the only automatic sources for git.ref and git.sha.
GITHUB_REF / GITHUB_SHA	GitHub Actions auto-detection	Current GitHub job ref and commit. These are the only automatic sources for git.ref and git.sha.
GITLAB_BRIDGE_EVENT_NAME	GitLab daemon webhook detection	Normalized event name emitted by the daemon bridge.
GITLAB_BRIDGE_EVENT_ACTION	GitLab daemon webhook detection	Normalized event action emitted by the daemon bridge.
GITLAB_BRIDGE_ISSUE_NUMBER	GitLab daemon webhook detection	Issue number emitted for issue and issue comment events.
GITLAB_BRIDGE_PR_NUMBER	GitLab daemon webhook detection	Pull request number emitted for merge request and MR comment events.
GITLAB_BRIDGE_BASE_REF / GITLAB_BRIDGE_HEAD_REF / GITLAB_BRIDGE_HEAD_SHA	GitLab daemon webhook detection	Observed MR context used only when standard GitLab MR variables are unavailable.
AGENTRIX_JOB_URL	CI auto-detection	Override detected job URL.
AGENTRIX_AGENT	GitLab template	Agent ID or name.
AGENTRIX_PROMPT	GitLab template	Prompt text.
AGENTRIX_TITLE	GitLab template	Custom task title.
AGENTRIX_OUTPUT_SCHEMA	GitLab template	JSON Schema string for structured output.
AGENTRIX_REPO	GitLab template	JSON repository override.
AGENTRIX_BRANCH_NAME	CLI, GitLab template	Task branch name override. Ignored when --branch-name is passed.
AGENTRIX_RESPONSE_MODE	GitLab template	stream or async. Defaults to stream in the template.
AGENTRIX_TIMEOUT	GitLab template	HTTP read timeout; in stream mode it is also the total wait timeout, in seconds. Defaults to 30 seconds for async and 1800 seconds for stream.
AGENTRIX_CAPABILITY_PROFILE	GitLab template	Capability profile.
AGENTRIX_RUNNER_ID	GitLab template	Runner ID. Required by the template above.
AGENTRIX_RESULT_FILE	GitLab template	Result JSON file path.

agentrix-run does not infer checkout policy from issue or workflow phases. In daemon-triggered GitLab pipelines, GITLAB_BRIDGE_* supplies webhook event and observed MR context only. It never overrides the current job ref/SHA and never creates checkoutRef or checkoutSha.