Running Argo CD core without the API server or UI

Argo CD core runs the controllers without the API server or UI for single-team cluster administration. This page covers what core-install.yaml leaves out, how to manage Applications with kubectl and the CLI, and when to move to the full install.

On this page

When a headless Argo CD core install fits a cluster administrator

A cluster administrator who wants GitOps reconciliation without multi-tenant access should consider the core install, the headless variant of Argo CD built from core-install.yaml. Core runs without the API server and without the web UI, and it is intended for teams that do not need multi-tenancy. The installation guide describes it as installing lightweight, non-HA components, so it suits a single operator managing a small set of clusters, a lab, or a platform team that drives Argo CD from Git and the command line. If several teams need their own views, approvals, or self-service sync, plan for the full install instead.

The main trade-off is what you give up. Without the API server there is no argocd-server for browser access or the gRPC endpoint the CLI normally uses against a running server, so day-to-day work moves to kubectl against Application and AppProject resources, and to the argocd CLI in core mode. Without the high availability manifests, there is one replica of each component and no redundancy. Confirm in the installation guide which components the core manifest actually includes before you size the cluster, and check whether your own workflows, such as notifications or external dashboards, assume the API server is present.

Decide the boundary before you install. Ask whether any future team will need SSO, per-team projects with RBAC, or a UI for others to inspect applications. Those needs are the signal to move to the full install, and migrating later means reviewing the official installation guide for the component differences and re-homing your Application definitions. Record that decision in your change records so auditors and successors can see why the control plane is minimal.

What core-install.yaml leaves out compared with the full install

The core installation does not run the argocd-server component, which serves the web UI and the API that the argocd CLI uses when it connects to a server. Administration moves into Kubernetes objects. Teams create and change Application, AppProject and ApplicationSet resources with kubectl, and they read status from the same objects.

  • No web UI: There is no dashboard for sync status, diffs or history. Operators read state with kubectl get applications -n argocd and the status fields on each Application.
  • Limited CLI behavior: Commands that depend on a logged-in server session do not apply. Confirm which argocd subcommands work in core mode for your CLI version.
  • Change path is Git or kubectl: Anyone with write access to Argo CD objects in the cluster can change what is deployed, so that access must be controlled through Kubernetes RBAC.
  • Integrations need rework: Webhooks, CI jobs and external tools that call the server API must be redesigned to work through Kubernetes objects.
  • Notifications and status paths: Confirm which notification and status features depend on the API server in your version.

Before you choose core, list every pipeline and tool that calls the Argo CD API and confirm each one has a Kubernetes-based alternative.

Choosing between core, the full install and HA manifests

This table compares core-install.yaml, the standard install and the HA manifests across access model, UI and API availability, SSO, multi-team RBAC and recommended use. Read each column as one install choice, and use the HA row to check whether your cluster has the three nodes the HA manifests require. The main takeaway is that core trades user-facing access for a smaller footprint, so it fits administrators who work through Git, kubectl and the CLI.

AspectCore (core-install.yaml)Standard installHA manifests
Access modelHeadless, no API server or UI; administrators manage applications with kubectl and the CLI on the clusterIncludes the API server, UI and CLI access for usersSame access model as the standard install, with components replicated for availability
UI and API availabilityNo web UI and no API serverWeb UI and API server includedWeb UI and API server included, run as redundant replicas
SSONot applicable without the API server; sign-in for people is not part of this modelSupported through bundled Dex or a direct OIDC providerSupported through bundled Dex or a direct OIDC provider
Multi-team RBACNot designed for multi-tenancy; access control relies on cluster permissionsProjects and RBAC for separating teamsProjects and RBAC for separating teams, as in the standard install
High availabilityLightweight, non-HA componentsNon-HA componentsRequires at least three nodes because of pod anti-affinity rules
Cluster size requirementSuits a small, single-administrator footprint; confirm capacity for your clusterRuns on a smaller footprint than HA, with no node minimum stated in the install guidePlan for at least three nodes; IPv6-only clusters are not supported
Recommended useSingle-administrator clusters that do not need multi-tenancyTeams that need a UI, API access or shared usersProduction environments that need redundancy across nodes
Move-up pathMove to the standard install when people need the UI, API or SSOMove to HA manifests when availability and node count support itAlready the target for high-availability needs

How to install core and manage Applications without the UI

This sequence produces a headless Argo CD control plane on a cluster you administer, with repository access defined as a Secret and Applications managed from Git-backed manifests using kubectl and the CLI.

  1. Confirm the target version and upgrade notes

    The cluster administrator chooses the Argo CD minor version to run and reads its release notes before anything is applied. Check the release process page for which minor versions still receive patch releases, and read the GitHub releases page for the current patch level of each supported line. Confirm you are not moving between major versions without the official upgrade notes, since RBAC scope and resource tracking changed in 3.0. You know this step is done when you have written down one exact version tag and its upgrade notes are reviewed.

  2. Apply core-install.yaml to a dedicated namespace

    The administrator creates a namespace for Argo CD and applies the core installation manifest from the matching release tag, pinned to the version chosen in the previous step. The core manifest omits the API server, the web UI and the bundled Dex, and installs lightweight, non-HA components, so it suits clusters without multi-tenant access needs. Confirm the manifest URL and tag against the installation guide before running the command. You know this step is done when the apply command returns without errors for every resource in the manifest.

  3. Verify the controller pods are running

    Check that the application controller, repo server and Redis pods reach the Running state in the Argo CD namespace, and that the Argo CD custom resource definitions are present on the cluster. Review controller logs for repository or cluster connection errors, which usually point to missing outbound network routes or DNS problems. Because the core install is non-HA, expect single replicas and plan for a restart window during any future upgrade. You know this step is done when every pod reports ready and the controller logs show no startup errors.

  4. Register the Git repository as a Secret

    Since Argo CD 3.0, repositories cannot be defined in the argocd-cm ConfigMap, so the administrator creates a Kubernetes Secret labeled as a repository in the Argo CD namespace, holding the repository URL and read credentials. Use a deploy key or a token scoped to read-only access on the repositories that hold manifests, and avoid embedding long-lived personal credentials. Store the Secret manifest outside the repository it describes, and confirm secret handling is covered by your own change process. You know this step is done when the repository is listed as connected through the CLI or the controller logs show a successful repository fetch.

  5. Create Applications as manifests

    The administrator writes each Application as a declarative manifest that points at a repository path, a target revision and a destination cluster and namespace, and commits it to Git. Setting the destination to the local cluster and an explicit namespace keeps the scope narrow when no project boundaries are in use. Review the sync policy before enabling automated sync, because automated pruning deletes resources that were removed from Git. You know this step is done when the Application manifest is applied with kubectl and the controller reports it in the Argo CD namespace.

  6. Sync and inspect with kubectl and the CLI

    The administrator triggers a sync with the Argo CD CLI, or waits for automated sync, and inspects the result with kubectl get applications and the CLI status and diff commands. Without the UI, the CLI and Application status fields are the primary view of health, sync state and drift, so confirm that operators know these commands before relying on them. Confirm the CLI can reach the controller through the Kubernetes API in this mode, since the core install does not expose the API server endpoint that the full install provides. You know this step is done when the Application reports Synced and Healthy and the deployed resources match the Git revision.

Managing Applications with kubectl and the CLI without a UI

In a headless Argo CD core install, the Application resources are the unit of work, and they are ordinary Kubernetes objects in the argocd namespace. Teams define them with kubectl apply for quick changes, but for anything that must survive a rebuild, the durable source should be a Git repository holding the Application manifests, reviewed and merged like any other change. Ad hoc kubectl edits to a live Application will be reverted or drift from Git, so decide early which path is authoritative and write it down for every administrator who touches the cluster.

The argocd CLI can still drive sync, refresh, rollback and status checks, but it reaches the Argo CD API server, and the core install omits that server and the UI. Whether the CLI works, and how you point it at the control plane, depends on what your chosen install exposes. Confirm this in the installation documentation before you script against it, and test the exact commands your runbooks depend on in a non-production cluster. Where the CLI cannot reach a server, many routine operations fall back to inspecting the Application objects with kubectl get and kubectl describe.

RBAC still matters even without a UI. Since the 2.14 to 3.0 change, update and delete permissions apply to the Application itself, and reading logs requires an explicit logs, get permission. Anyone with cluster access who can edit Applications, or read pod logs through Argo CD, holds those rights regardless of the interface. Review the Kubernetes RBAC bound to administrators, CI service accounts and operators, and confirm that the logs permission is granted only where it is needed.

Security risks that remain when there is no API server or UI

A headless install removes the web login and the API server, but the controller, repo-server and Redis still run with real privileges. The cards below cover the risks that stay in place and the checks to make before relying on a core install for production changes.

No UI means no SSO audit trail

Without the API server or UI, there is no SSO login for people to pass through, so changes are made with kubectl against the Argo CD custom resources or with a CLI session tied to the Kubernetes identity. The audit trail is only as good as the Kubernetes audit log on the cluster. Confirm who can create or patch Application resources, and whether those actions are recorded with a named human identity rather than a shared service account.

Disable the admin account

The built-in admin user is meant for initial setup. The user management documentation recommends disabling it with admin.enabled set to false once local users or SSO are configured. In a headless install, check whether the admin password secret still exists and who can read it. If no other login path exists, plan that step carefully so you do not lock yourself out of recovery access.

Repo-server runs untrusted content

The repo-server executes Helm and Kustomize against repository content. If a repository is untrusted, or a chart or overlay can reference files outside its tree, it can read or influence what gets rendered. Restrict which repositories are registered, review chart dependencies, and confirm that rendering runs with the least file access the workload needs. Headless mode does not change this exposure.

Credentials redacted, not removed

Argo CD redacts cluster, Git and OAuth2 credentials from API responses and logs. Redaction does not protect a secret that someone can read directly from the Kubernetes API. Repository credentials are stored as Kubernetes Secrets, so RBAC on the argocd namespace and on secret reads decides who can see them. Review those permissions and check that controller logs are not shipped to a wider audience than the cluster itself.

Controller holds cluster privilege

The application controller applies manifests to the clusters it manages, so its service account is effectively a privileged identity. Whoever can change an Application's source or destination can make the controller deploy into namespaces they could not reach directly. Limit cluster-scoped permissions to what your managed clusters need, and review which namespaces and repositories each Application may target before you grant write access to Application resources.

Patch only the latest minor versions

The release process states that only the three most recent minor versions receive patch releases, and a new minor ships four times a year. A headless install is still a running Argo CD, so falling behind leaves known issues unpatched. Record the version you run, subscribe to the GitHub releases page, and plan a minor upgrade on a fixed schedule rather than waiting for a security event.

Questions teams ask before running Argo CD core

Is Argo CD core cheaper to run than the full install?

Argo CD is released under the Apache License 2.0 and the project offers no paid edition, so the software itself carries no license fee. Your cost comes from the infrastructure that runs the controllers and the people who operate them. Core runs fewer components than the full install, which can reduce the cluster capacity it needs, but the savings are modest compared with the staff time spent on upgrades and access work. The main cost drivers are the number of clusters Argo CD manages, the number of Git repositories it reads, and how many people need to see application state through a UI or API. If your team is small and every change goes through Git, core may stay simple. Ask any partner for a quote that separates one-time setup from recurring upgrade, patching and support work.

How much effort do the install and upgrades need?

The initial install is a single manifest apply, but the ongoing work is what matters. The release process describes a minor release four times a year, and only the three most recent minor versions receive patch releases. That means you must plan an upgrade cycle and keep a test cluster ahead of production. Read the upgrade notes before each minor move. The 2.14 to 3.0 notes changed several defaults: update and delete RBAC now apply only to the application itself, logs access needs an explicit logs, get permission, and annotation-based resource tracking is the default. Repository definitions moved from the argocd-cm ConfigMap into Kubernetes Secrets. Budget engineer time for reading notes, testing each change and rolling it out, and confirm who owns that calendar.

Can our own team run Argo CD core without outside help?

A team can run core without outside help if it already operates Kubernetes in production, understands Git-based change control, and can manage cluster RBAC and secrets. Core removes the API server and UI, so the cluster itself becomes the main control point. Your engineers must be comfortable with kubectl, the Argo CD CLI in its core mode, and the Application and AppProject resources. Check three skills before you decide: writing RBAC rules for Application objects, handling repository credentials as Secrets, and running an upgrade with a rollback plan. If any of these are thin, a fixed-scope engagement can document the runbook and train your staff, and a retainer can cover upgrades. Ask for the written scope before work starts.

When should we move from core to the full Argo CD install?

Move to the full install when more people need to work with applications than cluster access comfortably allows. The triggers are usually several teams that need separate permissions, a UI for review and troubleshooting, programmatic access through the API for pipelines, or single sign-on for many users. The user management documentation recommends using the built-in admin user only for initial setup, then disabling it with admin.enabled set to false once local users or SSO are configured. Core does not give you that SSO path by itself, so plan the switch before audit or onboarding pressure arrives. Confirm how your identity provider, groups and projects will map to Argo CD roles before you migrate, because moving later means reviewing every existing permission.

Is Argo CD core suitable for production use?

Core can run in production when its access model matches your operating model, but the decision needs documented controls rather than an assumption. The security documentation says Argo CD authenticates API requests only with JSON Web Tokens and uses TLS for traffic between its own components. In core, the API server is absent, so your protection shifts to Kubernetes RBAC, network policy and the controls on the namespace where Argo CD runs. The repo-server runs Helm and Kustomize on repository content, so untrusted repositories and out-of-tree file access are a risk to manage. Restrict who can write Application objects and which repositories they can reference. Confirm with the installation guide which components core includes before you sign off on a production design.

How do we manage applications in core with kubectl and the CLI?

In core, applications are Kubernetes objects, so you create, inspect and change them with kubectl and the Argo CD CLI running in core mode. Each Application points to a Git repository, a path and a destination cluster. Argo CD reconciles the cluster to match the repository, so the Git history becomes your change record. Because there is no UI, operators need a shared procedure for checking sync status, reading events and handling a stuck sync. Write that procedure before go-live and test it with a deliberate failure. Confirm the exact core-mode commands and flags in the official installation guide for your release, since command behavior can change between minor versions.

What should a partner include in the written scope?

A partner should scope the work in writing before starting, because most engagements are fixed-scope and the quote follows from that document. Ask for these items: the target clusters and their network boundaries, the Git repositories and how credentials will be stored, the access model for operators and automation, the install method and version pinning, backup and recovery steps for Argo CD's own configuration, and the upgrade process for the three supported minor versions. Ask whether the scope covers documentation, handover training and acceptance testing. Ongoing upgrades, patching and continuous testing are available as retainers, so separate those from the build. DeployOpen does not publish a price list. It prepares systems and evidence for compliance reviews, but independent auditors issue any audit reports.

How DeployOpen scopes and supports a core Argo CD install

DeployOpen is a Chainscore Labs company that plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure. For a core Argo CD install, we start by confirming that a headless controller really fits your cluster administration model, then build and hand over the install against a written scope.

How we scope

  • Confirm whether the team needs no UI, API server or multi-tenant access before choosing core over the full install.
  • Record which clusters, Git repositories and Helm or Kustomize sources the controller will reconcile.
  • Agree the written scope, deliverables and timeline in advance. Most engagements are fixed-scope.

How we build

  • Install the core manifests into your cluster and define applications as declarative resources under version control.
  • Set repository and cluster credentials as Kubernetes Secrets, and confirm RBAC on the cluster for the controller.
  • Test reconciliation, drift detection and sync behavior with kubectl and the CLI before any production application is added.

How we hand over

  • Document the decision record for core versus the full install, including what the UI and API server would have provided.
  • Provide runbooks for adding applications, rotating credentials and running manual syncs with kubectl and the CLI.
  • Walk your administrators through the migration path to the full install, so the change later is planned rather than improvised.

How we support

  • Ongoing support, version upgrades and continuous testing are available as a retainer after handover.
  • Plan reviews of the Argo CD release cadence with your team, so patch versions stay within supported minor releases.
  • Confirm with the Argo CD project and your own environment which features are available in the version you run.

Sources and further reading

Talk to our team.

Tell us what you're working on, whether it's a deployment, an audit, a security test or a cyber range. You'll speak with an engineer who can help you scope it.

  • 30-minute call: free, with no obligation.
  • NDA on request: we can sign before you share details.
  • Clear next steps: a scope and plan after the call.