⌕

Quickstart

From nothing to watching Axtary block an agent's unsafe action — under ten minutes, no credentials required. Everything starts in deterministic fake mode, so there's nothing to sign up for and no token to paste.

1. Install

npm install -g @axtary/cli

This installs the current published release (@axtary/*@0.3.0) from npm. It is an early 0.x line — the runtime path is real and tested, but the API may change between minor versions. To hack on Axtary itself, you can also run from source:

git clone <repo-url> axtary && cd axtary
npm install && npm run build:cli
alias axtary="node $PWD/packages/cli/dist/bin.js"

2. Scaffold and check

mkdir my-protected-project && cd my-protected-project
axtary init
axtary doctor connectors --config axtary.yml

init writes a starter axtary.yml (fake GitHub/Slack/Linear adapters — no tokens) and a policy that denies .env*/secrets/ reads, requires step-up approval for auth/, billing/, infra/prod/ writes, and allowlists #axtary-dev for Slack. doctor shows what each connector needs before you ever switch one to real mode.

If you already know the scope you want, start from a reusable template instead:

axtary init --template repo-only-coding
axtary policy test .axtary/policy-tests/repo-only-coding.policies.test.yml --config axtary.yml
axtary demo --config axtary.yml --template repo-only-coding

Templates are repo-only-coding, staging-reads, incident-investigation, ticket-updates, doc-search, and guarded-prod. The generated policy test and demo --template are policy-only proofs with representative allow/deny cases; they do not call live providers.

3. See the loop end to end

axtary demo --config axtary.yml

Safe and unsafe GitHub/Slack/Linear/MCP actions run through policy → ActionPass signing → proxy → fake adapters → the hash-chained ledger at .axtary/actions.jsonl. You'll see allows, denies, and step-ups, each with a reason.

To watch a step-up actually execute, re-run with --approve-step-up: it attaches a local exact-payload approval (the same artifact shape a human approval produces), so the step-up actions run and each execution record carries the approved/executed payload-hash pair. axtary prove-equivalence then proves approved == executed for those records.

If you want these decisions in an existing trace collector, keep going with the core loop first, then add OpenTelemetry export. It is opt-in and exports hashes, decisions, reasons, and audit dimensions — not payload bodies or secrets.

4. First blocked action

Start the enforcement point (leave it running):

axtary proxy --config axtary.yml

In another terminal, simulate a coding agent trying to read a secret:

echo '{"cwd":"'$PWD'","tool_name":"Read","tool_input":{"file_path":"'$PWD'/.env.production"}}' \
  | axtary hook claude-code

You'll get a deny with the blocked path prefixes named, and the decision is written to the ledger.

Why does a local file read show up as github.contents.read? Axtary normalizes every tool call to a provider-neutral action shape so one policy covers file reads, PR creates, and Slack posts alike. The github. prefix is the content namespace, not a network call to GitHub.

5. Gate a real agent

  • Claude Code: add the PreToolUse hook to your project's .claude/settings.json, then ask Claude Code to read .env.production — it gets denied and self-corrects.
  • Any MCP agent: run axtary mcp serve and point Claude Code / Cursor / Codex at it.

What you just proved

In under ten minutes, with no credentials, you saw the core loop: an agent's action was turned into a normalized action, judged by deterministic policy before it ran, blocked when it tried to read a secret, and written to a tamper-evident ledger with a reason. Real connectors use the same authorization and ledger path, then add provider setup, readiness checks, and live provider execution.

Where to go next