Install & get started

VectorCourt gives an independent adversarial verdict on a hard decision. It is HTTP-first — there is no SDK and no binary to install. You send a question, wait, and read back a structured verdict. This page sets that up for your agents and for you.

1 — Get an API key

The vc-ask.sh helper requires a key for unattended use, and paid API access starts at Pro. The API also offers a guarded anonymous free tier for eligible consultations; the helper intentionally uses authenticated access. Buy a key, and it is delivered to you after checkout.

See pricing & buy a key →

Place the key where the helper and your agents can find it — either an environment variable or a key file:

# option A: environment variable
export VC_KEY="vc_your_key_here"

# option B: key file (zero-config — no export needed)
mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/vectorcourt"
printf '%s' "vc_your_key_here" > "${XDG_CONFIG_HOME:-$HOME/.config}/vectorcourt/adm.key"
chmod 600 "${XDG_CONFIG_HOME:-$HOME/.config}/vectorcourt/adm.key"

The key is sent only as the X-VC-Key request header. Never commit it or paste it into a prompt.

2 — For operators: the vc-ask.sh helper

One script files a question and immediately returns a durable collection handle. A later one-shot collection prints the verdict when it is ready.

Commands checked explicitly by vc-ask.sh: curl, jq, awk, stat, mktemp, cat, dd, wc. jq is a hard vc-ask.sh runtime dependency, not merely an example parser.

The Bash helper also assumes the standard POSIX utilities od, tr, mkdir, rmdir, sleep, chmod, rm, and mv; it does not require Perl or another helper interpreter.

It resolves credentials in this exact order: VC_KEY, then VECTORCOURT_API_KEY, then the file named by VC_KEY_FILE, then ${XDG_CONFIG_HOME:-$HOME/.config}/vectorcourt/adm.key, then ${XDG_CONFIG_HOME:-$HOME/.config}/vectorcourt/api.key, then the legacy ~/.vectorcourt/api.key file.

# hard helper dependency: jq
brew install jq          # macOS    (or: apt-get install jq)

# get the helper
curl -q -g -fsSL -o vc-ask.sh -- https://vectorcourt.com/static/vc-ask.sh
chmod +x vc-ask.sh

# ask a question
bash ./vc-ask.sh --question "Should a 15-person startup build its own auth or use Auth0/Clerk? Argue both sides."

# or file a longer, structured prompt from a file
bash ./vc-ask.sh --file /tmp/decision.txt

# later: use submission_id from the JSON receipt; this checks once and never sleeps
bash ./vc-ask.sh --collect --submission-id "$SUBMISSION_ID"

# only after an outcome-unknown submit: recover by its printed idempotency handle
bash ./vc-ask.sh --collect --idempotency-key "$IDEMPOTENCY_KEY"

An accepted submission prints JSON with its IDs, verdict URL, and exact collect_command. Emitted commands contain the resolved absolute Bash and script paths, so they remain usable after a directory change. If submit acceptance is uncertain, the client preserves the same idempotency handle and prints a read-only recovery command; never file the question again to recover it. Collection exits 4 while work is pending, 6 when grounded clarification answers are required, and 0 when finalized. Long polling remains available only through explicit --wait.

3 — For agents: install the skill (ANCC)

Agent runtimes that follow the ANCC skill convention can install VectorCourt as a skill. The skill is a thin wrapper over the same vc-ask.sh helper: the agent files a question, retains the returned collection handle, and checks later for the verdict and recommended next action. By default, no single invocation waits through deliberation; --wait is an explicit opt-in.

Drop the helper into the runtime's skill directory and reference it from your agent's skill manifest:

# fetch the helper into your agent's tools/skill directory
curl -q -g -fsSL -o vc-ask.sh -- https://vectorcourt.com/static/vc-ask.sh
chmod +x vc-ask.sh
# the agent calls: ./vc-ask.sh --file prompt.txt
# then runs the emitted collect_command when it is ready to check once

The machine contract — request body, polling, clarification round-trip, and signed webhook callbacks — is documented on the agentic API page. The discovery document is at /openapi.json.

4 — Read the verdict: act on the outcome

A verdict is not always "the answer." Sometimes the most valuable thing the court returns is that you asked the wrong question — because correctly answering the wrong question is the catastrophe. When the deliberation surfaces a strong counter-signal, the verdict carries a prominent North Star block right after the decision: the answer to what you asked, and the direction worth choosing next, with proof. Most verdicts show none — its presence is the signal worth reading.

After a finalized verdict the helper also prints a SIGNALS: line whose next_action field tells you — or your agent — what to do next. You do not have to interpret the internals yourself.

SIGNALS: next_action=reframe_question quorum=FULL_QUORUM quality=low verdict_status=insufficient confidence=0.42

What VectorCourt is NOT

It does not execute the chosen path or change your infrastructure. It does not replace factual lookup or your own go/no-go. It is not for low-stakes choices where the delay and cost outweigh the value. It does not guarantee unanimity — dissent and reversal conditions are part of every verdict.