---
sidebar_label: Install a package
toc_max_heading_level: 3
doc_id: 7f4fc24f-b965-4a90-90c0-8d0bfd854d26
description: >-
  How to install a published service or scope package in your organization with
  the tofu-modules, pin a release, upgrade, coexist with a copy you registered,
  and decide when to fork instead.
keywords:
  - package installation
  - service_package_installation
  - scope_package_installation
  - global packages
  - tofu-modules
  - fork a service
title: Install a package
canonical: 'https://docs.nullplatform.com/docs/packages/install'
---
# Install a package

Installing a package touches the same layers as registering a service or a scope yourself, and only the nullplatform layer changes: instead of registering a copy of the specification, you install the package. This page covers both kinds, with the [tofu-modules](https://github.com/nullplatform/tofu-modules) that do the work.

## Before you start

You need an agent that will run the package's worker, with `public.ecr.aws/nullplatform/*` among its `worker.allowedRegistries`, and a cloud provider configured at the NRN where you install or above it. Each package's repository README lists what else it needs, such as a state bucket or an environment variable on the agent.

## The three layers

| Layer | What you create | Where it comes from |
|---|---|---|
| Infrastructure | The cloud permissions the worker uses, usually an IAM role | The package's repository, as a `requirements` module |
| nullplatform | The installation and the agent channel; for a scope, also the scope type and its settings | tofu-modules' `service_package_installation` or `scope_package_installation` |
| Bindings | The role under the selector the package expects, in your IAM provider | Your providers |

The repository README of each package tells you the inputs of its requirements module and the selector its worker looks for.

The installation itself is one API call: the modules send a [POST request](/docs/api/package-installation-create) to `/package_installations` with the NRN, the package and the revision of the version you pin.

## Pick one release

Pick one release of the package's repository and use its version everywhere a version goes: the requirements module, the installation and, for a scope, the templates. The cloud permissions are the ones the worker of that same release expects, so mixing releases surfaces at runtime, as a failed action. The latest release is on the repository's releases page, and the package's versions are visible in **Platform settings**. Through the API, a [GET request](/docs/api/package-list) to `/packages` with `visible_to` and `slug` finds the package, and [its revisions](/docs/api/package-revisions-list) list every version.

## Install a service

```hcl
# ── infrastructure layer ─────────────────────────────────────────────
module "my_service_requirements" {
  source = "git::https://github.com/nullplatform/<repository>.git//<service>/specs/requirements/aws?ref=vX.Y.Z"
  # the inputs its README lists
}

# The agent role must be allowed to assume it: add it to the assume_role_arns
# of tofu-modules' infrastructure/aws/iam/agent.
#   assume_role_arns = [..., module.my_service_requirements.permissions_role_arn]

# ── nullplatform layer ───────────────────────────────────────────────
# For a service the installation is the whole nullplatform side, channel included.
module "my_service" {
  source = "git::https://github.com/nullplatform/tofu-modules.git//nullplatform/service_package_installation?ref=v9.16.0"

  nrn                  = "organization=1:account=2"
  package_slug         = "np-<slug>"
  package_version      = "X.Y.Z"                 # the same release, without the v
  agent_tags_selectors = { cluster = "runtime" } # must match the agent's TAGS
}

# ── bindings layer ───────────────────────────────────────────────────
# One aws-iam-configuration per NRN and dimensions: add the entry to the list
# your IAM provider already has.
#   { selector = "<selector>", arn = module.my_service_requirements.permissions_role_arn }
```

If you keep agent channels in a separate bindings layer, use `package_installation` in the nullplatform layer and `service_definition_agent_association` in bindings, with `package_slug` set to the package's slug.

## Install a scope

A scope package brings the specification and its actions. The scope type, the NRN settings and the scope configuration schema are yours, and `scope_package_installation` creates them from the templates of the same release.

```hcl
# ── nullplatform layer ───────────────────────────────────────────────
module "my_scope" {
  source = "git::https://github.com/nullplatform/tofu-modules.git//nullplatform/scope_package_installation?ref=v9.16.0"

  nrn             = "organization=1:account=2"
  np_api_key      = var.np_api_key # for the NRN settings
  package_slug    = "np-<slug>"
  package_version = "X.Y.Z"

  service_spec_name                = "<the scope type developers pick>"
  service_spec_description         = "<description>"
  service_path                     = "<scope>"
  repository_scope_template        = "https://raw.githubusercontent.com/nullplatform/<repository>/refs/tags"
  repository_scope_template_branch = "vX.Y.Z" # the same release
  create_scope_configuration       = true
  create_agent_channel             = false # the channel lives in your bindings layer
}

# ── bindings layer ───────────────────────────────────────────────────
module "my_scope_channel" {
  source = "git::https://github.com/nullplatform/tofu-modules.git//nullplatform/scope_definition_agent_association?ref=v9.16.0"

  nrn                      = "organization=1:account=2"
  tags_selectors           = { cluster = "runtime" }
  scope_specification_id   = module.my_scope.service_specification_id
  scope_specification_slug = module.my_scope.service_specification_slug
  service_path             = "<scope>"

  # The channel template, from the same release
  repository_notification_channel        = "https://raw.githubusercontent.com/nullplatform/<repository>/refs/tags"
  repository_notification_channel_branch = "vX.Y.Z"

  worker_orchestrator = true
  package_slug        = "np-<slug>"
}
```

The scope's settings go in a provider of the configuration schema the installation created; the repository README says which settings the scope reads.

## From a catalog of definitions

If your layers keep a catalog of `service_definition` or `scope_definition` entries, an installation is an entry of the same catalog that carries `package_slug` and `package_version` instead of a repository: a second module block, with the same `for_each` over those entries, points at `service_package_installation` or `scope_package_installation`. Their outputs have the names `service_definition` and `scope_definition` use, so the map your bindings layer reads keeps its shape.

## Already registered a copy?

If you registered the same service or scope yourself, you have a specification with the plain slug, such as `aws-s3-bucket`, and an agent channel filtered to it. The global package uses another slug, such as `np-aws-s3-bucket`, so both can live in one organization:

- Add the installation next to your `service_definition` or `scope_definition`. Its channel routes only the global slug, and your existing channel keeps serving your copy.
- Keep your IAM role: both specifications assume the role under the same selector, with the same permissions.
- Existing services and scopes stay on your copy: an instance can't move to another specification. Create new ones from the installed specification, and remove your copy and its channel once nothing uses them.

## Upgrade

Move the release in every layer where you pinned it: `ref` of the requirements module, `package_version` of the installation and, for a scope, the templates ref. On the nullplatform side, the module sends a [PATCH request](/docs/api/package-installation-update) that moves the installation's `default_revision_id`.

Instances created from the previous version keep running it. To move them, [roll out the version](/docs/packages/rollouts) in waves.

## Global package or your own fork

| | Global package | Your own fork |
|---|---|---|
| Specs and code | Maintained by nullplatform in the repository | Maintained by you, in your fork |
| What you install | The package, read-only | A package you publish in your organization, or a registered copy |
| Updates | A new release: move the version | Only when you merge upstream into your fork |
| When | Always, unless you need changes to the specification, the links, the actions or the workflows | Substantial changes: new actions or links, another specification, workflows that behave differently |

Use the global package. It's the only way to keep receiving fixes, features and security patches: each one arrives as a release, and you take it by moving the installed version. If something is missing or wrong, open an issue or a pull request in the repository, so every organization gets it.

Fork only to change what the service or scope is. A fork means you become the publisher of a different package: you build its worker image, publish it in your organization under your own slug, and maintain its specs, code and installation. Each repository README has the steps for its own fork.

### The shortcut, and why it's risky

The worker image nullplatform publishes is a global artifact, so a package of your own may pin it and change only the specs. It saves you the build, and it's the main trade-off to understand before taking it: the code in that image reads the specification it was released with, the attributes the form collects, the actions and their parameters, the links and what they export. Every change to your specs is a divergence the image doesn't know about, and the next release assumes specs you no longer have. A service or scope behaves as one thing because its specs and its code are released together. Take the shortcut only for changes the image can't see, such as descriptions, defaults within the same shape, or visibility.

### What a fork costs

Updates stop arriving unless you merge them yourself. There's no way back for existing instances, since they can't move to another specification. And you own the operations: images, releases and the compatibility of your specs with the agent.

## Next steps

- [Packages](/docs/packages): what a package is and how versions work
- [Roll out a version](/docs/packages/rollouts): move the services and scopes you already have to the version you upgraded to
- [Sample services](/docs/services/sample-services): the services nullplatform publishes as global packages
- [tofu-modules](https://github.com/nullplatform/tofu-modules): the modules used on this page, with their inputs and outputs
- [Package installation API](/docs/package-installation-api-index): install a package, move its version and list what's installed
