Platform overview
How source files, projects, deployments, managed infrastructure, and execution fit together.
Swirls is a managed platform for systems defined in .swirls files. A project can contain agents, workflows, data, connections, access rules, and apps. The platform turns those declarations into deployed resources and provides the runtime that executes their work.
The platform model
| Concept | What it means |
|---|---|
| Organization | The workspace that owns projects, members, identity settings, and billing. |
| Project | The unit you configure, deploy, and operate. Its resources, credentials, data, and execution history belong to that project. |
| Source | The .swirls files that describe the system. Multiple files compose into one project definition. |
| Deployment | An immutable snapshot of that definition and its source. A project has one active deployment at a time. |
| Primitive | A declaration for part of the system, such as an agent, workflow, database, connection, or app. |
| Execution | A run of deployed work, with its inputs, step outputs, state, and history. |
Start with the primitives to understand what you can declare, or follow the quickstart to create your first deployment.
From source to deployment
1. Define the system
Write .swirls files locally or with a coding agent. Resource names connect the files: a workflow can invoke an agent, an agent can use a workflow as a tool, and both can use the project's data and connections.
Learn the language and organize multiple files.
2. Validate locally
Run swirls doctor to check the source before deploying. Local tooling supports authoring, validation, and type generation. Workflow execution and agent chat run on Swirls Cloud.
3. Deploy a snapshot
Use swirls deploy, or connect a GitHub repository and deploy through Git. The platform validates the merged definition, stores a deployment snapshot, and makes a successful non-test deployment active. Configure the credentials and connections required by your resources in Cloud.
4. Operate the project
When hosted execution is enabled, triggers start workflows and messages start agent turns. Use Cloud to inspect traces, respond to reviews, manage credentials, and change the active deployment. Runs keep the deployment snapshot they started with.
Understand execution, test with playbooks, and inspect traces.
Infrastructure behind the primitives
Swirls provides the execution runtime, isolated code evaluation, agent workspaces, managed storage, credential delivery, and hosted interfaces. Different primitives use different parts of that infrastructure. A TypeScript expression, a workflow node, and an agent shell command do not all run in the same environment.
What you configure
You define the system's behavior, schemas, permissions, and external dependencies. You also supply vendor credentials where required, connect external accounts, and verify that the system behaves as intended. Swirls manages the deployed resources and execution runtime.
- Secrets and connections — configure access to external services.
- Roles and policies — control who can use the system.
- Identity federation — connect an identity provider.
- Billing and execution access — understand plan capabilities, credits, and limits.
Deployment and execution are separate
Local authoring and deployment for inspection do not imply hosted execution access. Free deployments let you inspect the compiled project; running workflows and agent chats requires hosted execution to be enabled. Check the project's plan and required credentials before starting a run.