Skip to content
openagentix openagentix docs

Getting started

There are two ways in. The local CLI works today and runs an agent definition against an event on your machine, with the same parser, policy gate, budgets and audit chain as the platform. The Docker Compose setup starts the whole platform (API, worker, console, PostgreSQL) and arrives with the 0.1 release.

Run an agent locally

Section titled “Run an agent locally”

  1. Clone the platform repository and install dependencies (Node.js 22 LTS, pnpm):

    Terminal window
    git clone https://github.com/open-agentix/open-agentix.git
    cd open-agentix
    pnpm install --frozen-lockfile
    pnpm build

  2. Make the CLI available as oax and validate the bundled example pipeline:

    Terminal window
    alias oax="node $PWD/packages/runners/dist/cli.js"
    oax validate examples/cve-triage.agents.md
    # valid: cve-triage@<version>

  3. Run it against a recorded event. The example uses the deterministic simulated provider and built-in demo MCP servers, so it needs no API keys and makes no outbound calls:

    Terminal window
    oax run examples/cve-triage.agents.md --event examples/events/trivy-finding.json

    The summary shows the result, the steps, tokens and cost, and the verified audit chain:

    status=succeeded steps=… toolCalls=… tokens=…/… cost=$0.000000
    audit: valid (… entries, head 3f9a0c…)

  4. Try the guardrails. Run the ticket example, which needs a human approval, and answer it:

    Terminal window
    oax run examples/ticket-updater.agents.md \
      --event examples/events/jira-issue.json --approve all

    Without --approve all the approval is rejected and the agent stops.

Add --json to get every step as a JSON line. See the CLI reference for all options.

Use a real model

Section titled “Use a real model”

Configure providers with OAX_PROVIDERS (a JSON array) or --providers <file>, and keep keys out of files: secrets are resolved by name from OAX_SECRET_<NAME> or from files in OAX_SECRETS_DIR.

Terminal window
export OAX_SECRET_OPENAI_KEY=sk-...
export OAX_PROVIDERS='[{"kind":"openai","name":"openai","baseUrl":"https://api.openai.com/v1","apiKeySecret":"openai.key"}]'

Then set provider: openai and a model in your agent. See Providers.

Run the platform with Docker Compose

Section titled “Run the platform with Docker Compose”

The Compose setup will start PostgreSQL 16, the API (control node), a worker and the console:

Terminal window
git clone https://github.com/open-agentix/open-agentix.git
cd open-agentix
cp .env.example .env        # set the admin bootstrap password and secrets
docker compose up -d

You will then send a signed webhook to start a run and follow it in the console, step by step.

Next steps

Section titled “Next steps”