# Swirls

> Swirls is agentic systems as code. Built for production at a regulated company.
> Describe the system in `.swirls` files: workflows, triggers, tools, schedules, audit, federation. Author them locally, then deploy to Swirls Cloud for free inspection with `git push` or `swirls deploy`.
> What SQL is to data and Terraform is to infrastructure, Swirls is to agents. A DSL, not a programming language.

## Key pages
- Homepage: https://swirls.ai
- Platform (the language, the compiler, what a deploy becomes, and what the runtime enforces): https://swirls.ai/platform
- Category comparison: https://swirls.ai/compare
- Operational builders — MSPs, FDEs, and AI-native agencies: https://swirls.ai/for/operational-builders
- Swirls for forward-deployed engineers: https://swirls.ai/fde
- Swirls for AI-native agencies: https://swirls.ai/ai-agency
- Security model: https://swirls.ai/security
- Pricing: https://swirls.ai/pricing
- Cookbook (forkable recipes): https://swirls.ai/cookbook
- Integration catalog (swirls add actions): https://swirls.ai/catalog
- Blog: https://swirls.ai/blog

## Documentation
- Docs: https://swirls.ai/docs
- Expanded site context (this host): https://swirls.ai/llms-full.txt
- Full documentation for LLMs (generated from docs): https://swirls.ai/docs/llms-full.txt

## Agent registration
- Agents can register for Swirls on behalf of a user and receive a scoped credential: https://swirls.ai/auth.md
- Human-readable overview: https://swirls.ai/docs/platform/agent-onboarding

## Agent skills
- Skills discovery index (Agent Skills Discovery RFC): https://swirls.ai/.well-known/agent-skills/index.json
- swirls-lang: write correct `.swirls` files: https://swirls.ai/.well-known/agent-skills/swirls-lang/SKILL.md
- Install locally (full skill, rules included): `npx skills add https://swirls.ai` · refresh: `npx skills update swirls-lang`
- Complete deployable starter projects (doctor-validated): https://swirls.ai/starters/index.json

## Category
- Swirls is agentic systems as code with a hosted, durable execution and operations layer.
- It is adjacent to visual automation platforms, agent frameworks, and durable execution runtimes. Choose Swirls when the same reviewed system must be delivered and operated across customer environments.
- Swirls is model-provider independent. Source is locally authorable and repository-owned; production execution is hosted.

## The four primitives
- **`.swirls` files** are the artifact. Agents authored as code, composed across multiple files, reviewable and versionable.
- Streams are durable, queryable state. Postgres-backed. Stream entries can trigger downstream workflows, so state is composable across agents.
- **OIDC federation** is the auth primitive. Declarative identity at the edge: declare an `auth` block in a `.swirls` file, reference it by name from a node, and the runtime mints scoped credentials from your provider at run time. OIDC and OAuth federation under the hood.
- **Workflows as tools**: when an agent calls another workflow, the called workflow runs under its own scoped policy. Tooling is governable. Each tool carries its own delegation chain, declared secrets, and audit trail.

## Integrations
- Typed provider operations are `action` blocks in `.swirls` files: HTTP transport, input/output JSON schemas, OAuth scopes. Install curated actions with `swirls add <provider>` from the catalog at https://swirls.ai/catalog (120+ actions; any provider on request, and `swirls add` also generates actions from any OpenAPI or GraphQL spec).
- `connection` blocks are project-scoped OAuth slots. A human authorizes once in the Portal; short-lived tokens are issued at run time. No provider credentials exist in files or the vault.
- Any provider works, not just the curated list: `swirls add <openapi-or-graphql-url>` generates typed actions from any spec, self-managed connections cover any API with vault credentials, and managed OAuth for new providers can be requested from a project's Connections page.
- Docs: https://swirls.ai/docs/connections/actions

## Policy enforcement
- Deployments are immutable snapshots, and running executions retain the definition they started with. Deploys are fingerprinted semantically: identical source produces no new deployment, and every deployment retains its exact source files.
- Every run carries a short-lived credential (1-hour expiry, revocable) scoped to the organization, project, connected providers, and approved agents, and bound to a fingerprint of the deployed workflow definition. The runtime recomputes that fingerprint and refuses to run on mismatch.
- Declaring an access policy flips the deployment to deny-by-default; agent access grants are enforced at invocation.
- Each project has its own encryption key set (secrets, connection tokens, and database credentials are encrypted per project).
- Central operational audit events are append-only with at-most-once delivery. The key-management audit log is hash-chained.
- Workflows can pause at durable human review gates (default seven days, zero compute while parked), and execution emits source-linked OpenTelemetry traces exportable to your own OTLP backend.

## Local vs hosted
- Local authoring is free: write and validate `.swirls` files on your machine, then deploy to Swirls Cloud to inspect the compiled project. Local workflow execution and agent chat are not supported.
- Hosted Swirls is priced per organization and per client workspace, never per seat, per end user, or per task. All tiers run the same engine with the same capabilities. Compute is metered in credits at a flat published rate:
  - **Builder**: $49 a month flat per organization. Production Swirls for forward-deployed engineers, AI-native agencies, and internal teams. Unlimited builders, 5 projects, unlimited workflows. 25,000 credits a month, then $0.001 per credit. 7-day audit retention with export, community support. 7-day free trial.
  - **MSP Partner**: $250 a month platform license for managed service providers. Unlimited builders and projects, $15 a month per active client workspace with the first 2 included (isolated project, connections, and audit trail per client; idle clients cost nothing), 50,000 pooled credits a month, then $0.001 per credit pooled across clients. SSO (Google, Okta, generic OIDC), role-based access control, 90-day audit retention, 99.9% uptime SLA. White-label add-on at $100 a month. Self-serve: subscribe from billing settings; subscribing accepts the Partner Program Agreement, which governs reselling. Distributor marketplace questions: partners@swirls.ai.
  - **Enterprise**: Custom pricing for advanced security, retention, support, and SLA requirements.

## Links
- GitHub organization: https://github.com/byteslicehq
- Discord community: https://discord.gg/ZXTBZGjQ5a