Set up with a coding agent

Start with the setup prompt

Copy this prompt into a coding agent that can run terminal commands. It guides the agent through registration, CLI installation, learning the language, writing or downloading a starter, validation, and deployment. You approve the account access and provide any required vendor credentials.

Set me up with Swirls (swirls.ai) and build my first Swirls system. Follow these steps in order.

1. Register an account for me. Fetch https://swirls.ai/auth.md and follow it exactly, including where to store the credential for the CLI. Use the email flow: ask me for my email address, register, and tell me to open the approval email from Swirls. I will click the link, approve, and read you a 6-digit code from the approval page. The code is only on that page, never in the email. While I am getting the code, ask me what I want to build (an app, agent, workflow, or complete operational system), how it should start (an application action, form, webhook, schedule, or chat), who will use it, what systems it should connect to, and what it should produce. Ask where on my machine the project should live. If I do not know what to build, offer to set me up with a starter so I can get a feel for Swirls: fetch https://swirls.ai/starters/index.json, describe each starter in one line, let me pick or pick for me, and download its files into the project directory. Starters are validated ahead of time; use their files as written. Create the project directory and work inside it. Do not continue past registration until you have exchanged my code for a credential.

2. Install the Swirls CLI. Ask my permission, then run:
curl -fsSL https://swirls.ai/install | bash

3. Learn the language before writing any files. Fetch https://swirls.ai/.well-known/agent-skills/swirls-lang/SKILL.md and the rules it tells you to read first; rule links resolve relative to that URL. Use only syntax the spec explicitly allows. Never invent keywords, node types, or fields.

4. Write the .swirls files for what I described, or use the starter's files as downloaded. Projects can span multiple files. Validate with swirls doctor and fix every finding before deploying.

5. Deploy without prompts, exactly as auth.md documents:
swirls deploy --project <project-name> --create --name initial
Pick a short project name from what I am building.

6. If the deploy output warns about missing vendor keys, executions are held until those keys exist. Ask me for each key value (for example my OpenRouter or Anthropic API key) and store it with the exact command the deploy output prints, like: swirls secret set OPENROUTER_API_KEY=<value>. Never guess or invent key values.

7. Tell me the deployment id and remind me I can watch executions at https://swirls.ai/app. The approval step already signed me in there.

If any request returns an error code, the Errors table in auth.md says what to do. If swirls doctor keeps failing on syntax, re-read the spec rules instead of guessing.

When setup finishes, open Swirls Cloud to inspect the project. Hosted execution requires the appropriate project access and credentials; a successful deployment alone does not mean workflows or agent chats can run.

For the manual path, use Deploy your first project.

How agent registration works

AI agents can sign users up for Swirls. A user tells their agent to set up Swirls, the agent registers with the Swirls auth server, the user approves once, and the agent receives a scoped credential it can use to create projects and deploy workflows. If the user is new to Swirls, their account and workspace are created during registration. The user does not need to complete a separate signup form.

Swirls implements the auth.md standard for agent registration. The machine-readable contract lives at swirls.ai/auth.md.

If you are an agent reading this: fetch https://swirls.ai/auth.md and follow it. The sections below explain the registration flows and permissions.

Design

Registration is handled by the Swirls auth server at auth.swirls.ai. Agents discover it the same way OAuth clients do:

1. An unauthenticated request to a protected API endpoint returns a 401 with a WWW-Authenticate header pointing at the protected resource metadata.
2. The resource metadata points at the authorization server metadata, which carries an agent_auth block describing the registration endpoints and supported flows.
3. swirls.ai/auth.md documents the same contract as plain Markdown, readable by agents and humans alike.

Two registration flows are supported.

Agent-verified

Agent platforms that can mint an ID-JAG identity assertion for Swirls register in a single request. The platform asserts the user's verified email, Swirls verifies the assertion against the platform's published keys, and the credential is issued immediately. Repeat registrations from the same platform identity always route to the same Swirls account.

This flow is active when the authorization server metadata lists urn:ietf:params:oauth:token-type:id-jag in identity_assertion_types_supported.

User-claimed

Any agent that knows the user's email address can register. Swirls emails the user a one-time approval link. The link signs the user in, creating their account and workspace if needed, and shows a consent page listing exactly what the agent will be able to do. Approving reveals a 6-digit code. The user reads the code to the agent, and the agent exchanges it for the credential.

The approval code appears on the consent page after approval; the email contains the link, not the code. Keep approval with the person granting access.

What the credential can do

Registration credentials grant these scopes:

The credential acts as the user who approved it, inside their workspace. Organization settings, member management, and billing stay out of reach. Credentials expire after 30 days; agents re-register to renew.

Revocation

Three independent paths revoke agent access:

• The user can deny a pending request from the consent page.
• The agent can revoke its own credential by presenting it to the revocation endpoint.
• The agent platform can revoke every credential issued for a user by posting a signed logout token. One event from the platform invalidates all of that user's agent credentials at once.

Try it

Next steps

• swirls.ai/auth.md: the full registration contract with request and response shapes.
• OIDC Federation: workload authentication from your own identity provider.
• Swirls Cloud: managed runtime and dashboard.