Projects & deployments

Swirls Cloud hosts the resources declared in your .swirls files. Deploy with swirls deploy or connect a GitHub repository for automatic deployment on push. Use the dashboard to inspect snapshots, configure resources, and operate the project. See Infrastructure for execution environments and storage.

Project resources

• Execution: workflow nodes are checkpointed so interrupted runs can resume. See failure policies for retry behavior.
• Operations: inspect traces, respond to reviews, and query the audit log.
• Credentials: declare secrets per node and configure their values in Cloud.
• Deployments: retain immutable source snapshots and select the active deployment.
• Access: invite teammates and declare roles and policies for agent access.

Hosted execution depends on the project's plan and required credentials. See Billing for execution access, credits, and limits, and the security model for security controls.

Getting started

curl -fsSL https://swirls.ai/install | bash
swirls auth login

swirls configure

swirls deploy

git push

Deploy methods

Swirls Cloud supports two deploy paths:

Both paths compile every .swirls file in the project, validate the merged definition server-side, and store it as an immutable snapshot with its source files. You can use both on the same project.

Git deploys

Link a GitHub repository to a project on the dashboard's Integrations page: install the Swirls GitHub App, pick the repository, and optionally set a root path when your .swirls files live in a subdirectory. Pushes to the configured production branch deploy to production; other branches can deploy as previews or be ignored, per your branch rules. Every push gets a commit status that links to the deployment, and a push with no changes is skipped with a successful status. You can also trigger a manual deploy of any branch from the dashboard.

Active deployment and rollback

One deployment per project is active at a time. The active deployment is the one whose forms, webhooks, and schedules fire. Successful non-test deploys become active, including preview and staging deployments. A test deployment never becomes active. To roll back, open Deployments in the dashboard and repoint the active deployment to any earlier successful snapshot. In-flight executions keep the snapshot they started with, so changing the active snapshot does not restart them. Rollback changes definitions; it does not reverse database migrations, stored data, or external side effects.

Disable and re-enable a project

Disable a project from Settings → General when you want to keep its configuration and history without keeping it operational. Disabling closes execution admission immediately, cancels live workflow and agent work, pauses schedules without backfilling missed occurrences, and then marks the project disabled. Deployments, secrets, connections, databases, files, traces, and other project data remain available for inspection.

Disabled projects do not count toward active-project limits and cannot create new execution-credit or tool-spend usage. Usage already incurred is retained and is not refunded. Enable the project from the same settings page when you are ready to accept work again; schedules resume at their next future occurrence, and cancelled runs are not resumed.

The same lifecycle operations are available from the CLI:

swirls project disable --project <id-or-name>
swirls project enable --project <id-or-name>

The dashboard

Open a project in the dashboard to operate it. The major surfaces:

• Activity: browse recent workflow runs, filter by status, workflow, trigger, or top-level/sub-workflow, and choose Load older runs for more history. Enable Live for automatic updates. If a refresh fails, previously loaded runs stay visible; Refresh retries with your filters intact.
• Traces: the run and debug surface. Every workflow execution and agent session as a filterable list with a span waterfall per run. See Traces.
• Inbox: pending human-in-the-loop reviews and approvals.
• Agents: chat with deployed agents, with persisted session history.
• Triggers: the project's forms, schedules, and webhooks.
• Streams, Views, and Databases: browse stream records, spreadsheet views, and managed database tables.
• Deployments: versioned deploys with environment and source filters, plus rollback.
• Connections, MCP servers, and Secrets: outbound integrations and credentials, encrypted at rest. Vendor API keys are declared in DSL secret blocks (optionally type: managed for Enterprise platform keys).
• Auth: inherit an organization identity provider or register a project-specific provider for OIDC federation. Each binding has its own project audience.
• Access: assign member attributes that deployed role and policy blocks match on.
• Settings: project lifecycle, trace content policy, and trace export destinations.

At the organization level: members and invitations, the audit log, reusable identity provider defaults that projects explicitly inherit, and billing.

Plans and credits

Swirls Cloud meters usage in credits. Workflow node executions and agent chat turns consume execution credits from your plan's allowance; one-time top-ups and usage-based overage extend it. See Billing for how metering, budgets, and enforcement work, and swirls.ai/pricing for current plans and prices.

On self-serve paid plans, you declare vendor API keys in DSL secret blocks and set values on the Secrets page. Enterprise supports type: managed secrets so Swirls supplies platform keys.

Next steps

• Local Development: Author, validate, and deploy .swirls files from your machine.
• Billing: How credits, budgets, and usage reporting work.
• Traces: Inspect every run span by span.
• Agent Onboarding: Let AI agents register for Swirls on behalf of users.