Getting started
Let your AI set it up
Paste one prompt into Claude Code, Cursor, or whichever coding agent you use. It reads your repository, configures delivery to your receiver and verifies an event through your application. You approve the sign-in and any production changes that require your approval.
The prompt
Copy this into your agent, in the repository you want to connect.
Set up Queuey (https://queuey.ai) in this repository.
The defaults below do the whole job; ask me only where a step says so.
An engineer steers with queuey plan, queuey.deploy.json and the flags:
when you are done, tell me in a few lines what you set up and where those
are.
Where to read, as plain text. Read it when you need exact syntax; do not
guess at it:
- https://queuey.ai/llms.txt is the index, https://queuey.ai/llms-full.txt every page
at once (if your fetch cuts it short, read single pages instead).
- https://queuey.ai/docs/md/{slug} is one page as Markdown, for example
https://queuey.ai/docs/md/quickstart.
- https://queuey.ai/.well-known/agent-skills/index.json lists the agent skills.
- queuey --help, queuey <command> --help, and queuey advise.
A sandbox that cannot reach localhost can still read queuey.ai. If I give
you addresses for a local or self-hosted Queuey (API, ingress, console,
docs), they win over the queuey.ai addresses in this text.
1. First, ask me once: have I decided where Queuey goes — which part sends,
which part receives, or which services? If I have, follow that. If I say
"see for yourself", run queuey advise --json (step 3), tell me which files
it read (filesRead), and propose a place before you write any code.
2. Install the CLI if it is not there. With .NET 8 or later:
dotnet tool install -g Queuey.Cli --prerelease
The tool lands in ~/.dotnet/tools. If queuey is not found afterwards,
put that folder on PATH as $HOME/.dotnet/tools, for example in ~/.zshrc:
export PATH="$PATH:$HOME/.dotnet/tools"
Not as "~/.dotnet/tools": a ~ inside quotes is not expanded, and PATH
then names a folder that does not exist.
No .NET? Every release ships the CLI as one self-contained file, with
no runtime needed, for osx-arm64, osx-x64, linux-x64, linux-arm64 and
win-x64 (.zip). On macOS or Linux, with this machine's platform in place
of osx-arm64:
curl -fsSL https://github.com/Queuey-AI/queuey-client/releases/latest/download/queuey-osx-arm64.tar.gz | tar -xz
Then move ./queuey onto PATH, or call it as ./queuey. A 404 means there is
no build for this machine: install .NET 8 and use the command above.
Check it with queuey --version. This setup requires Queuey.Cli, Queuey.Client and Queuey.Edge ≥ 0.1.0-preview.9 (newer than 0.1.0-preview.8).
In a .NET project, add the package for the job, with --prerelease:
- Queuey.Client, to publish from a service that is online:
dotnet add package Queuey.Client --prerelease
- Queuey.Edge, to publish from a machine with local disk that survives a
restart, where the network can drop:
dotnet add package Queuey.Edge --prerelease
- Queuey.Client.Waas, only to declare event streams for partners:
dotnet add package Queuey.Client.Waas --prerelease
Anywhere else there is no package to add: one signed POST to the ingress,
as in https://queuey.ai/docs/md/quickstart and https://queuey.ai/docs/md/how-to/signed-requests.
Only from server-side code — the key must never end up in a browser bundle.
You use the CLI. Queuey's MCP server, https://api.queuey.ai/mcp with
sign-in, is for operating Queuey from an AI client such as claude.ai or
ChatGPT, not for a coding agent: https://queuey.ai/docs/md/how-to/mcp.
3. Run queuey advise --json. Tell me its reasoning in your own words. If it
asks a question (usually: can the network here be trusted?), ask me.
Do NOT write your own retry loop, local queue, backoff or offline buffer:
that is Queuey.Edge. Then queuey advise --write-files writes
queuey.deploy.json, with a secured dev workspace, and .gitignore lines
for .env and queuey.json.
4. Log in:
queuey login --profile dev --json
With addresses I gave you, add --api-base <API> --ingress-base <ingress>.
It prints a link and a code, and exits 5: it waits for me. Show me the
link and the code; once I have approved it, run:
queuey login --profile dev --wait
Do not ask me for an API key: the login is the connection.
5. The workspace. Security goes on the workspace, and its queues inherit it;
a new queue is open until its workspace has security. Then:
queuey plan --profile dev
queuey apply --profile dev
A workspace without an environment counts as prod, where keys wait for
my approval. Tell me that the security is set on the workspace.
6. The sender's signing key, the same value in Queuey and in the app:
queuey keys mint --profile dev --write <target>
It writes QUEUEY_SIGNING_KEY_ID and QUEUEY_SIGNING_SECRET. The target is user-secrets in a .NET project with a UserSecretsId, else
.env. If I can use neither, run it without --write: nothing is minted, and
it names the variables and the console page. Tell me where the key is.
Queuey.Client and Queuey.Edge read it with UseSettings(...) or
UseEnvironmentVariables(), which reads .env in Development only:
https://queuey.ai/docs/md/reference/dotnet-client, and for Edge on a device
https://queuey.ai/docs/md/how-to/edge.
7. Configure the receiver for every queue, even if it is outside this repository.
Find its actual route and environment from code and deployment settings; ask
me if the address is missing. Never guess it or leave a placeholder.
Set delivery.url in queuey.deploy.json: an absolute receiver URL, or a route
with workspace.delivery.baseUrl. This is not Queuey's ingress address.
For local delivery use delivery.kind = "localForward" and the app's route
as delivery.url; queuey listen supplies the local host and port.
If this code takes Queuey's deliveries, create the receiver's secret:
queuey credentials generate <name> --profile dev --write <target>
then merge signing into its delivery configuration, keeping url and kind:
"delivery": { "signing": { "enabled": true, "templateKey": "queuey",
"credentialRef": "<name>" } }
Verify every delivery (https://queuey.ai/docs/md/how-to/verify-deliveries), and
deduplicate on the event id only with the v2 signature.
A hosted Queuey never reaches localhost: to receive on this machine,
forward the queue to queuey listen, as
https://queuey.ai/docs/md/how-to/local-delivery shows.
Run queuey plan and queuey apply with --profile dev. Read back the saved
delivery configuration and check the effective receiver, including inherited
settings, against the intended endpoint. Do not expose URL credentials.
When you start the app to test it, stop it by the PID you started, or
with lsof -ti tcp:<port> -sTCP:LISTEN. Never use lsof -ti tcp:<port>
alone: it also finds processes connected to the port, such as Queuey
delivering to the app, and kills them too.
8. Implement and verify the integration. Wire the publish call into the agreed
application path. Start the app (and listener, if local), trigger a harmless
representative event through it, and follow that event with:
queuey verify <queue> --event <event-id> --profile dev --json
If its id is unavailable, use queuey verify --help to start observation before
triggering the event. Wait for the final result: a started check is not a pass.
Confirm delivery to the intended receiver; check its logs or stored result
where accessible. Report the queue, receiver (without secrets), event id and
verification outcome. A 202 at ingress or successful apply is not completion.
Do not claim setup is complete until delivery is verified. If blocked, report
exactly what is missing and the next action needed.
9. Never:
- print, read or copy a secret, or use --show-secret;
- add --replace without reading me its warning and asking first;
- put a key in a command's arguments, in code as a literal, or through
/tmp;
- work around an approval. In prod a command exits 5 with a link
(approval_required): show me the link and wait.
You never need a license-wide API key; if one is ever wanted, I mint it
in the console at https://app.queuey.ai (the license's Home page → API keys).For agents that load skills
The same prompt is published as an agent skill, setup-queuey, next to design-event-delivery in the skills index. An agent that discovers skills on its own can load it without anyone pasting the prompt.
Not a .NET repository?
The prompt works the same. The CLI is written in .NET, but it does not need .NET to run: every release ships it as one self-contained file for macOS, Linux and Windows, and the prompt tells the agent how to fetch it. In a JavaScript, TypeScript, Python or Go repository, queuey advise does not reach for a package at all: the integration is one POST to the ingress. In a web app, that call belongs in server-side code — an edge function, a route handler, your API — and never in the browser bundle, where the key would be readable by anyone who loads the page.
The keys, and who holds them
Your app publishes with a signing key for its workspace, which reaches every queue in it. The agent makes it with your login, queuey keys mint --write user-secrets in a .NET project with user secrets, queuey keys mint --write .env otherwise, and the value goes straight to where the app reads it: the agent never sees it, and it is the same value Queuey holds. A receiver gets its secret the same way, with queuey credentials generate <name> --write …, and checks every delivery with it. When neither place suits you, the agent tells you the variable names and the console page where you make the key yourself.
A .NET app reads them with UseSettings from configuration, or with UseEnvironmentVariables(), which also reads .env in Development; in production they come from environment variables, as the Queuey.Client page shows. A license-wide API key is yours, in the console, and the agent never needs one.
Queuey Edge signs with the same QUEUEY_SIGNING_* key as Queuey.Client. On a device, the Edge daemon reads it from edge.env, which the agent makes with queuey keys mint --queue <queue> --write edge.env and installs as root-only, the way the Edge page shows.
Program.cs or any other code; or pass it through /tmp.If you want the controls
You do not have to answer anything for the defaults to work. If you want to steer, the agent tells you where: queuey plan shows what queuey apply would change, and what the plan's limits would refuse, before anything is written; queuey.deploy.json holds the configuration and is committed with the code; and flags change the defaults — keys mint --queue for a key to one queue, --type api-key, --write for where a secret goes.
Your own Queuey
Running Queuey locally or self-hosted? Give the agent its addresses — the API, the ingress, the console, the docs — with the prompt. They win over the queuey.ai addresses in it: it logs in with --api-base and --ingress-base, the profile keeps both hosts, and every command after that uses them.
An agent in a sandbox may not reach localhost at all, so a docs server on your machine can be out of its reach. It can still read the docs on queuey.ai: every page at once in /llms-full.txt, or one at a time as Markdown at /docs/md/{slug}.
What happens, in order
- It asks you one thing first
Have you decided where Queuey goes — which part sends, which receives, which services? Point it there, or say “see for yourself”: then it reads the repository, tells you which files it read, and proposes a place before it writes any code.
- It reads the repository
Project files, infrastructure and source. It is looking for two things it can actually determine: whether events already survive a crash somewhere, and whether local storage survives a restart.
- It works out the path
Already have an outbox, a bus or a job queue? Publish from that consumer — no reason to rebuild it. Local disk that survives a restart? That is Queuey Edge. No such disk, as in a container without a volume or a serverless function? Queuey.Client, or one signed POST outside .NET.
- It asks you the one thing it cannot read
Whether the network where this runs can be trusted. That is not in the repository, so it is asked rather than guessed — and only where the answer would change the recommendation.
- It sets up, and you log in with one link
It writes the deployment file and wires up publishing. To connect, it runs queuey login and shows you a link: you check the code and approve it in the console, signing up first if you need to, and it carries on. There is no key to copy. It makes a dev workspace with the security set on it, so every queue inherits it, and tells you, because a new queue is open until its workspace has security. The signing key your code publishes with, and the secret a receiver checks deliveries with, it puts where the app reads them without ever seeing them.
- It checks the receiver address
For every queue, it writes the receiver URL into queuey.deploy.json, applies it and checks the saved destination. It uses the route your application actually handles, with the right host for the environment. If the address is missing, it asks you.
- It proves the integration works
It triggers a harmless event through your application and uses queuey verify to follow it to the receiver. You get the event ID and the verification result. If delivery cannot be verified, it explains what is missing instead of calling the setup complete.
- In prod, it waits for you
A workspace without an environment counts as prod. There, a key goes to a person: the command answers with a link, the agent shows it to you and waits, and it does not try to get around it.
If you would rather look first
This one analyses and changes nothing — no files, no workspace, no credentials. Useful on a repository you do not want touched yet, or when you just want to see what it makes of things.
Analyse this repository for Queuey (https://queuey.ai) but change nothing.
Install the CLI if needed. With .NET 8 or later:
dotnet tool install -g Queuey.Cli --prerelease
The tool lands in ~/.dotnet/tools. If queuey is not found afterwards,
put that folder on PATH as $HOME/.dotnet/tools, for example in ~/.zshrc:
export PATH="$PATH:$HOME/.dotnet/tools"
Not as "~/.dotnet/tools": a ~ inside quotes is not expanded, and PATH
then names a folder that does not exist.
No .NET? Every release ships the CLI as one self-contained file, with
no runtime needed, for osx-arm64, osx-x64, linux-x64, linux-arm64 and
win-x64 (.zip). On macOS or Linux, with this machine's platform in place
of osx-arm64:
curl -fsSL https://github.com/Queuey-AI/queuey-client/releases/latest/download/queuey-osx-arm64.tar.gz | tar -xz
Then move ./queuey onto PATH, or call it as ./queuey. A 404 means there is
no build for this machine: install .NET 8 and use the command above.
Then run: queuey advise
Summarise what it says: do we send, receive or both; which path it recommends;
and the evidence it read that from. List the files it would create, but do not
create them. If it asks a question it could not answer from the code, put that
question to me.Why it asks only once
If you already know where Queuey goes, it would be a waste to make the agent guess, so it asks first and follows you. If you don't, you don't have to classify your own repository: queuey advise reads whether it sends, receives or both, whether events already survive a crash somewhere, and whether local disk survives a restart — the part the tool does better, especially on a codebase you inherited.
It does ask about the network, because that genuinely is not in the repository. And it shows the file behind every conclusion, so when it reads something wrong you can see exactly where and say so.
- Mint a license-wide API key. That is a console action, and it stays yours. A key that can mint keys would turn repository access into account access. The signing key for the workspace it can make, straight into user secrets or a git-ignored .env, without seeing the secret.
- Write its own delivery machinery. If your producer needs retries, a local buffer or offline survival, the answer is Queuey Edge, which already exists. An agent is good at writing two hundred lines of retry logic, which is exactly why it is told not to.
Without an agent
The same command works on its own, and reads more like a second opinion than a tool:
queuey advise
queuey advise --json # the same, for a machineOr follow the quickstart and send an event by hand.