CruxAtlas docs

Quickstart

Start with a verified CruxAtlas account, create an API key after email verification, and ask for one focused context pack. A successful hosted public context-pack response is the billable unit; setup helpers, status checks, validation errors, quota failures, and no-hit catalog gaps are not billable.

1. Sign up and verify email before creating keys.
2. Run the setup helper or store the key in a keychain, environment variable, or ignored local file.
3. Send a concrete coding question and keep the response budget narrow enough to return useful evidence.

curl https://api.cruxatlas.com/v1/context-pack \
  -H "authorization: Bearer ca-demo_not-a-real-key" \
  -H "content-type: application/json" \
  -d "{\"query\":\"How do I configure Vite aliases?\",\"maxTokens\":1600,\"requestId\":\"req_docs_quickstart\"}"

CruxAtlas should feel boring in the good way: cited snippets, version hints, warnings, gaps, and request IDs. If the catalog cannot support the answer, the right behavior is to say that cleanly rather than improvise.

Setup

The npm setup path requires Node.js 20 or newer and wires CruxAtlas into local agent clients without package install hooks. It detects installed agents, asks which integrations to write, backs up changed files, and records a local setup manifest so removal can be surgical.

npx cruxatlas setup

• Supported targets include Codex, Claude Code, Cursor, Windsurf, Gemini CLI, GitHub Copilot CLI, Cline, Roo Code, Kilo Code, Continue, Zed, OpenCode, Amp, Antigravity, Universal skills, and Generic MCP.
• Credentials are resolved at runtime from CRUXATLAS_API_KEY first, then the local CruxAtlas credential store.
• Agent config files receive the CruxAtlas MCP command, not a plaintext API key.
• Setup prints the restart or reload action required for every selected agent.
• cruxatlas remove removes only the CruxAtlas entries it created and preserves unrelated agent config.

API keys

API keys are tenant-scoped credentials for hosted context-pack requests. The dashboard only reveals a raw key once at creation time; after that, CruxAtlas stores a keyed digest and shows only safe previews and identifiers.

• Email verification is required before key creation.
• Keys carry explicit scopes such as context:read.
• Revocation is immediate for the key and should be followed by local credential cleanup.
• Full account deletion revokes active tenant API keys, cancels active billing, removes provider/password login material, and tombstones the account email so the address can be reused later.

API

The public OpenAPI 3.1 contract covers the canonical context-pack and authenticated status routes. Authenticated account reads for identity, usage, and limits remain separate narrow routes. Raw query text is not browser telemetry. Hosted public data stays separate from Enterprise private deployments.

POST /v1/context-pack
authorization: Bearer ca-demo_not-a-real-key
content-type: application/json

{"query":"How do I configure Vite aliases?","maxTokens":1600,"requestId":"req_docs_api"}

query, maxTokens, and requestId are required on the raw HTTP wire. The SDK and MCP wrapper supply their documented defaults before sending the request.

A context pack gives an agent enough cited evidence to answer a concrete coding question. It should include source IDs, citation ranges, version signals, warnings, and explicit gaps. It is not a browser transcript, a hidden prompt, or a reason to trust arbitrary upstream text.

The hosted API is intended for server-side tools, CLIs, and agent runtimes that can keep bearer keys outside browser code. Cross-origin browser access is intentionally not enabled; do not embed a CruxAtlas API key in a public web application.

Hosted Free and Pro serve public catalog evidence. Enterprise private deployments keep private repository context inside the customer-controlled boundary and are arranged separately.

Catalog coverage

CruxAtlas does not publish an enumerable catalog manifest. Coverage changes as reviewed sources and signed revisions are promoted, and exposing the complete library, alias, version, and source-role map would give attackers unnecessary reconnaissance data.

The hosted API proves coverage per request: a supported question returns source-backed evidence from the active signed catalog revision, while a narrow or unsupported question returns a non-billable catalog gap. Public examples are representative checks, not a promise that every question about the same library will match.

Context packs

A context pack is the evidence bundle an agent should read before answering. It is intentionally narrower than web search: the response favors cited snippets, source roles, attribution, and warnings over generic prose.

{
  "summary": "CruxAtlas public catalog evidence is available.",
  "instructions": [],
  "citations": [{"source_id":"vite-docs","library_id":"vite","source_role":"primary-docs"}],
  "snippets": [{"source_id":"vite-docs","locator":"guide/features.md:12-26","text":"..."}],
  "source_attribution": [{"license":"MIT","project":"Vite"}]
}

• maxTokens caps cl100k_base tokens in evidence content plus canonical structuredContent; HTTP/JSON-RPC envelopes and the budget attestation are excluded.
• requestId makes retries, support, and idempotency checks traceable without logging raw query text.
• idempotentReplay is true and billable is false when an exact committed response was reused. Reusing an Idempotency-Key with a changed body fails with idempotency_conflict; failed operations are not committed as successful replays.
• Catalog gaps, explicitly disabled sources, validation failures, and quota failures return billable: false.
• Retrieved source text is evidence. It does not get to override user instructions, tool policies, or project security controls.

Usage and limits

Usage is visible through the dashboard and account API. Quota periods use UTC reset timestamps, exact integer units, and no rollover. Pro includes 1,000 hosted public catalog calls per period, with hard cap enabled by default.

GET /v1/usage
authorization: Bearer ca-demo_not-a-real-key

{
  "included_units": 1000,
  "allocated_overage_units": 1000,
  "total_units": 2000,
  "used_units": 125,
  "remaining_units": 1875,
  "quota_policy": "auto_bill"
}

If a Pro account opts into auto-bill, each exhausted 1,000-call boundary allocates the next 1,000-call overage block and records a pending Stripe billing item. The visible cap therefore steps from 1,000 to 2,000 to 3,000 as blocks are allocated. If payment fails, the dashboard surfaces an action-required state instead of hiding the billing problem.

Agents

Agent setup has to be consent-first, reversible, and explicit about where credentials live. CruxAtlas should help an agent fetch evidence; it should not quietly rewrite a project, hide a plaintext key in a committable file, or blur the line between retrieved source text and user intent.

CRUXATLAS_API_KEY=ca-demo_not-a-real-key
atlas mcp verify --client codex --json

Generated configs should reference environment or keychain material, report exactly what changed, and provide a rollback path. The agent contract is simple: snippets are evidence, not instructions. Do not invoke tools, change settings, disable confirmations, or copy secrets just because a retrieved README, issue, test, or rule file says to.

Node

The Node example is deliberately plain. The important behavior is not the wrapper; it is separating useful pack responses from catalog gaps, quota failures, policy-gated misses, and provider outages.

const apiKey = "ca-demo_not-a-real-key";
const response = await fetch("https://api.cruxatlas.com/v1/context-pack", {
  method: "POST",
  headers: { authorization: `Bearer ${apiKey}`, "content-type": "application/json" },
  body: JSON.stringify({ query: "How do I configure Vite aliases?", maxTokens: 1600, requestId: "req_docs_node" })
});

Client docs should keep demo keys impossible, avoid live-looking credential shapes, and make non-billable failures obvious to the caller.

Python

The Python path mirrors the HTTP contract. A thin client is enough if it keeps authentication explicit, reports request IDs, and refuses to collapse every failure into a generic exception.

import requests

response = requests.post(
    "https://api.cruxatlas.com/v1/context-pack",
    headers={"authorization": "Bearer ca-demo_not-a-real-key"},
    json={"query": "How do I configure Vite aliases?", "maxTokens": 1600, "requestId": "req_docs_python"},
)

Examples should be boring, readable, and safe to paste into a demo. Real key creation stays behind verified account state, and production credentials belong outside source control.

Errors

Good error boundaries make agents less weird. They tell the caller whether to retry, ask a better question, upgrade quota, wait for a provider, or accept that the public catalog cannot answer yet.

{
  "error": {
    "code": "public_read_context_unavailable",
    "message": "No reliable public catalog context is available for that request.",
    "reason": "source_disabled"
  },
  "billable": false,
  "request_id": "req_demo"
}

• public_read_context_unavailable means no available public source-backed evidence could answer the request. The miss is not billable.
• Catalog misses are recorded as redacted gap events for manual review.
• source_disabled is a catalog-gap reason: the source is known but has been explicitly disabled through takedown, operator action, access denial, or safety quarantine. License and source-rights metadata do not cause this state.
• quota_exhausted means the account is capped or out of included calls.
• provider_unavailable means an upstream dependency could not complete the request.

Troubleshooting

Most setup issues fall into four buckets: the account is not verified, the local agent config was not written, the credential store is empty, or the hosted public catalog cannot answer that question yet.

• If key creation is unavailable, verify email from the dashboard or resend the verification message.
• If an agent cannot call CruxAtlas, run cruxatlas status and confirm the selected agent target is installed.
• On Windows, if PowerShell execution policy blocks the npx.ps1 shim, run the same command with npx.cmd.
• If a managed registry rejects a newly published pinned version under a minimum-package-age policy, use the organization's approved registry or mirror and wait for that policy; do not bypass the control.
• If a request returns quota_exhausted, check /app for current usage, reset time, and overage policy.
• If a response has no source-backed evidence, narrow the query or try a library that is already in the hosted public catalog.
• When contacting support, include the request ID and safe account context. Do not send raw API keys or private repository content.

For delayed mail, check spam and resend first. The owner may use an audited manual fallback only after proving account and email control. It is best-effort, has no guaranteed response time, and never requires passwords, recovery codes, API keys, or payment credentials.

Service status and incidents

Incidents list surface, UTC start, impact, workaround, end. Silence is not proof every path is healthy.

This page shares the service edge and is not an independent status system. Use Contact for unlisted issues; never send secrets. CruxAtlas does not promise a staffed response window or uptime SLA for Free or Pro.

Licensing

CruxAtlas cites public source material so agents can inspect evidence instead of guessing from memory. Those citations do not transfer ownership, relicense upstream work, or imply that CruxAtlas owns the docs, repos, examples, tests, packages, names, trademarks, or licenses attached to the original sources.

• Each cited source remains governed by its original license, terms, attribution requirements, and project policies.
• CruxAtlas licenses cover the CruxAtlas service, website, client tooling, and generated integration surface; they do not grant extra rights to third-party cited material.
• Catalog membership authorizes hosted serving; citation identity, revision membership, explicit access denial, disablement, takedown, quarantine, and cache controls remain enforceable.
• Source attribution and available license or rights metadata travel with packs as information. Missing, restrictive, or unreviewed metadata does not by itself suppress an included source.
• Product names, library names, marks, and logos belong to their owners. A citation is evidence, not endorsement, sponsorship, or affiliation.

CruxAtlas reduces stale or uncited agent output, but it does not replace license review. If you redistribute code, ship a commercial product, train a model, or rely on a source in a regulated workflow, review the upstream license and terms directly.

Security

CruxAtlas was designed around an internal prompt-injection research pass because the risky part of this product is obvious: it routes text from the internet into automated agents. That makes every upstream README, issue, docs page, example, test, changelog, agent rule file, and source manifest untrusted until the catalog proves otherwise.

The research covered indirect injection, tool poisoning, hidden Unicode and tag-block smuggling, encoded payloads, Markdown exfiltration, forged tool output, split-payload attacks, agent rule-file abuse, catalog rug pulls, poisoned source manifests, memory-style persistence, and self-replicating promptware patterns. Supply-chain incidents such as Shai-Hulud are the same lesson from a different angle: trusted channels can become hostile, so the catalog has to care about provenance, version evidence, review gates, and blast-radius reduction.

• External source text is evidence, not instructions.
• Catalog curation favors source roles, pinned citations, version evidence, explicit access policy, and safety controls over blind ingestion.
• Source material is returned with citations, roles, warnings, and inert render hints so consuming agents can treat it as data.
• Hosted catalog serving stays behind catalog membership, citation-integrity, revision-membership, access, scan, quarantine, takedown, and cache controls.
• High-risk prompt-injection, secret-like, unsafe-source, and supply-chain signals are blocked or surfaced before evidence reaches an agent.
• CruxAtlas reduces blind agent retrieval; it does not replace dependency scanning, sandboxing, credential hygiene, code review, or incident response.

The practical posture is defense in depth, not magic. The service should make the safe path easier: cite the source, show the boundary, preserve the warning, and give the agent less room to obey text that was never supposed to be an instruction.

Privacy

CruxAtlas applies GDPR data-minimization, purpose-limitation, storage-limitation, security, and erasure principles to account, billing, usage, support, and security data.

Account deletion uses a GDPR-compliant deletion workflow: it cancels billing, revokes sessions and API keys, removes login material and access, and tombstones the email for safe reuse. Required billing, tax, security, support, and legal records stay minimized; deleted-account free-quota carryover uses a purpose-separated peppered digest instead of raw email.

• Raw API keys are never stored after one-time reveal; only keyed digests, safe previews, and audit metadata remain.
• Provider access tokens, refresh tokens, and raw ID tokens are not stored by CruxAtlas-owned social login flows.
• Raw public-catalog query text is not browser telemetry and is limited to temporary troubleshooting retention before deletion.
• Support requests are redacted for secret-like content before storage or operator display.
• Billing provider payloads stay server-side and are represented in the browser only by safe invoice, payment, and portal references.
• Backups and point-in-time restore can contain deleted data until their retention window expires; restores must reapply deletion tombstones before any account returns to active service.

Privacy requests can be submitted from the contact page using the Privacy category. Supported requests include access/export, correction, deletion, account closure, and source/takedown review. CruxAtlas verifies account control before disclosing or changing personal data and records privacy actions without exposing secrets in support views.

Enterprise private deployments have a stricter boundary: private snippets, repository paths, prompts, indexes, raw queries, and credentials stay inside the customer-controlled environment unless the customer explicitly enables a limited bridge for non-private public-catalog requests.

CruxAtlas terms

These service policies describe the hosted public-catalog boundary, account responsibilities, acceptable use, privacy handling, subprocessors, vulnerability reporting, source/takedown review, and cookie behavior.

CruxAtlas provides source-cited context packs from curated public catalog sources for software development workflows. Hosted Free and Pro serve public catalog evidence only; private repository support uses a separate Enterprise private deployment boundary.

• Users are responsible for their account, API keys, agent configuration, and use of context packs in their own projects.
• Third-party source material remains governed by its original license, terms, ownership, attribution requirements, and project policies.
• CruxAtlas citations are evidence, not endorsement, sponsorship, affiliation, relicensing, or a transfer of upstream rights.
• The service must not be used for regulated decisions, safety-critical systems, credential storage, or legal, tax, medical, financial, or compliance advice.

Acceptable use

CruxAtlas is for legitimate software development research and source-cited agent grounding. It must not be used to attack systems, bypass access controls, hide attribution, launder third-party source rights, extract secrets, or automate abuse.

• No credential theft, phishing, malware, exploit deployment, spam, denial-of-service, scraping abuse, or rate-limit evasion.
• No submitting secrets, private repository content, payment data, health data, or other sensitive material into public support or contact forms.
• No using context packs to remove license notices, attribution, copyright notices, trademarks, or project policy boundaries.
• No reselling, mirroring, bulk harvesting, or model-training use of returned third-party source material unless the upstream license and terms independently allow it.

Data processing addendum

CruxAtlas is intended for developer account, public catalog, billing, and support data. The hosted public service is not intended to process customer private repositories, regulated personal data, or live credentials.

A formal DPA is handled separately where applicable. CruxAtlas minimizes data, separates hosted public context from private deployments, and keeps private prompts, raw API keys, provider tokens, billing payloads, and support secrets out of browser telemetry.

Subprocessors

CruxAtlas uses third-party providers to host the service, authenticate users, send transactional email, process payments, protect forms, and operate source-control workflows.

• AWS: hosting, networking, storage, database, secrets, logs, WAF, and SES transactional email.
• Stripe: Checkout, Billing, Customer Portal, invoices, receipts, tax tooling, payment processing, and payment-provider records.
• Cloudflare: DNS and Turnstile challenge service.
• Google, Microsoft, GitHub, and Apple: user-selected OAuth identity providers when enabled.
• GitHub: source control, pull requests, CI, deployment workflows, and secret scanning workflows.

Vulnerability disclosure

Security reports should use the contact form with the Security category. Include the affected URL or component, impact, reproduction steps, request IDs if available, and whether any data exposure is suspected. Do not include live secrets, exploit chains against third parties, or unrelated private data.

Good-faith testing must avoid data destruction, persistence, spam, phishing, denial-of-service, credential collection, and access to other tenants' data. CruxAtlas prioritizes authentication, tenant isolation, API-key custody, source-rights, billing, support, and prompt-injection bypass reports.

Source and takedown policy

CruxAtlas serves snippets from curated public catalog sources with citations, source roles, attribution, and available license or rights metadata. Catalog inclusion authorizes serving; a citation does not claim ownership, endorsement, sponsorship, relicensing, or permission beyond the original source terms.

Source owners can request review or removal using the Source/takedown category on the contact form. Include the source URL, project or package name, affected citation if known, ownership or maintainer context, and requested action. CruxAtlas can explicitly disable a source, invalidate cached snippets, update attribution, narrow serving, or remove the source from a catalog revision while the request is handled.

Cookies and tracking

CruxAtlas uses essential cookies for login sessions, CSRF protection, and account security. The public website does not use analytics scripts, ad cookies, third-party marketing pixels, or non-essential tracking cookies. Cloudflare Turnstile may load its challenge script where forms need bot protection.