> For the complete documentation index, see [llms.txt](https://docs-lunar.earthly.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-lunar.earthly.dev/install/lunar-hub/dedicated/overview.md).
# Overview
Lunar Dedicated is a fully managed, single-tenant Lunar install. Earthly provisions, operates, and upgrades it end-to-end in an AWS account dedicated to you, and you reach it over private networking or, where your CI can't, over the internet. It's for teams that want Lunar's guardrails without running the [Hub](/install/lunar-hub/self-hosted/overview.md) themselves.
This page explains how it works, who it fits, and what Earthly needs from you to stand one up. [Setup](/install/lunar-hub/dedicated/setup.md) is the hands-on companion covering what your team actually does.
{% hint style="info" %}
Lunar Dedicated is a managed offering, distinct from the self-hosted [Lunar Hub](/install/lunar-hub/self-hosted/overview.md). With Dedicated, Earthly runs the infrastructure; with the self-hosted Hub, you do. The CLI and CI tracer are installed and configured the same way in both.
{% endhint %}
## How it works
```mermaid
flowchart LR
Git["GitHub / GitLab"]
subgraph Earthly["Earthly (management account)"]
Mgmt["Deploy and operate tooling"]
end
subgraph Dedicated["Your dedicated AWS account"]
Hub["Lunar Hub"]
WH["Webhook listener"]
Data[("Postgres · S3 · secrets")]
Hub --> Data
end
subgraph You["Your network"]
CI["CI runners · Lunar CLI"]
end
Mgmt -- "assume-role (IAM)" --> Dedicated
CI -- "internet or PrivateLink —
you choose" --> Hub
Git -- "webhooks" --> WH
```
* **One dedicated AWS account.** The strongest isolation AWS offers: a hard billing and security boundary, with nothing else running inside it.
* **Earthly operates it by assuming an IAM role.** Management is identity-based, so Earthly needs no VPN or peering to run your install.
* **You choose how the hub is reached.** Over the internet on your own hostname, behind TLS and token authentication, or privately over [PrivateLink](/install/lunar-hub/dedicated/privatelink-inbound.md). Joining the two networks directly (peering / Transit Gateway) is [coming soon](#how-you-connect). Whether the webhook listener stays public depends on where your Git platform lives: a cloud-hosted one delivers from the internet, while a platform in your own network can deliver privately.
* **Your data stays in the install.** Authoritative state (Postgres), run inputs and outputs (S3), and secrets all live in your dedicated account and region. Earthly stores none of your data centrally.
* **Earthly manages the whole lifecycle.** Provisioning, version upgrades, patching, and monitoring, on a [maintenance schedule](#maintenance-and-upgrades) you choose.
## Requirements
Lunar Dedicated fits cleanly when the following are true:
| Requirement | Detail |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Reachable CI** | The Lunar CLI and [CI tracer](/install/ci-tracer/github-actions-self-hosted.md) must run somewhere that can reach the hub. With internet access that's anywhere, including GitHub-hosted runners; with private access it means self-hosted runners in your network, or runners with VPN/PrivateLink access. On GitLab there is no tracer to place ([tracing is coming soon](/install/ci-tracer/gitlab-ci.md)), but the CLI still needs that reachability. |
| **A network to connect from** (private access only) | An AWS VPC that can reach a PrivateLink endpoint. Not needed if you reach the hub over the internet. |
| **An outbound allowlist you can permit** | The install needs egress for operational telemetry, container image pulls, and AWS APIs. |
| **A single region** | Each install lives in one AWS region. |
| **Git platform credentials** | On GitHub, a [GitHub App](/install/git-platforms/github.md) you create and install on the org(s) and repositories Lunar should monitor. On GitLab, a [group access token](/install/git-platforms/gitlab.md#authentication) per top-level group. If your instance is self-managed and not reachable from the public internet, Lunar also needs a [private path to it](/install/lunar-hub/dedicated/privatelink-outbound.md). |
{% hint style="info" %}
**Coming soon.** Joining your network to the install directly (VPC peering or Transit Gateway), connecting privately with no existing AWS footprint (site-to-site VPN), and multi-region installs are on the roadmap.
{% endhint %}
{% hint style="info" %}
**Need a fully air-gapped, no-egress install?** Dedicated isn't air-gapped; it requires outbound egress to operate. For an air-gapped environment, the [self-hosted Lunar Hub](/install/lunar-hub/self-hosted/overview.md) is a better fit. [Book a demo](https://earthly.dev/book-demo/) to work with us.
{% endhint %}
## How you connect
Two ways to reach your hub are available today, with a third on the way. PrivateLink is the one Earthly recommends wherever your CI can use it; the deciding factor is usually where your CI runs.
| | **Internet** | **PrivateLink** | **Joined network** (peering / Transit Gateway) |
| -------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------- |
| Availability | Available now | Available now | **Coming soon** |
| What it is | The hub on your own hostname, behind TLS and token authentication | A private one-way "door" from your network to the hub | Your network and the install's network are routed together |
| Reaching the hub | From anywhere, including GitHub-hosted runners | Through one private endpoint you create | Over the joined network, at a private address |
| Address coordination | None | None (address ranges can overlap freely) | Address ranges must not overlap |
| Your setup effort | None | Create one endpoint and two DNS records | Accept the join and add routes (usually your networking team) |
| Best when | Your CI runs on shared hosted runners, which can't reach a private endpoint | **Recommended.** Your CI runs in a VPC you control | You already run a Transit Gateway |
{% hint style="info" %}
Your install reaches outwards as well as inwards. The Hub calls your Git platform to read repositories, register webhooks, and post results; collectors, catalogers, and policies run *inside* your install and reach the systems they gather data from. For a dedicated customer any of those may be internal: a self-managed GitHub Enterprise Server or GitLab instance, registries, ticketing, internal APIs. That's why connectivity is two-way, and why onboarding asks where your CI runs and what your install needs to reach.
{% endhint %}
The two directions are set up independently, and you may need only one of them:
* **Reaching the hub**: how your CI runners, CLI users, and browsers get to your install. Choose from the options above. Over the internet there's nothing for you to do; PrivateLink needs one interface endpoint and two DNS records from you, covered in [PrivateLink to Your Hub](/install/lunar-hub/dedicated/privatelink-inbound.md).
* **Lunar reaching your internal systems**: needed if anything your install must reach sits off the public internet, such as a self-managed Git platform or an internal registry, ticketing system, or API. You publish each target as a PrivateLink endpoint service; see [PrivateLink to Your Internal Systems](/install/lunar-hub/dedicated/privatelink-outbound.md). **This one has a long lead time, so start it first.**
## What Earthly needs from you
These answers shape your install:
| What | Why |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Region** | Where the install (and your data) lives |
| **Hub access** | Internet or PrivateLink, and where your CI runs. Say so if you would rather join networks directly, so Earthly can tell you where that sits on the roadmap |
| **Internal targets** | Whether anything Lunar must reach sits off the public internet (a self-managed Git platform, or collector targets like internal registries, ticketing, or APIs), and if so, how many distinct hostnames. Drives [PrivateLink to Your Internal Systems](/install/lunar-hub/dedicated/privatelink-outbound.md), the longest-lead-time item in onboarding |
| **DNS** | Use Earthly's subdomain (`you.dedicated.earthly.dev`), or delegate a subdomain of your own (e.g. `lunar.yourco.com`) for Earthly to manage |
| **Git platform** | Which one, and where it lives: for [GitHub](/install/git-platforms/github.md), the App ID and installation ID plus the org(s)/repos it's installed on; for [GitLab](/install/git-platforms/gitlab.md), the top-level group(s) and, if self-managed, your instance hostname. The credential itself you [deposit](/install/lunar-hub/dedicated/setup.md#step-4-deposit-your-secrets) |
| **Sizing** | Rough org/repo count and CI volume, which maps to a t-shirt size (final sizing confirmed together) |
| **Maintenance windows** | A recurring weekly app window and a monthly infra window, in your timezone |
| **Contacts** | An operations contact (for maintenance notices) and a security contact (for incidents) |
| **WAF** (if required) | Whether your security review requires a web-application firewall in front of a public webhook listener. It isn't part of the standard install, so raise it and Earthly will scope it with you |
## Setup
Earthly handles initial provisioning and setup. This includes account creation, infrastructure provisioning, bringing up your hub, every upgrade (within your chosen window), version selection, monitoring, backup/restore, and clean offboarding.
However, we do need some help from your end.
### What you do
Summarized here; [Setup](/install/lunar-hub/dedicated/setup.md) has the commands and is the page to work from.
1. **Send your** [**questionnaire answers**](#what-earthly-needs-from-you)**.** Earthly replies with your coordinates packet (tenant, region, dedicated account ID, deposit role ARN, deposit ExternalId, and your webhook URL) and starts building.
2. **Start** [**private access to your internal systems**](/install/lunar-hub/dedicated/privatelink-outbound.md), if your Git platform or any collector target isn't on the public internet. Longest lead time in onboarding, so start it first.
3. [**Nominate your depositor account**](/install/lunar-hub/dedicated/setup.md#step-2-identify-your-depositor-account): the AWS account you'll deposit secrets from (there's a path for teams without one).
4. [**Set up your Git platform**](/install/lunar-hub/dedicated/setup.md#step-3-set-up-your-git-platform) and send Earthly the identifiers: on GitHub the App ID, installation ID, and org; on GitLab the top-level group(s) and your instance hostname if you're self-managed.
5. [**Deposit your secrets**](/install/lunar-hub/dedicated/setup.md#step-4-deposit-your-secrets): a \~30-minute terminal task once the packet and the credential exist. Secrets are written **directly into your dedicated account's** secret store through a write-only role, never through Earthly's systems.
6. [**Go live**](/install/lunar-hub/dedicated/setup.md#go-live): Earthly verifies the install end-to-end and hands over your access token, plus a Grafana login if your install is reachable over the internet; you load workload secrets, finish DNS if you delegated a subdomain, and create your inbound endpoint if you chose PrivateLink.
None of this needs a meeting; most teams have all of it ready before their first call with Earthly.
## Maintenance and upgrades
The Earthly team manages Lunar Hub updates for you; you choose *when* upgrades land. There are two recurring maintenance windows:
* **A weekly app window** for routine Lunar version bumps (a rolling hub restart).
* **A monthly infra window** for node patches, add-on updates, and the occasional infrastructure upgrade.
Every Dedicated install runs the hub redundantly, so routine upgrades roll through without taking the service down; expect at most a brief interruption as connections move. Planned windows are excluded from the uptime clock. Critical security patches and forced version deprecations can land out-of-window, with notice.
**On GitLab, one recurring task stays with you.** Group access tokens carry a fixed expiry, and there is no overlap period where old and new both work. Create the replacement in GitLab and [deposit it](/install/lunar-hub/dedicated/setup.md#step-4-deposit-your-secrets) ahead of the expiry date, using the same command as at setup, then revoke the old one. See [expiry and rotation](/install/git-platforms/gitlab.md#expiry-and-rotation). If a token lapses, Lunar stops posting results and stops reacting to webhooks for that group. GitHub App credentials do not expire this way.
## Security and data
How a Dedicated install handles isolation, data, secrets, and audit:
* **Exclusive, isolated account.** Your install runs alone in a dedicated AWS account, with no other workloads.
* **Data residency.** Authoritative state (Postgres), run inputs/outputs (S3), and secrets all live in your dedicated account and region. Earthly stores none of your data centrally.
* **Secrets are encrypted at rest, and Earthly never holds them.** You [deposit](/install/lunar-hub/dedicated/setup.md#step-4-deposit-your-secrets) your Git platform credential (the GitHub App private key, or the GitLab group access token) into your install's own secret drop over a write-only role, and your workload secrets (API keys) go straight to your hub via the CLI. Neither passes through Earthly's central systems, and both live encrypted inside your install.
* **Full audit visibility.** Every action Earthly's roles take is recorded in AWS CloudTrail.
* **Defined data lifecycle.** Run inputs and outputs are retained 30 days. On exit, Earthly returns your data (a portable database dump plus your storage buckets) and **provably deletes** the install by destroying its encryption keys, with the deletion recorded in CloudTrail.
* **Operational telemetry is required.** The install sends metrics and logs back to Earthly so it can monitor the install and meet the SLA. This covers operational data only (never your source code, data, or secrets), and Earthly details exactly what it includes in your security review. If you need telemetry fully off, the [self-hosted Lunar Hub](/install/lunar-hub/self-hosted/overview.md) is a better fit; [book a demo](https://earthly.dev/book-demo/).
{% hint style="warning" %}
**Custody is audited.** Your secrets are encrypted with a key that lives inside your account and is readable only by the hub. Routine operation can't read your secrets, and any access that could is a deliberate, audited action. It is not a cryptographic guarantee that Earthly *cannot* read them. If you need hard zero-knowledge, the [self-hosted Lunar Hub](/install/lunar-hub/self-hosted/overview.md) is the better fit; [book a demo](https://earthly.dev/book-demo/).
{% endhint %}
## What's included
* A single-tenant, fully managed Lunar install in a dedicated AWS account
* Hub access over the internet, or privately via PrivateLink
* A redundant hub, so planned upgrades roll through without downtime
* A single region per install
* Full lifecycle management: provisioning, upgrades, patching, monitoring, backup/restore, and clean offboarding
## Next steps
[Setup](/install/lunar-hub/dedicated/setup.md) is where your team picks it up: the questionnaire, your depositor account, your Git platform credential, and the secret deposit.
If anything Lunar must reach sits off the public internet, such as a self-managed Git platform or a collector target, start [PrivateLink to Your Internal Systems](/install/lunar-hub/dedicated/privatelink-outbound.md) in parallel. It's the longest-lead-time item in onboarding.
Earthly is also glad to walk through the model live, answer your security team's questions, and map out what onboarding looks like for your environment.
Book a demo
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs-lunar.earthly.dev/install/lunar-hub/dedicated/overview.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.