Infrastructure
The execution environments, storage, credentials, and network boundaries behind a Swirls project.
Your .swirls files declare resources and behavior. Swirls supplies the infrastructure behind those declarations. This page maps the parts of that infrastructure to the primitives that use them.
Execution environments
Different kinds of work run in different environments. Choose the primitive according to the work it needs to do.
| Work | Where it runs | What to use it for |
|---|---|---|
| Workflow orchestration | The hosted durable execution runtime | Order steps, wait for inputs or reviews, checkpoint progress, and recover interrupted work. |
| Built-in nodes and hosted tools | Swirls execution workers | Model calls, HTTP requests, integrations, database operations, and other supported node types. |
code nodes and embedded @ts | An isolated JavaScript environment | Transform values, calculate inputs, and shape outputs with the supplied execution context. |
| Agent workspace tools | A managed Linux sandbox | Read and write files, navigate a workspace, and run shell commands during an agent turn. |
disk node commands | A Linux environment attached to the named disk | Run a command against persistent files shared by the project. |
Embedded TypeScript is not a general-purpose server process. It does not provide an operating-system shell or arbitrary npm installs. A command: @ts expression produces a command string; the disk environment executes that command afterward.
See node types, execution context, and agents for the contracts available in each environment.
Durable execution
Workflows execute a graph of dependent steps. The runtime records completed node outputs so interrupted work can resume from its checkpoints. Waits, reviews, and child workflows are part of that execution lifecycle.
Retries and failure handling still matter when a step calls an external service. Use the appropriate failure policy and design external writes for the retry behavior of that service.
How execution works explains the run lifecycle. Traces show what happened during a run.
Data and files
| Resource | Storage responsibility | Learn more |
|---|---|---|
| Stream | Swirls stores typed records produced by the system. | Streams |
| View | Swirls presents and computes over stream records. | Views |
| Managed database | Swirls provisions PostgreSQL from a declared schema. You review schema changes and data migrations. | Databases |
| Existing Postgres | You supply the database and connection; workflows query it through a declared resource. | Postgres |
| Disk | Persistent files can be shared across workflows and agents. | Disks |
An agent's temporary sandbox workspace and a persistent disk have different lifecycles. Put files that need to survive sandbox replacement on persistent storage. Use streams or databases for structured records that other parts of the system need to query.
Credentials and identity
Declare secret names in source and configure their values in the platform. Execution receives the credentials its declarations require. For supported providers, a connection binds an OAuth account to a named slot and supplies tokens at run time.
Roles and policies determine which identities may invoke agents. Workflow and tool restrictions within a grant are declared but not yet enforced at those finer boundaries; use agent profiles to narrow tools. An organization's identity provider can supply the identity facts those rules match.
- Secrets — named credential values and delivery.
- Connections — OAuth bindings and typed actions.
- Access control — roles and policies.
- Identity federation — external identity providers.
Networking and hosted interfaces
Apps, forms, webhooks, and chat channels provide entry points to the deployed system. A project network declares a private connectivity boundary: it identifies which resources may be exposed into that network and which outbound consumers need a private route.
Named network binding and live routing are not yet available. Read Project Networks for setup requirements, supported consumers, and current limitations.
Deployments and operations
A deployment is a version of the project definition. Persistent data and credentials belong to the project; redeploying the source does not recreate them. The active deployment selects the live resource definitions, while existing runs retain their original snapshot.
Use Cloud deployment controls to manage releases and rollback, playbooks to verify behavior, and traces to investigate runs. Billing describes hosted execution access and usage limits.