Infrastructure Provider Contracts

These references describe the boundaries a service must satisfy to supply shared caching or remote execution to Once. Start with Become an Infrastructure Provider for a top-to-bottom cache integration guide.

Independent Capabilities#

• Cache: store opaque blobs and action results; restore verified content across machines. Current implementations are local storage and a local tier backed by Tuist's REAPI cache.
• Execution: run a prepared command in an isolated environment and return declared outputs, streams, and exit status. Current implementations are native local execution, Microsandbox, E2B, and Daytona.
• Artifacts: retain immutable build products for distribution. Local publication accepts arbitrary payloads; see each provider's guide for supported formats and publication limits.

Once owns graph analysis, dependency ordering, action identity, and cache policy. Providers do not need to interpret target kinds or implement the graph. Live run events are an optional reporting protocol, not an execution or cache protocol.

Integration Status#

Provider dispatch is currently compiled into Once. There is no dynamic provider registration API, generic REAPI cache configuration, or REAPI Execution.Execute transport. A new provider needs an adapter and configuration/resolution changes in Once. The cache reference separates the provider-neutral behavior from the wire format used by today's Tuist adapter; the execution reference describes an internal command boundary and service requirements, not a new network API.

Code Reading Map#

These links follow main. The internal types are implementation references, not compatibility promises of the public cache SDK. Pin a revision in your integration's validation record.

• InfrastructureProviderConfig and manifest decoding: supported kinds and the independent named cache/execution bindings.
• CLI provider resolution: resolve workspace policy to a cache implementation or RemoteExecution; keep credentials separate.
• Shared cache configuration resolution: cache selection and overrides used by callers.
• CacheProvider: local/remote cache dispatch and the operations consumers rely on.
• Executor selection: dispatch, resource domain, and unsupported-policy rejection.
• PreparedCommand and remote dispatch: command data passed into a sandbox adapter.
• Provisioner: optional once connect support, currently Tuist only.
• Authentication command dispatch: optional interactive/CI login integration, currently Tuist only.

Keep a new provider's transport, authentication, and service behavior in its adapter. Use generic cache, scheduling, and action primitives for shared behavior. Do not add ecosystem-specific scheduling or build-system branches to a provider integration.

See the manifest reference for the configuration customers use and the provider guide for the integration handoff checklist.