Integration architecture

Axtary is not limited to applications written in TypeScript, but its current embeddable libraries are Node.js packages. Most teams should install only the CLI and run Axtary beside the agent or service. TypeScript/JavaScript teams can instead embed the SDK or compose the lower-level packages. Other languages can call the local HTTP boundary for implemented connectors, use the MCP wrapper, or put a small trusted Node sidecar in front of a custom tool.

There is no hosted execution API that receives provider credentials and calls tools for you. The enforcement process runs in your infrastructure; the hosted dashboard is an optional approval and evidence plane.

Choose the smallest integration

If you are evaluating Axtary, use the CLI row. It installs one executable and brings the other eight runtime packages as dependencies. Do not install all nine packages individually unless you are building a custom host.

What runs where

agent or service
      |
      | hook, MCP, SDK call, or loopback HTTP JSON
      v
customer-operated enforcement process
  normalize -> policy -> exact approval? -> ActionPass -> ledger -> adapter
      |                                                        |
      | optional approval request / redacted evidence          | provider credential
      v                                                        v
hosted dashboard                                          GitHub / Slack /
(people and proof only)                                   Linear / Jira / …

The enforcement process owns the hot path and provider credentials. The dashboard cannot execute provider actions. Two optional bridges connect the planes:

• A hosted step-up request sends the exact normalized payload and hashes so a human can review that content. Do not enable this bridge for payloads your policy forbids sending to the hosted reviewer.
• Ledger sync sends a verified, redacted evidence projection. It excludes provider credentials, auth headers, raw responses, private signing keys, agent prompts, and payload bodies.

Local policy, execution, and ledger verification work without a hosted account. Hosted approval is deliberately in the path only for actions whose policy decision is step_up; routine local allows do not wait on the cloud.

TypeScript, JavaScript, and other languages

The published @axtary/*@0.4.0 packages are ESM Node.js packages supporting Node ^20.19.0, ^22.13.0, or >=24.

• CLI users write no TypeScript. The axtary executable runs the local proxy, hooks, MCP wrapper, connectors, policy checks, and evidence commands.
• JavaScript and TypeScript use the same SDK. Type declarations ship with every package; TypeScript is optional.
• Other languages use a process boundary today. Use MCP or loopback HTTP JSON, or run a small Node sidecar that owns the Axtary handler. Axtary does not currently publish maintained Python, Go, Java, or Rust SDKs.
• The hosted dashboard is not the language-neutral execution API. It coordinates people and evidence and never receives provider credentials.

The local proxy intentionally rejects non-loopback bind addresses because its HTTP boundary has no general-purpose network authentication. Keep it on the same machine, runner, or Kubernetes pod as the caller. A shared cross-host proxy, public ingress, or central unauthenticated 0.0.0.0:7331 deployment is not a supported topology.

The local HTTP JSON boundary

Start the proxy:

axtary proxy --config axtary.yml

It listens on 127.0.0.1:7331 by default and exposes two action endpoints:

Both accept the public normalized action shape:

{
  "schemaVersion": "axtary.action.v0",
  "actor": {
    "agentId": "agent:design-partner",
    "humanOwner": "user:operator@example.com",
    "runtime": "internal-service",
    "tenant": "org:local"
  },
  "intent": {
    "taskId": "INC-418",
    "declaredGoal": "Search the approved runbook before remediation"
  },
  "capability": {
    "tool": "docs.documents.search",
    "resource": "docs:local",
    "payload": {
      "workspace": "local",
      "query": "database failover",
      "maxResults": 5
    }
  }
}

For a decision-only probe from any language:

curl --fail-with-body http://127.0.0.1:7331/authorize \
  --header 'content-type: application/json' \
  --data-binary @action.json

Read status, decision.decision, decision.reasons, explanation, and ledger.record.payloadHash from the response. For an allow, actionPass.claims.payloadHash must match that ledger hash. The proxy stamps the configured tenant onto the normalized action rather than trusting a caller-supplied tenant label. A successful HTTP status does not mean the action was allowed: policy denials and step-ups are valid decision responses.

POST /authorize cannot stop a caller that ignores its response and still uses a provider credential. For a real security boundary, keep credentials in the Axtary adapter/sidecar and use /actions, or verify the ActionPass again in the trusted component that performs the side effect. Never give the provider credential to the agent and call /authorize only as advisory logging.

Where the nine packages fit

The packages are composable implementation layers, not nine installation steps:

The usual execution spine is:

config -> policy -> approval evidence -> ActionPass -> proxy -> adapter
                    \________________ ledger evidence ________________/

MCP adds tool-definition identity before policy.
CLI assembles and operates the entire spine.

Deployment patterns for an existing company

Developer workstation

Install the CLI globally, commit axtary.yml and the generated hook config, keep .axtary/ runtime state ignored, and start one proxy per protected workspace. This is the quickest design-partner path.

CI or self-hosted automation runner

Install the CLI in the runner image or invoke it with npx. Inject only the named credential environment variables from Vault, 1Password, Doppler, SOPS, or the runner's secret store. Run doctor connectors before protected work and export/attest the ledger as a job artifact. Do not print the environment.

Kubernetes workload

The current safe shape is a same-pod sidecar or companion process sharing the pod network namespace and a private ledger volume. The application talks to loopback; the Axtary process owns provider credentials. This describes how the current boundary composes with Kubernetes—it is not a claim that Axtary ships a Helm chart, operator, or managed cluster ingress today.

Existing Node service

Use @axtary/actionpass when the service already owns and can protect the tool execution boundary. Use @axtary/proxy plus registered handlers when you need configurable policy, durable ledger state, budgets, or hosted approval resolution. Use the CLI instead if the standard connectors are sufficient.

Existing non-Node service

For an implemented connector, keep the Axtary CLI proxy beside the service and send normalized actions to /actions. For a custom internal API, expose the operation as MCP and wrap it, or add a small trusted Node host using @axtary/proxy. A language-specific SDK can be added with a design partner, but it is not already shipped.

A design-partner integration sequence

1. Pick one non-production action with a clear resource and payload.
2. Decide the boundary: hook, MCP, implemented connector via /actions, or in-process SDK.
3. Install the CLI unless a custom Node host is genuinely necessary.
4. Start in credential-free demo mode and write policy fixtures for allow, deny, and step-up.
5. Put the real credential in the local broker or the existing secret manager; keep only the environment-variable name in config.
6. Run doctor connectors and a read/auth-only smoke check.
7. Exercise the non-production action, then attest and independently verify the ledger.
8. Add hosted approval only if a remote human must inspect the exact payload; add hosted sync only if the team wants shared evidence.
9. Expand to another action only after the first boundary, policy, failure mode, and evidence are understood.

Next: run the Quickstart, choose a supported agent boundary, or embed the TypeScript/JavaScript SDK. Credential placement is covered in Credentials and connecting.