Build at the Speed of Light

Satellites are remote build runners that speed up builds with Earthly’s caching and parallelization. Available via BYOC or Self-Hosted, they integrate with CI systems and local workflows to:

• Enhance CI with caching and parallelism.
• Share compute and cache across the team.
• Enable cross-platform builds (e.g., x86 on ARM).

BYOC stands for “Bring Your Own Cloud,” a service model that combines the benefits of on-premises deployment with the convenience of vendor management for a cloud-like experience. With our BYOC plan, you provide Earthly with access to your AWS account using a strict IAM role that you own.

The IAM role you grant us allows Earthly to create and manage EC2 instances within a specific VPC. However, this role does not grant Earthly connection access to the instances themselves or to their internal cache data. For more details, refer to our BYOC documentation. That said, organizations with strict compliance requirements may prefer the Self-Hosted option, which ensures that satellites are fully controlled by your team alone.

The number of users is tracked by monitoring who triggered a Satellite build at least three times during a month. Builds may be triggered either directly by the user in their terminal, or indirectly by pushing code to a repository, and that push being picked up by a CI that uses Earthly Satellites to perform the build. In the latter case, the triggering user is inferred via commit metadata. The triggering user does not have to be a user registered with Earthly. In some cases, if the triggering user cannot be inferred from commit metadata, then the user logged into Earthly CLI in the CI run is used as the triggering user. If you would like to estimate the number of users that a project has according to how we track users, please check out the github.com/earthly/lib/billing+active-users target.

In the BYOC plan, Satellites will automatically enter a sleep state when they have been inactive for at least 30 minutes. This state is shown in the Earthly CLI when you list or connect to your satellites. If a build is started while a Satellite is in a sleep state, the Earthly backend will automatically wake the instance back up before allowing the build to start. Note that this feature is unavailable in the Self-Hosted plans.

The number of satellites you need depends on the workload they need to handle. For maximum performance, you can create a different satellite for each CI pipeline. This may be overkill for some setups though, where CI pipelines are small. The best method to determine the number of satellites you need is to start with one or two and add more as needed. Earthly prints information on build startup about how loaded the Satellite is currently. This can be used as a guide to determine if more Satellites are needed. You can read more about tuning your satellites in our best-practices guide.

Self-Hosted satellites are deployed using our official Docker image. You can run this image as a container in your own infrastructure, such as on a dedicated VM or as a Pod in a Kubernetes cluster. See our Self-Hosted Satellites documentation for more details.