From ariadne-core
Set up and connect Ariadne Core. Triggers: deploy ariadne, set up ariadne core, connect ariadne core, install the CLI, troubleshoot connection.
How this skill is triggered — by the user, by Claude, or both
Slash command
/ariadne-core:ariadne-core-installThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Use this skill when the user wants to deploy Ariadne Core to Railway or another host, connect their CLI / agent to an existing deployment, troubleshoot a connection, or update a deployment.
Use this skill when the user wants to deploy Ariadne Core to Railway or another host, connect their CLI / agent to an existing deployment, troubleshoot a connection, or update a deployment.
This skill has two modes:
This skill requires terminal access — ariadne CLI is a Python package and ariadne login runs a local OAuth loopback flow. Claude Code, Cursor, Cline, OpenClaw, Open Brain, and any other agent with Bash/shell tool access can drive this autonomously. For the visual onboarding walkthrough in Cowork, use the ariadne-core-walkthrough skill instead.
Before proceeding, determine who you're helping:
AI agent executing autonomously — another LLM or automated system that needs exact commands, verification checks, and error handling. Use the AI path sections. Be terse. No explanations unless something fails.
Human following along — a person at a keyboard. Use the Human path sections. Explain what each step does. Offer to hand off to the ariadne-core-walkthrough skill if they want the full visual walkthrough with illustrations.
If unclear, ask: "Are you setting this up yourself, or should I run the commands?"
A document extraction and retrieval pipeline plus an agent-memory substrate (bw working memory + pgvector semantic recall). Converts documents (PDF, DOCX, PPTX, XLSX, HTML, 20+ formats) into clean Markdown and vector embeddings. Exposes them via a REST API over HTTPS.
Railway / Fly.io / VPS
┌─────────────────────────┐
│ ariadne-core │
│ ├── REST API (/api/*) │
│ ├── Postgres + pgvec │
│ └── Pipeline │
└─────────────────────────┘
REST API + `ariadne` CLI
▲ ▲ ▲ ▲
│ │ │ └── Claude Cowork
│ │ └────── OpenClaw / Open Brain
│ └────────── Cursor / Cline / other agents
└────────────── Claude Code
Authentication is OAuth 2.1 Bearer JWT (Auth0). The `ariadne login` CLI runs
the PKCE flow and stores tokens in the OS keyring. Clients can also discover
the Auth0 config via `GET /.well-known/ariadne-config` and run the flow
themselves.
Runs as a hosted service. All endpoints except /api/health and /.well-known/ariadne-config require an Authorization: Bearer <jwt> header.
The user wants to stand up their OWN Ariadne Core deployment on Railway (or another host).
Run the setup script for a guided terminal experience. It handles provider selection, API keys, model discovery, .env configuration, and Railway deployment via API — no Railway CLI needed:
python scripts/setup.py
The script deploys using Railway's GraphQL API with a Railway API token. Users create a token at https://railway.com/account/tokens.
Copy this URL and paste it into your browser:
https://railway.com/deploy/ariadne-core
Fill in your EMBEDDING_API_KEY and VISION_API_KEY (same key if using one provider). Everything else has defaults.
Don't have a Railway account? Sign up at: https://railway.com?referralCode=RxMpbX ($20 in free credits, no commitment).
After the user says the deploy is done, ask them:
"What's the public URL Railway gave you? It looks like something.up.railway.app. You can find it in the Railway dashboard — click on the ariadne-core service, go to Settings, scroll to Networking, and copy the Public Domain URL."
Once you have the URL, verify it's healthy:
curl -s https://THE-URL/api/health
# Expected: {"status": "healthy"}
curl -s https://THE-URL/.well-known/ariadne-config
# Expected: JSON with AUTH0_DOMAIN, AUTH0_CLIENT_ID, AUTH0_AUDIENCE
If /.well-known/ariadne-config returns 500 auth_misconfigured, the deploy is missing one of AUTH0_DOMAIN / AUTH0_CLIENT_ID / AUTH0_AUDIENCE — set those in Railway variables and redeploy.
The setup script uses Railway's GraphQL API (https://backboard.railway.com/graphql/v2) to deploy the published ariadne-core template. No Railway CLI is needed. The script needs a Railway API token — users create one at https://railway.com/account/tokens.
Before running the setup script, do a quick model freshness check — read defaults from python scripts/setup.py --help, check the provider's model page for newer models in the same class, suggest updates. Pass overrides via --embedding-model and --vision-model.
Model documentation pages:
https://ai.google.dev/gemini-api/docs/modelshttps://developers.openai.com/api/docs/modelshttps://docs.together.ai/docs/inference-modelsNever read, cat, copy, or display .env files — you don't handle API keys.
Point them at the setup script (python scripts/setup.py) first — it handles everything interactively. If they want the full visual walkthrough, hand off to the ariadne-core-walkthrough skill. If they prefer the one-click deploy button, point them at the alternative above.
See the ariadne-core-deploy skill for Fly.io and VPS instructions.
The user already has a URL (someone else's hosted instance, or their own from Path 1). They want to install the CLI and authenticate so their agents can drive Ariadne.
# 1. Install the Python client from PyPI
pip install ariadne-core-client
# 2. Authenticate — opens a browser for Auth0 OAuth via Google
ariadne login --host https://THE-URL
# 3. Verify auth landed
ariadne whoami
# Expected: user identity + token expiry timestamp
# 4. Sanity-check the server is reachable + the corpus is accessible
ariadne stats
# Expected: total_documents, total_chunks, collections list
If ariadne whoami reports "Not authenticated" after ariadne login, the OAuth flow didn't complete. Check that the browser actually opened and the user signed in.
Tell them three short commands:
pip install ariadne-core-client
ariadne login --host https://their-url.up.railway.app
ariadne whoami
Explain:
ariadne CLI).ariadne whoami verifies it worked.Once authed, they can run ariadne search "test" to confirm the corpus is reachable, or have their agent drive ariadne search calls on their behalf.
The Ariadne Core plugin packages the agent-facing skills (walkthrough, install, deploy, document-intelligence, invitation, etc.). Install it in Claude Code Desktop so agents can invoke the skills:
# Add the marketplace (one-time)
/plugin marketplace add denson/ariadne-core
# Install the plugin
/plugin install ariadne-core@ariadne-core
# Reload (or start a new session)
/reload-plugins
Cowork discovers plugins installed via Claude Code at user scope — install in Claude Code first, and the skills appear in Cowork too.
Once the CLI is installed + authed, an agent with shell / Bash tool access drives Ariadne via:
# Vector search
ariadne search "query" --collection some-collection --top-k 5
# Listing
ariadne list-collections
ariadne list-documents
# Ingest
ariadne ingest /path/to/file.pdf
# Direct REST for anything the CLI doesn't cover (e.g. /api/bw/* for bw-side
# ticket retrieval). The token is in the OS keyring:
TOKEN=$(python -c "import keyring; print(keyring.get_password('ariadne-core', 'https://THE-URL:token'))")
curl -H "Authorization: Bearer $TOKEN" https://THE-URL/api/bw/projects/some-slug/tickets/some-id
ariadne logout # clear stored credentials
pip uninstall ariadne-core-client
/plugin uninstall ariadne-core
If they deployed their own instance and want to delete it:
railway down
curl -s https://THE-URL/api/health
# Expected: {"status": "healthy"}
curl -s https://THE-URL/.well-known/ariadne-config
# Expected: JSON with AUTH0_DOMAIN, AUTH0_CLIENT_ID, AUTH0_AUDIENCE
ariadne whoami
# Expected: identity + expiry
ariadne stats
# Expected: total_documents, collections list
| Symptom | Cause | Fix |
|---|---|---|
pip install ariadne-core-client says "no matching distribution" | Older pip or stale index | pip install --upgrade pip and retry, or pip install --index-url https://pypi.org/simple ariadne-core-client |
ariadne login doesn't open a browser | Local default-browser misconfigured | Copy the URL printed by ariadne login into your browser manually |
ariadne login says "callback port in use" | Another process is on the loopback port | Stop the conflicting process or restart your machine |
ariadne whoami says "Not authenticated" after login | OS keyring not writable / sign-in didn't complete | Re-run ariadne login; ensure the OS keyring service is running (gnome-keyring on Linux, default on macOS / Windows) |
ariadne stats returns 401 | Token expired (Auth0 default ~20h) | Re-run ariadne login |
ariadne stats returns 502 | Deployment not running | Check Railway dashboard, run railway logs |
/.well-known/ariadne-config returns 500 auth_misconfigured | AUTH0_DOMAIN / AUTH0_CLIENT_ID / AUTH0_AUDIENCE unset on the server | Set all three in Railway variables and redeploy |
401 missing_token from API | No Authorization header, empty header, or Authorization: Bearer with no token | Add Authorization: Bearer <jwt> with the actual JWT |
401 wrong_audience or wrong_issuer | JWT was minted against a different Auth0 tenant/API | Re-run ariadne login against the right host; check /.well-known/ariadne-config for the expected values |
401 expired_token | Token has expired | Re-run ariadne login |
| Embedding errors in server logs | Bad API key or wrong base URL | Verify key works against your provider's endpoint directly |
DATABASE_URL errors on deploy | Set manually in .env | Remove DATABASE_URL from .env — Railway injects DATABASE_URL_PRIVATE (internal) and DATABASE_URL (public) automatically; the app prefers the private one |
Point the user (or agent) to:
github.com/denson/beadwork-demo-aresense. User clones the repo and invokes factory-demo-walkthrough from there to feel the substrate before committing to their own data.For the visual version with illustrations, use the ariadne-core-walkthrough skill.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub denson/ariadne-core