# Crew

A crew of the organisation's Belai library: a named set of worker agents a host runs together. Fields, YAML, HCL and CLI samples, and how apply treats it.

A crew of the organisation's Belai library: a named set of worker agents a host runs together. A crew's display name is unique in the library; a document naming a crew nobody declared adopts it. Members name agent profiles by their name, as the console's crew editor does; whether each exists and is a worker is checked by the host when it installs the crew. Every apply that changes it saves a new version; deleting the document hides the crew and keeps its versions.

| | |
|---|---|
| `apiVersion` | `vulnetix.com/v1` |
| `kind` | `Crew` |
| Group | [AI libraries](/platform-iac/kinds/catalogue.md#ai-libraries) |
| Status | **Served.** The [config engine](/platform-iac/reference/engine.md) plans and applies it. |
| Objects per tenant | many, keyed by `metadata.name` |
| Token and role | An owner, or a service account with the developer role (its ApiKey), or an Authentik access token for either. A member is refused with HTTP 403. See [Credentials for automation](/platform-iac/reference/config-api.md#credentials-for-automation). |
| Terraform resource | [`vulnetix_crew`](/platform-iac/terraform/resources.md#vulnetix_crew), imported by name (see [Terraform and OpenTofu](#terraform-and-opentofu)) |
| CLI | [`vulnetix config apply`](/platform-iac/cli/apply.md), CLI v3.168.0 and later. |
| Pinned schema | [`v1.19.1/Crew.schema.json`](https://github.com/Vulnesis/config-schemas/releases/download/v1.19.1/Crew.schema.json) |
| Newest schema | [`latest/Crew.schema.json`](https://github.com/Vulnesis/config-schemas/releases/latest/download/Crew.schema.json) |
| First released in | [`v1.6.0`](https://github.com/Vulnesis/config-schemas/releases/tag/v1.6.0) |
| Print the built-in copy | `vulnetix config schema Crew` |

## Minimal

Only the fields the kind requires. From `examples/Crew/minimal.yaml`.

**YAML**

```yaml
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/Crew.schema.json
apiVersion: vulnetix.com/v1
kind: Crew
metadata:
  name: review-crew
spec:
  members:
    - profile: reviewer
```

**HCL** (resource `vulnetix_crew`)

```hcl
# Only the arguments the kind requires. From config-schemas examples/Crew/minimal.yaml.

resource "vulnetix_crew" "review_crew" {
  name = "review-crew"
  members = [
    {
      profile = "reviewer"
    },
  ]
}
```

Every field that has a schema default, set to that default: [`terraform/crew.tf`](https://github.com/Vulnesis/platform-iac-examples/blob/main/terraform/crew.tf) and [`yaml/Crew.yaml`](https://github.com/Vulnesis/platform-iac-examples/blob/main/yaml/Crew.yaml) in [Vulnesis/platform-iac-examples](https://github.com/Vulnesis/platform-iac-examples).

**CLI** (applies it)

```bash
export VULNESIS_ORG_ID=...    # the organization UUID
export VULNESIS_API_KEY=...   # the ApiKey of a developer or owner service account
vulnetix config apply -f - --manager gitops:acme/platform --auto-approve <<'EOF'
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/Crew.schema.json
apiVersion: vulnetix.com/v1
kind: Crew
metadata:
  name: review-crew
spec:
  members:
    - profile: reviewer
EOF
```

## Advanced

Every field the kind supports, with a `when` expression where it takes one. From `examples/Crew/advanced.yaml`.

**YAML**

```yaml
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/Crew.schema.json
apiVersion: vulnetix.com/v1
kind: Crew
metadata:
  name: release-crew
  annotations:
    owner: platform-team
spec:
  displayName: Release crew
  description: Reviews, tests and writes the notes for every release branch.
  members:
    - profile: reviewer
      replicas: 2
    - profile: security-reviewer
  onePerRepo: true
```

**HCL** (resource `vulnetix_crew`)

```hcl
# Every argument the kind supports. From config-schemas examples/Crew/advanced.yaml.

resource "vulnetix_crew" "release_crew" {
  name         = "release-crew"
  description  = "Reviews, tests and writes the notes for every release branch."
  display_name = "Release crew"
  members = [
    {
      profile  = "reviewer"
      replicas = 2
    },
    {
      profile = "security-reviewer"
    },
  ]
  one_per_repo = true
  annotations = {
    owner = "platform-team"
  }
}
```

Every field that has a schema default, set to that default: [`terraform/crew.tf`](https://github.com/Vulnesis/platform-iac-examples/blob/main/terraform/crew.tf) and [`yaml/Crew.yaml`](https://github.com/Vulnesis/platform-iac-examples/blob/main/yaml/Crew.yaml) in [Vulnesis/platform-iac-examples](https://github.com/Vulnesis/platform-iac-examples).

**CLI** (applies it)

```bash
export VULNESIS_ORG_ID=...    # the organization UUID
export VULNESIS_API_KEY=...   # the ApiKey of a developer or owner service account
vulnetix config apply -f - --manager gitops:acme/platform --auto-approve <<'EOF'
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/Crew.schema.json
apiVersion: vulnetix.com/v1
kind: Crew
metadata:
  name: release-crew
  annotations:
    owner: platform-team
spec:
  displayName: Release crew
  description: Reviews, tests and writes the notes for every release branch.
  members:
    - profile: reviewer
      replicas: 2
    - profile: security-reviewer
  onePerRepo: true
EOF
```

## Fields

Paths use dots for nesting and `[]` for the items of a list. **Required** means required whenever the parent object is present. A default is what the server uses when the field is left out.

| Field | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|
| <span id="apiVersion"></span>`apiVersion` | string | yes |  | exactly `vulnetix.com/v1` | The document format version. Every kind in this release is vulnetix.com/v1. |
| <span id="kind"></span>`kind` | string | yes |  | exactly `Crew` | Always Crew. |
| <span id="metadata"></span>`metadata` | object | yes |  | no other keys |  |
| <span id="metadata-name"></span>`metadata.name` | string | yes |  | pattern `^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$` | The object's name, unique per kind within a tenant. It is the natural key: plan, apply, export and the Terraform provider all address an object by kind and name. |
| <span id="metadata-org"></span>`metadata.org` | string | no |  | format `uuid` | The tenant (organization UUID) the document belongs to. When set, plan and apply refuse to run against any other tenant. |
| <span id="metadata-labels"></span>`metadata.labels` | object | no |  | map of string to string (length 0 to 256); keys match `^[a-z0-9]([a-z0-9._/-]{0,61}[a-z0-9])?$` | Free key/value labels. Stored with the object, never interpreted by the server. |
| <span id="metadata-annotations"></span>`metadata.annotations` | object | no |  | map of string to string (length 0 to 4096) | Free key/value notes for people and tools, such as a ticket link. |
| <span id="spec"></span>`spec` | object | yes |  | no other keys |  |
| <span id="spec-displayName"></span>`spec.displayName` | string | no |  | pattern `^\S(.*\S)?$`; length 1 to 128 | The crew's name in the library: one line of at most 128 characters, not starting belai:. Defaults to metadata.name. |
| <span id="spec-description"></span>`spec.description` | string | no |  | length 0 to 500 | One line of at most 500 characters. |
| <span id="spec-members"></span>`spec.members` | array of object | yes |  | 1 to 8 items | The agents in the crew, 1 to 8. |
| <span id="spec-members-profile"></span>`spec.members[].profile` | string | yes |  | length 1 to 128 | The name of an agent profile in the library (its front matter name). |
| <span id="spec-members-replicas"></span>`spec.members[].replicas` | integer | no |  | 1 to 8 | How many copies of the agent run, 1 to 8. Left out, one. |
| <span id="spec-onePerRepo"></span>`spec.onePerRepo` | boolean | no |  |  | Run at most one copy of the crew per repository. |

## Applying this kind

- **Command.** `vulnetix config apply -f <file>`; the CLI line above says from which release. Plan first with [`vulnetix config plan`](/platform-iac/cli/plan.md): it shows each object as create, update, delete or no change, with a `planHash` that apply then holds to. Apply writes in one transaction.
- **Manager.** Each object records the manager that applied it (`terraform`, `console` or `gitops:<repo>`). `--prune` deletes only objects its own manager owns. See [The manager](/platform-iac/cli/plan.md#the-manager) and the [config engine](/platform-iac/reference/engine.md).
- **Status.** Applied, Unchanged or Deleted, with no other status fields. The phases the engine reports are explained under [status phases](/platform-iac/reference/engine.md#status-phases).

## How apply treats it

The canonical crew JSON is saved as a new version. Display names are unique in the library, and a document for a crew nobody declared adopts it. Members are checked by the host at install. Delete hides the crew.

## Terraform and OpenTofu

The resource is `vulnetix_crew` in the `vulnetix/resolve` provider. Its arguments are the `spec` in snake case, beside `name`, `labels` and `annotations` from `metadata`. The Minimal and Advanced HCL are above. The provider's own reference is [vulnetix_crew](https://registry.terraform.io/providers/vulnetix/resolve/latest/docs/resources/crew).

Import an object that already exists by its name:

```shell
# Import an existing Crew by its name (metadata.name).
terraform import vulnetix_crew.review_crew review-crew
```

Install, authentication and how state is read: [Terraform and OpenTofu](/platform-iac/terraform.md).

Check a file with `vulnetix config validate -f <file>`. See [Validate documents](/platform-iac/cli/validate.md). In an editor, start the file with the [schema comment](/platform-iac/schemas/editors.md).
