Sign up for Chainguard Starter

Chainguard Starter is Chainguard’s free self-serve plan. You sign up with chainctl starter init, which creates a Starter organization for you and, optionally, adds your first images. This page covers signing up, adding images, joining an organization that already exists, and signing up from a script or a coding agent.

Before you begin

You need the following:

• chainctl 0.2.394 or later. To install it, refer to How to install chainctl. To update an existing installation, run sudo chainctl update, or brew upgrade chainctl if you installed it with Homebrew.
• A verified email address on one of these accounts: GitHub, GitLab, Google, or an email-and-password account. For GitHub and GitLab, Chainguard uses the account’s primary email address.

Use a business email address if you plan to invite colleagues. With a business address, Chainguard names your organization after your email domain, and you can invite people whose addresses are in that domain. A personal email address, such as a Gmail address, creates an organization that isn’t tied to any domain and can’t invite anyone until it upgrades to Chainguard Team.

Sign up

To create a Starter organization, complete the following steps:

1. Run chainctl starter init:

   chainctl starter init

2. Choose an identity provider from the menu. chainctl offers to save your choice for later chainctl auth login runs. chainctl starter init shows the menu each time unless you add --social-login.

3. Sign in using the browser window that opens. You have 5 minutes to finish.

4. Answer the questions about your name, company, job title, and whether you want updates from Chainguard. Before the questions, chainctl prints the terms and privacy notice that you agree to by continuing.

5. If you signed in with a personal email address, enter a name for your organization. The name can’t look like a domain name.

chainctl creates your organization and prints its name and ID. Chainguard then sets up the organization’s access to images, which usually takes a few minutes.

To add images as part of signing up, list them with --images. For example, the following command signs in with GitHub and adds the nginx and redis images once the organization is ready:

chainctl starter init --social-login github --images nginx,redis

Add images

A Starter organization can access up to five images. To find image names, browse the Chainguard Directory. To add images after you sign up, run chainctl starter add-images with one or more image names:

chainctl starter add-images nginx redis

Once you add an image, you can’t swap it for another one. When all five slots are used, chainctl starter status says so and suggests upgrading to Chainguard Team with chainctl plans update --plan team. To add a Helm chart, use chainctl images helm add-chart. Each image the chart needs that your organization doesn’t already have uses one of the five slots. Refer to Self-serve Helm charts.

To check whether your images are ready to pull, run chainctl starter status. It shows your organization’s registry path, how many images you’ve added, and each image’s state. An image shows INITIALIZING until it’s ready to pull, then READY.

chainctl starter status

When an image is ready, pull it from your organization’s registry path, which chainctl starter status shows on its Registry: line, such as cgr.dev/example.com. Replace $REGISTRY with that path:

docker pull $REGISTRY/nginx:latest

An organization created with a personal email address has no domain, so its registry path uses the organization’s ID instead of a name.

To pull from CI pipelines, create a pull token. Refer to Authenticate CI pipelines with a pull token.

Join an existing organization

If your company already has a Starter organization for your email domain, chainctl starter init can’t create a second one. Ask to join the existing organization instead:

1. Sign in to Chainguard with your business email address:

   chainctl auth login

2. Request access:

   chainctl starter request-access

Chainguard emails the request to the organization’s owners, who decide whether to invite you. For privacy, the command responds the same way whether or not an organization exists for your domain.

Sign up from a script or a coding agent

chainctl starter init can run without prompts, which lets a script or a coding agent run it for you. You still sign in yourself in the browser.

Pass --non-interactive with a flag for each question:

chainctl starter init --non-interactive --social-login google \
  --given-name Ada --family-name Lovelace --company Acme --job-title Engineer \
  --output json

With --non-interactive, the command never prompts. If a required flag is missing, it fails and names the flags it needs. A missing --email-updates counts as no. If you sign up with a personal email address, also pass --name.

With --output json, the command writes progress to standard error and writes one JSON object to standard output. The object includes the outcome, the organization’s ID and name, the images it added, the next command to run, and the error, if any. If the identity you signed in with already belongs to an organization, the object also includes organizations, the organizations it belongs to; identity, the email address it signed in with; and hint, what to do instead.

The command exits with one of the following codes:

Have a person accept the terms

When a coding agent signs up for you, add --terms-step so that you, not the agent, accept the terms. This flag needs chainctl 0.2.397 or later.

With --terms-step and --output json, the JSON object also includes the following fields:

• terms: the statement to accept and the documents it refers to.
• plan: what the Starter plan includes and excludes. The list can include limits that Chainguard doesn’t enforce yet. For the current limits, refer to Chainguard plans.
• human_step: the step that only a person can take. Its command field holds the command that accepts the terms.

Once the organization exists, human_step names the command that accepts the terms, and next is empty, so the agent has nothing to run. With chainctl releases before 0.2.399, next names the command instead. An owner of the organization reads the terms and runs the command. Replace <organization-id> with the ID from the JSON’s organization field:

chainctl starter accept-terms --parent <organization-id>

The command prints what the Starter plan includes, then the terms, and asks you to accept them. Without an interactive terminal, add --yes; using it means you agree to the terms. Running the command again after the terms are accepted changes nothing.

Next steps

• Compare what Starter and Team include in Chainguard plans.
• To use Chainguard Checks and Chainguard Workspaces, refer to Set up Chainguard Checks and Chainguard Workspaces.