Infrastructure

Once works locally without configuration. Infrastructure becomes useful when you want to run an action on another machine or share a cached result with another developer or coding agent.

Artifacts describes a third independent capability: retain immutable build products for distribution. Once publishes the content; infrastructure decides how people use it.

Build an Integration#

If you operate an infrastructure service, start with Become an Infrastructure Provider. It walks through shared caching, the adapter work required in Once, authentication, validation, and the customer handoff. The provider contracts give exact behavior and links to the implementations and tests.

Create And Connect A Project#

Provision a remote project and bind this repository to it in one command:

bash
once connect --provider tuist --create

Once signs you in when needed, creates the project with the provider, and records the binding in the repository root once.toml. Read Connect A Project for account selection, binding an existing project, and previewing the write.

Run An Action Somewhere Else#

Choose a named execution provider in the repository root once.toml:

toml
[infrastructures.remote_tests] kind = "e2b" template = "vitest-node-22" [infrastructure.execution] provider = "remote_tests"

Then run a literal command through that provider:

bash
once exec --remote -- node --version

Annotated scripts can select the same provider with # once remote "remote_tests". Once creates a clean execution root, transfers only declared inputs, runs the command, retrieves declared outputs after a successful exit, and deletes the machine.

Read Remote Execution for the full action lifecycle and a real Vitest workflow.

Share Results Across Machines#

A cache provider lets another machine reuse an action result instead of running it again:

toml
[infrastructures.tuist] kind = "tuist" account = "acme" project = "app" [infrastructure.cache] provider = "tuist"

The execution and cache capabilities are independent. A repository can run actions through E2B or Daytona while storing reusable results through Tuist. It can also use either capability on its own.

Available Providers#

ProviderCapabilityEnvironmentBest fit
DockerExecutionLocal immutable imageValidate per-action graph dispatch in fresh containers.
MicrosandboxExecutionLocal imageValidate an action boundary on the current computer.
E2BExecutionHosted templateStart a prepared hosted environment quickly.
DaytonaExecutionHosted container imageBuild a hosted environment from a familiar image.
TuistShared cache, artifactsNot applicableReuse action results and share installable applications.

Keep A Local Escape Hatch#

The local cache remains available after a shared cache is configured. Set ONCE_CACHE_PROVIDER=local for one invocation:

bash
ONCE_CACHE_PROVIDER=local ./scripts/greet.sh

For execution, omit --remote to run on the current computer. Pass --compute <provider> with --remote to choose a different named execution provider for one invocation.

Next#

Start with Remote Execution, then open the setup guide for the provider you want to use.

For CI orchestration, read Event-Driven Automation. Declare triggers that select existing capabilities and let the CI service schedule workers without maintaining another build graph. The guide lists service integration status, including upcoming Tuist support and a Buildkite dynamic-pipeline example.