---
sidebar_label: Craft a scope
doc_id: 4ba778bf-933d-477c-909d-8aef74f9bce7
description: >-
  Build your own agent-backed scope from scratch: understand the core concepts,
  define specifications, implement lifecycle actions, and register for use.
keywords:
  - agent-backed scopes
  - scope specification
  - lifecycle actions
  - scope registration
  - craft scope
---

# Craft a scope from scratch

When the built-in scope types don’t fit your workload, you can build your own. This section walks you through defining a scope specification, implementing lifecycle actions, and registering the scope so developers in your organization can use it.

## How it works

Agent-backed scopes run using the [nullplatform agent](/docs/agent/overview), which lives inside your infrastructure (for example, a Kubernetes cluster) and listens for actions.

1. You define your scope using a **specification** and a set of lifecycle **actions**.
2. The scope is registered with your organization.
3. The agent listens for matching actions and sends them to your **runner**.
4. The runner provisions infrastructure or executes commands as needed.

```mermaid
graph LR
  subgraph nullplatform
    nullAPI[nullplatform API]
  end

  subgraph client_infrastructure
    subgraph cluster
      agent[nullplatform agent]
    end
  end

  agent -- communicates with --> nullAPI
```

## Key concepts

### Scope specification

A scope specification defines the structure of your scope: its name, category, visibility, accepted parameters, and input schema. Think of it like a class definition. The scopes you create from it are the instances.

```json
{
    "name": "My scope name",
    "slug": "my-scope",
    "type": "scope",
    "visible_to": [
        "organization=1:account=2"
    ],
    "attributes": {
        "schema": {
            "type": "object",
            "required": ["warmup"],
            "properties": {
                "asset_type": {
                    "type": "string",
                    "export": false,
                    "default": "docker-image",
                    "readOnly": true
                },
                "warmup": {
                    "type": "boolean",
                    "export": false,
                    "readOnly": false
                }
            }
        },
        "values": {}
    },
    "selectors": {
        "category": "Deployment Services",
        "imported": false,
        "provider": "AWS",
        "sub_category": "Agent backed scope"
    }
}
```

### Lifecycle actions

Actions define what you can do with a scope. Each action is defined through an **action specification**, which outlines its parameters and expected behavior. Scopes support standard actions (`create`, `update`, `delete`) and custom actions like `rollback` or `switch_traffic`.

```json
{
    "name": "Create a scope",
    "type": "create",
    "parameters": {
        "schema": {
            "type": "object",
            "required": ["scope_id"],
            "properties": {
                "scope_id": {
                    "type": "string"
                }
            }
        },
        "values": {}
    },
    "results": {
        "schema": {
            "type": "object",
            "properties": {}
        },
        "values": {}
    }
}
```

:::warning Actions and action specs are different things
A scope specification is like a class, and a scope is like an instance. Similarly, an action specification defines the shape of an action, and a concrete action is an instance executed through a runner.
:::

### Visibility

You can limit which users or teams can use your scopes by setting visibility based on [NRN](/docs/NRN)s. This lets you control scope availability across different parts of your organization.

## Summary

| Entity               | Description                                                                                                                   |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Scope specification  | Defines the name, category, visibility, and parameters for the scope it defines. |
| Action specification | Defines the type (create, update, delete, custom) of actions along with its parameters.                                            |
| Action               | An action instance executed through a runner to manage the scope’s lifecycle.                                                 |

## Next steps

- [Scope specification](/docs/agent-backed-scopes/craft-scopes/scope-spec): define your scope’s structure, parameters, and visibility
- [Action specifications](/docs/agent-backed-scopes/craft-scopes/scope-action-spec): set up lifecycle and custom actions
- [Register your scope](/docs/agent-backed-scopes/craft-scopes/register-scope): make the scope available in your organization
- [Override workflows](/docs/agent-backed-scopes/overrides): customize existing scope behavior