api.md

# API Reference

## Packages
- [crewlet.ai/v1alpha1](#crewletaiv1alpha1)


## crewlet.ai/v1alpha1

Package v1alpha1 contains the v1alpha1 API of the crewlet.ai group: a
Crewlet company and its org chart as Kubernetes objects.

Each typed field maps onto one field of Crewlet's company document, which
its doc comment names; enum values are PascalCase here and Crewlet's own
spelling there. Engine tuning without a typed field passes through
Company.spec.engineConfig.

No field holds a credential. Every position Crewlet marks as a credential in
the company document is filled from a Secret through a SecretKeyReference or
a SecretReference (NamespacedSecretKeyReference and NamespacedSecretReference
on the cluster-scoped EngineClass), or, for a seat's account the engine
creates under an Integration with provisioning Engine, is a value the engine
mints into its own store (ProvisionedCredential). docs/concepts/credentials.md
in the repository maps every position to its field.


### Resource Types
- [Company](#company)
- [EngineClass](#engineclass)
- [Integration](#integration)
- [LLMProvider](#llmprovider)
- [MCPServer](#mcpserver)
- [Schedule](#schedule)
- [Seat](#seat)
- [Unit](#unit)



#### APIExposure



APIExposure is how a company's engine API is reached. Every request needs
a credential, but for the probes, the vendors' webhooks and a box's
per-run endpoints: a person's session, signed in at the dashboard, or a
bearer token, such as the one the operator generates per company and
publishes in a Secret named by the Company's status.apiAccessSecretRef.

_Validation:_
- MinProperties: 1

_Appears in:_
- [ExposureSettings](#exposuresettings)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `mode` _[APIExposureMode](#apiexposuremode)_ | mode is how the API is reached. | ClusterInternal | Enum: [ClusterInternal Gateway Ingress] <br />Optional: \{\} <br /> |
| `gateway` _[GatewayExposure](#gatewayexposure)_ | gateway is the Gateways to attach to, for mode Gateway. |  | Optional: \{\} <br /> |
| `ingress` _[IngressExposure](#ingressexposure)_ | ingress is the Ingress settings, for mode Ingress. |  | Optional: \{\} <br /> |
| `hostname` _string_ | hostname is the API's host name, as a template with the variables and<br />rules of webhooks.hostname, and one rule more.<br />It is also where a browser reaches the engine (the Company's<br />status.endpoints.dashboardBaseURL, unless the Company states its own),<br />and an origin the engine accepts a person's write from, and Crewlet<br />refuses to start on a browser's address whose host ends in a label<br />that is a number: a browser reads such a host as an IPv4 address and<br />rewrites it before it sends it. So its last label may not be one<br />(\{\{uid\}\}.123, \{\{uid\}\}.0x1f), where webhooks.hostname's may. A last<br />label a variable fills is a number only for some Companies: one whose<br />namespace is a number (4711, 0x1f) under \{\{name\}\}.\{\{namespace\}\}, or<br />whose namespace or name makes one with the template's own characters<br />beside it (\{\{uid\}\}.0x\{\{name\}\} for a Company named cafe; a Company's<br />name begins with a letter, so it is never a number alone). That<br />Company's engine is held back, with RuntimeReady=False AddressRefused,<br />rather than started to refuse. Ending the template in a domain of your<br />own, as in \{\{name\}\}.\{\{namespace\}\}.crewlet.example.com, leaves it to no<br />Company. |  | MaxLength: 253 <br />MinLength: 1 <br />Optional: \{\} <br /> |


#### APIExposureMode

_Underlying type:_ _string_

APIExposureMode is how a company's engine API is reached from outside its
namespace.

_Validation:_
- Enum: [ClusterInternal Gateway Ingress]

_Appears in:_
- [APIExposure](#apiexposure)

| Field | Description |
| --- | --- |
| `ClusterInternal` | APIExposureClusterInternal reaches the API only through the company's<br />Service, from inside the cluster.<br /> |
| `Gateway` | APIExposureGateway also routes a host name to the API with an<br />HTTPRoute. Attach it to an internal Gateway: the API includes the<br />company's configuration and secret store.<br /> |
| `Ingress` | APIExposureIngress does the same with an Ingress.<br /> |


#### AppliedObjectCounts



AppliedObjectCounts is how many objects of each kind the applied revision
was rendered from.

_Validation:_
- MinProperties: 1

_Appears in:_
- [ConfigStatus](#configstatus)
- [UnconfirmedRevision](#unconfirmedrevision)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `units` _integer_ | units is the number of Units. |  | Minimum: 0 <br />Optional: \{\} <br /> |
| `seats` _integer_ | seats is the number of Seats. |  | Minimum: 0 <br />Optional: \{\} <br /> |
| `llmProviders` _integer_ | llmProviders is the number of model providers, platform providers<br />included. |  | Minimum: 0 <br />Optional: \{\} <br /> |
| `mcpServers` _integer_ | mcpServers is the number of MCPServers. |  | Minimum: 0 <br />Optional: \{\} <br /> |
| `integrations` _integer_ | integrations is the number of Integrations. |  | Minimum: 0 <br />Optional: \{\} <br /> |
| `schedules` _integer_ | schedules is the number of Schedules. |  | Minimum: 0 <br />Optional: \{\} <br /> |


#### ArtifactExposure



ArtifactExposure is how browsers reach the engine's artifact listener
(Crewlet's api.artifacts), which serves artifacts and nothing else. Crewlet
refuses it over plain http on a routable host, so a route serves https only.

_Validation:_
- MinProperties: 1

_Appears in:_
- [ExposureSettings](#exposuresettings)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `mode` _[ArtifactExposureMode](#artifactexposuremode)_ | mode is how the artifact origin is reached. | None | Enum: [None Gateway Ingress] <br />Optional: \{\} <br /> |
| `gateway` _[GatewayExposure](#gatewayexposure)_ | gateway is the Gateways to attach to, for mode Gateway; a listener the<br />route attaches to must be HTTPS. |  | Optional: \{\} <br /> |
| `ingress` _[IngressExposure](#ingressexposure)_ | ingress is the Ingress settings, for mode Ingress; tls is required. |  | Optional: \{\} <br /> |
| `hostname` _string_ | hostname is the artifact origin's host name, a template with the<br />variables and rules of api.hostname. Use a registrable domain of its<br />own: on the dashboard's site Crewlet serves every artifact opaque. |  | MaxLength: 200 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `origins` _[ArtifactOrigins](#artifactorigins)_ | origins is PerArtifact (unset), where the route takes *.<hostname>, or<br />Shared, where it takes <hostname>. |  | Enum: [PerArtifact Shared] <br />Optional: \{\} <br /> |


#### ArtifactExposureMode

_Underlying type:_ _string_

ArtifactExposureMode is how browsers reach a company's artifact origin.

_Validation:_
- Enum: [None Gateway Ingress]

_Appears in:_
- [ArtifactExposure](#artifactexposure)

| Field | Description |
| --- | --- |
| `None` | ArtifactExposureNone routes nothing; the Company may state an address<br />(spec.exposure.artifactsBaseURL).<br /> |
| `Gateway` | ArtifactExposureGateway routes the artifact hosts with an HTTPRoute.<br /> |
| `Ingress` | ArtifactExposureIngress does the same with an Ingress.<br /> |


#### ArtifactOrigins

_Underlying type:_ _string_

ArtifactOrigins is how artifacts are kept apart in a browser.

_Validation:_
- Enum: [PerArtifact Shared]

_Appears in:_
- [ArtifactExposure](#artifactexposure)

| Field | Description |
| --- | --- |
| `PerArtifact` | ArtifactOriginsPerArtifact gives each artifact a host under the route's<br />host name: its own origin, which needs a wildcard DNS name and certificate.<br /> |
| `Shared` | ArtifactOriginsShared serves every artifact from one host, each with an<br />opaque origin and no browser storage.<br /> |


#### AtlassianIntegration



AtlassianIntegration connects a company's Atlassian Cloud organization, in
which the engine creates a service account for each agent seat, grants it
the company's Jira and Confluence sites, and mints its API token. It maps
onto Crewlet's integrations.atlassian. Each seat names the minted token and
the account's address as provisioned values of its MCPServer named
atlassian, so the Integration's provisioning is Engine. A Data Center
deployment has no organization; its accounts are made by hand and each
seat's token comes from a Secret.



_Appears in:_
- [IntegrationSpec](#integrationspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `orgID` _string_ | orgID is the organization's id, from admin.atlassian.com. Crewlet's<br />`org_id`. |  | MaxLength: 64 <br />MinLength: 1 <br />Pattern: `^[A-Za-z0-9-]+$` <br />Required: \{\} <br /> |
| `apiKeySecretRef` _[SecretKeyReference](#secretkeyreference)_ | apiKeySecretRef is the Secret key holding an organization API key<br />created without scopes: Atlassian refuses a scoped key the call that<br />creates an account. Crewlet's `api_key`, a credential position. |  | Required: \{\} <br /> |


#### CLIAgentAuth



CLIAgentAuth is how a company's model provider signs its CLI in. It maps
onto the `auth` of a Crewlet providers.llm entry.

A subscription login is made at a terminal, by `crewlet llm login` or the
CLI's own command, and a pod has no terminal: Subscription signs in with a
headless token, such as the CLAUDE_CODE_OAUTH_TOKEN `claude setup-token`
mints, or with a credential bundle `crewlet llm export` wrote from a login
made elsewhere: the CLI's login, which is its credential files, or, for
OpenCode, which keeps its logins in a database of its own, the document
OpenCode 2's auth export printed. A bundle is restored only into a
provider's login on the data volume that is empty or that was installed
before the bundle's own login, by the install record each carries; a
refresh keeps its login's record, so the refreshed login a running engine
keeps there wins over a bundle of the same login, and only a bundle
exported after a newer login replaces it. A token never needs refreshing,
which makes it the better of the two wherever the CLI mints one. A provider names one of the two: given both, which login the CLI acts
on would be the CLI's choice between its environment and its own files,
which nothing here can see.

APIKey signs in with the one key of apiKeySecretRef, which Crewlet puts in
the CLI's key variable. Without it Crewlet would read that variable itself
from its secret store and the engine's environment, which hold credentials
that are not this object's to name, so the key is required with the mode;
it is refused under any other, where Crewlet reads none.

Crewlet hands a CLI a token or a key only through the variable its profile
names, and refuses one for a CLI whose profile names none, since it would
reach nothing: so LLMProviderSpec holds tokenSecretRef to the CLIs with a
token variable and mode APIKey to the CLIs with a key variable.

Env signs the CLI in with the provider's env and nothing else: Crewlet
hands it neither its token variable nor its key variable and seeds no
login, so a cloud provider or a gateway is the CLI's one sign-in rather than
a second one the CLI ranks against a token or a key by rules of its own. It
takes a CLI whose Crewlet profile says what in env signs it in: ClaudeCode,
whose profile lists the names that do (sign_in_env: ANTHROPIC_AUTH_TOKEN,
CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX and CLAUDE_CODE_USE_FOUNDRY),
one of which env must set, and Hermes, Pi and OpenCode, whose env must hold
their model provider's key under a credential's name (below). Those
ClaudeCode names are refused in env under every other mode, which hands the
CLI a credential of its own beside them. tokenSecretRef and
credentialBundleSecretRef are refused with it, as no token or login reaches
the CLI. The rules are LLMProviderSpec's, which sees the agent and env beside
auth.

Hermes, Pi and OpenCode may sign in to a Subscription with neither: each
fronts many model providers and reads each provider's key from that
provider's own variable, so Crewlet's profile for it names no key variable
and marks it as signing in through its environment (env_sign_in), and
Crewlet documents the provider's key in the entry's env as its metered
sign-in, and hands that env to the CLI untouched. Crewlet counts an entry of
env as a sign-in only when its name says it holds a credential: one of
its parts between underscores is, in any case, KEY, KEYS, APIKEY,
ACCESSKEY, SECRETKEY, TOKEN, SECRET, PASSWORD, PASSWD, CREDENTIAL,
CREDENTIALS, AUTH, OAUTH or PAT (cliprofile.IsCredentialName). So
OPENROUTER_API_KEY signs such a CLI in and HTTPS_PROXY or
HERMES_MAX_TOKENS does not, and one whose env holds no such name is
signed in to nothing, and refused. Every other CLI keeps to a token, a
bundle or a key: one with a key variable takes its key through mode APIKey,
and Crewlet refuses that variable in env, which auth owns. The rule is
LLMProviderSpec's, which sees the agent and env beside auth.

_Validation:_
- MinProperties: 1

_Appears in:_
- [LLMProviderSpec](#llmproviderspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `mode` _[CLIAgentAuthMode](#cliagentauthmode)_ | mode is how the CLI signs in. Unset is Subscription. Crewlet's<br />`mode`. |  | Enum: [Subscription APIKey Env] <br />Optional: \{\} <br /> |
| `tokenSecretRef` _[SecretKeyReference](#secretkeyreference)_ | tokenSecretRef is the Secret key holding a long-lived subscription<br />token the CLI mints for headless use. Crewlet's `token`, a credential<br />position. |  | Optional: \{\} <br /> |
| `apiKeySecretRef` _[SecretKeyReference](#secretkeyreference)_ | apiKeySecretRef is the Secret key holding the metered API key auth<br />mode APIKey hands the CLI, in the key variable Crewlet's profile for<br />it names (ClaudeCode's ANTHROPIC_API_KEY, Codex's CODEX_API_KEY).<br />One key: a CLI holds one sign-in and rotates nothing, so a second key<br />is a provider of its own, later in a seat's chain. Crewlet's<br />`api_key`, a credential position: the value is pushed into the<br />engine's secret store and the document refers to it by name only. |  | Optional: \{\} <br /> |
| `credentialBundleSecretRef` _[SecretKeyReference](#secretkeyreference)_ | credentialBundleSecretRef is the Secret key holding a credential<br />bundle `crewlet llm export` wrote. A bundle holding a login OpenCode<br />1.x made (its auth.json) is refused when the engine restores it, and<br />the provider runs signed out: export it again from OpenCode 2.<br />Crewlet's `credential_bundle`, a credential position. |  | Optional: \{\} <br /> |


#### CLIAgentAuthMode

_Underlying type:_ _string_

CLIAgentAuthMode is how a model provider's CLI authenticates. It maps onto
the `auth.mode` of a Crewlet providers.llm entry (Subscription is
`subscription`, APIKey is `api-key`, Env is `env`).

Crewlet's `inherit-env`, which hands the CLI whichever token or key the
engine's own environment holds, is not offered: a credential in the
engine's environment is outside the encrypted store, readable by every
process the engine runs, and resolvable by a ${NAME} written in many fields
of the company document, so it would be the one credential the API takes by
another route than a Secret reference. Subscription, APIKey and Env cover
what it is for.

_Validation:_
- Enum: [Subscription APIKey Env]

_Appears in:_
- [CLIAgentAuth](#cliagentauth)
- [PlatformLLMProviderAuth](#platformllmproviderauth)

| Field | Description |
| --- | --- |
| `Subscription` | CLIAgentAuthSubscription signs the CLI in to a subscription with<br />tokenSecretRef or credentialBundleSecretRef, or signs Hermes, Pi or<br />OpenCode in with its model provider's key in the provider's env.<br /> |
| `APIKey` | CLIAgentAuthAPIKey gives the CLI the key of apiKeySecretRef, in the<br />key variable Crewlet's profile for it names, billing the metered<br />account. CursorAgent's key is a Cursor account's API key<br />(CURSOR_API_KEY), not a model provider's.<br /> |
| `Env` | CLIAgentAuthEnv signs the CLI in with the provider's env alone: a<br />cloud provider's switch and its credentials (ClaudeCode's<br />CLAUDE_CODE_USE_BEDROCK with the AWS variables), a gateway's address<br />and the token it takes (ANTHROPIC_BASE_URL with ANTHROPIC_AUTH_TOKEN),<br />or, for Hermes, Pi and OpenCode, their model provider's key. Crewlet<br />hands the CLI neither its token variable nor its key variable, and<br />seeds no login, so nothing competes with what env signs in with.<br /> |


#### CLIAgentName

_Underlying type:_ _string_

CLIAgentName is which coding CLI a model provider drives. It maps onto the
`agent` of a Crewlet providers.llm entry (ClaudeCode is `claude-code`, Codex
is `codex`, GeminiCLI is `gemini-cli`, QwenCode is `qwen-code`, OpenCode is
`opencode`, CursorAgent is `cursor-agent`, Copilot is `copilot`, Grok is
`grok`, MuseCode is `muse-code`, KimiCode is `kimi-code`, Hermes is
`hermes`, Pi is `pi`). Crewlet's `custom`, a CLI described wholly by profile
overrides, is not offered: the overrides name the binary and the arguments
the engine's pod runs.

_Validation:_
- Enum: [ClaudeCode Codex GeminiCLI QwenCode OpenCode CursorAgent Copilot Grok MuseCode KimiCode Hermes Pi]

_Appears in:_
- [LLMProviderSettings](#llmprovidersettings)
- [LLMProviderSpec](#llmproviderspec)
- [PlatformLLMProvider](#platformllmprovider)

| Field | Description |
| --- | --- |
| `ClaudeCode` |  |
| `Codex` |  |
| `GeminiCLI` |  |
| `QwenCode` |  |
| `OpenCode` |  |
| `CursorAgent` |  |
| `Copilot` |  |
| `Grok` |  |
| `MuseCode` |  |
| `KimiCode` |  |
| `Hermes` |  |
| `Pi` |  |


#### CLIAgentWebTools

_Underlying type:_ _string_

CLIAgentWebTools is whether a model provider's CLI keeps its own web tools
(its fetch and its search). It maps onto the `web_tools` of a Crewlet
providers.llm entry's overrides (Allowed is `allowed`, Denied is
`denied`).

A seat keeps its CLI's web tools: it must not have less reach than the
same CLI at a terminal. A provider Ask Crewlet runs on turns
them off, which Crewlet requires of every model in
spec.assistant.llm: Ask Crewlet reads only what the signed-in person's
own requests return, and a page the model fetched for itself is text no
authority decision saw. Crewlet turns them off only for a CLI whose profile
carries a measured way to (its web_denial): ClaudeCode, Codex, OpenCode and
Pi.

_Validation:_
- Enum: [Allowed Denied]

_Appears in:_
- [LLMProviderSettings](#llmprovidersettings)
- [LLMProviderSpec](#llmproviderspec)
- [PlatformLLMProvider](#platformllmprovider)

| Field | Description |
| --- | --- |
| `Allowed` | CLIAgentWebToolsAllowed keeps the CLI's web tools, every seat's<br />default.<br /> |
| `Denied` | CLIAgentWebToolsDenied runs the CLI with its web tools off.<br /> |


#### ChatBackend

_Underlying type:_ _string_

ChatBackend is which chat surface a company runs. It maps onto Crewlet's
chat.backend (Chatlet is `chatlet`, Vendor is `vendor`, None is `none`).

_Validation:_
- Enum: [Chatlet Vendor None]

_Appears in:_
- [ChatSettings](#chatsettings)

| Field | Description |
| --- | --- |
| `Chatlet` | ChatChatlet is Chatlet, Crewlet's own chat: rooms the engine keeps, a<br />room for each unit's channel, read on the dashboard.<br /> |
| `Vendor` | ChatVendor is the Slack or Mattermost the company's Integrations (or<br />a seat's Slack app) connect it to.<br /> |
| `None` | ChatNone is a company with no chat.<br /> |


#### ChatSettings



ChatSettings is which chat surface a company runs and the policy of
Chatlet. It maps onto Crewlet's chat block.

_Validation:_
- MinProperties: 1

_Appears in:_
- [CompanySpec](#companyspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `backend` _[ChatBackend](#chatbackend)_ | backend is which chat surface the company runs. Unset derives it, as<br />Crewlet does: Vendor for a company with a Slack or Mattermost<br />Integration or a seat with a Slack app, Chatlet for every other. So<br />there is no default here: a Chatlet written beside such an<br />Integration, or a Vendor without one, is refused by the engine's dry<br />run, reported on the Company, since a company's conversations cannot<br />live in two places. |  | Enum: [Chatlet Vendor None] <br />Optional: \{\} <br /> |
| `chatlet` _[ChatletSettings](#chatletsettings)_ | chatlet is the policy of Chatlet: for backend Chatlet, or for no<br />backend on a company Crewlet derives Chatlet for. On a company whose<br />chat is a vendor's nothing would read it, so the engine's dry run<br />refuses it there, reported on the Company. |  | MinProperties: 1 <br />Optional: \{\} <br /> |


#### ChatletSettings



ChatletSettings is the policy of Chatlet. It maps onto Crewlet's
chat.chatlet.

_Validation:_
- MinProperties: 1

_Appears in:_
- [ChatSettings](#chatsettings)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `messageRetentionDays` _integer_ | messageRetentionDays is how long a message lives before the engine<br />prunes it: 0 keeps messages for ever, and a horizon is 30 to 3650<br />days, since under a month somebody away could miss a decision before<br />reading it. Unset takes Crewlet's default of 365. Crewlet's<br />`message_retention_days`. |  | Maximum: 3650 <br />Minimum: 0 <br />Optional: \{\} <br /> |
| `defaultChannelPrivate` _boolean_ | defaultChannelPrivate makes a room created without a stated<br />visibility private; unset, such a room is public, readable by the<br />company's seats. A room created with a visibility keeps it. Crewlet's<br />`default_channel_private`. |  | Optional: \{\} <br /> |
| `typingStatus` _[WorkingStatus](#workingstatus)_ | typingStatus is when a seat shows in a room that it is working on a<br />message. Unset takes Crewlet's default, Always. Crewlet's<br />`typing_status`. |  | Enum: [Always Addressed] <br />Optional: \{\} <br /> |


#### ClassEnvVar



ClassEnvVar is an environment variable an EngineClass sets on the engine
pods of every Company of the class: platform wiring such as the address of
the platform's own API. A value from a Secret is copied by the operator into
a Secret it owns in each Company's namespace and referenced from the pod, as
telemetry headers are, so the value never appears in the pod template and the
platform's Secret never has to be readable from a tenant namespace. The
value is in every tenant's engine pod all the same, where code the tenant
runs can read it: put nothing here a tenant must not hold.



_Appears in:_
- [EnginePodSpec](#enginepodspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `name` _string_ | name is the variable's name. |  | MaxLength: 128 <br />MinLength: 1 <br />Pattern: `^[A-Za-z_][A-Za-z0-9_]*$` <br />Required: \{\} <br /> |
| `value` _string_ | value is the variable's literal value. An empty string is a valid<br />value, which is why the field is a pointer. |  | MaxLength: 4096 <br />Optional: \{\} <br /> |
| `valueFrom` _[NamespacedSecretValueSource](#namespacedsecretvaluesource)_ | valueFrom reads the value from a Secret key in a namespace the<br />platform controls. |  | Optional: \{\} <br /> |


#### Company



Company is one Crewlet company: the operator runs an engine for it and keeps
the engine's company document equal to what the Company and the objects that
name it declare.

The Company's name becomes part of the names of the objects the operator
creates for it (the data StatefulSet and the engine Service), so it must be
a DNS label of at most 47 characters: a StatefulSet name longer than 52
characters overflows its pods' controller-revision-hash label.





| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `apiVersion` _string_ | `crewlet.ai/v1alpha1` | | |
| `kind` _string_ | `Company` | | |
| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.37/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. |  | Optional: \{\} <br /> |
| `spec` _[CompanySpec](#companyspec)_ | spec is the company's desired state. |  | Required: \{\} <br /> |
| `status` _[CompanyStatus](#companystatus)_ | status is the company's observed state. |  | MinProperties: 1 <br />Optional: \{\} <br /> |


#### CompanyAssistant



CompanyAssistant is whether the company runs Ask Crewlet, the models it
runs on and the bounds of one turn. It maps onto Crewlet's
`assistant` block, each field onto the field it names.

Ask Crewlet answers a signed-in person's questions about the company and
prepares changes for that person to approve, acting only as them: every
read is a request of theirs, and nothing is written until they approve.
Every provider in llm must drive a CLI Crewlet runs with no tool of its
own (ClaudeCode or Pi; Codex keeps a shell its sandbox only confines, and
OpenCode's has not been measured to go), with webTools Denied: Ask
Crewlet runs it in the engine's pod, never as a seat's executor runs. Crewlet refuses any other in the dry run before every apply, and
the refusal is reported on the Company, since the rule turns on the
providers' own specs.

_Validation:_
- MinProperties: 1

_Appears in:_
- [CompanySpec](#companyspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `enabled` _boolean_ | enabled runs Ask Crewlet. Unset or false leaves it off. Crewlet's<br />`enabled`. |  | Optional: \{\} <br /> |
| `llm` _[LLMProviderReference](#llmproviderreference) array_ | llm is Ask Crewlet's model chain, the first provider tried first,<br />referred to as a Seat's chain is. Required when enabled is true.<br />Crewlet's `llm`. |  | MaxItems: 8 <br />Optional: \{\} <br /> |
| `maxSteps` _integer_ | maxSteps is the most tool steps one turn may take. Unset takes<br />Crewlet's default of 30. Crewlet's `max_steps`. |  | Maximum: 40 <br />Minimum: 1 <br />Optional: \{\} <br /> |
| `turnTimeoutSeconds` _integer_ | turnTimeoutSeconds is the longest one turn may run. Unset takes<br />Crewlet's default of 900. Crewlet's `turn_timeout_seconds`. |  | Maximum: 1200 <br />Minimum: 30 <br />Optional: \{\} <br /> |
| `proposalTTLSeconds` _integer_ | proposalTTLSeconds is how long a proposed change waits for its<br />owner's approval. Unset takes Crewlet's default of 900. Crewlet's<br />`proposal_ttl_seconds`. |  | Maximum: 3600 <br />Minimum: 60 <br />Optional: \{\} <br /> |
| `retentionDays` _integer_ | retentionDays is how long a person's conversations are kept. Unset<br />takes Crewlet's default of 30. Crewlet's `retention_days`. |  | Maximum: 365 <br />Minimum: 1 <br />Optional: \{\} <br /> |
| `tokenBudget` _[TokenBudget](#tokenbudget)_ | tokenBudget caps the tokens Ask Crewlet may spend for each person per<br />window, charged on top of the company's own spec.tokenBudget.<br />Crewlet's `token_budget`. |  | MinProperties: 1 <br />Optional: \{\} <br /> |
| `deepWork` _[CompanyAssistantDeepWork](#companyassistantdeepwork)_ | deepWork lets Ask Crewlet hand a large task (research, scripts,<br />files, many steps) to a coding CLI running its own tools in a box of<br />its own, which needs spec.sandbox. Unset, Ask Crewlet answers in<br />quick mode only. Crewlet's `deep_work`. |  | Optional: \{\} <br /> |


#### CompanyAssistantDeepWork



CompanyAssistantDeepWork is Ask Crewlet's deep work: the model a large
task is handed to and the bounds of one run. It maps onto Crewlet's
`assistant.deep_work` block, each field onto the field it names.

A deep-work run is Claude Code in its own harness, with its shell, its
files and its web tools: the point of the escalation. Its one way into
Crewlet is the signed-in person's own Ask Crewlet tools over the tool
bridge, so every read is still that person's request and every write still
a proposal they approve. The provider llm names must drive ClaudeCode:
Crewlet confines a deep-work run on the engine pod around that one CLI's
install and temporary directories, which no other CLI has been measured
against. Crewlet refuses any other in the dry run before every apply, and
the refusal is reported on the Company, since the rule turns on the
provider's own spec.

Crewlet places a run in its provider's own runIn, else in the Company's
E2B sandbox when spec.sandbox.e2b configures one, else on the data pod
that opened the turn, in a box the engine confines with bubblewrap where
the pod lets it start a namespace, else with the kernel's Landlock: kept
from the engine's data, its configuration, its keyring and every other
box. On a pod that enforces neither Crewlet starts no such run, and gives
that as the reason. Crewlet makes that box on the data pod's sandboxes
volume, in a directory of its own beside the seats' boxes
(/var/lib/crewlet-sandboxes/assistant, under the
providers.sandbox.local.state_dir the operator writes whenever a run can
be placed on the pod), so the class's data.sandboxSizeLimit bounds what
the run writes there, and a run past it evicts the pod as a seat's box
does, never filling the data volume. A run reaches the bridge at the
Company's public address wherever it is placed, so a Company with no
public address runs no deep work. It is not placed by
spec.sandbox.defaultRunIn, which places seats' executors: a seat's Direct
box is not confined. deepWork requires
spec.sandbox all the same, so that whether deep work runs in E2B or on
the engine pod is a choice the Company states rather than one its absence
makes.



_Appears in:_
- [CompanyAssistant](#companyassistant)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `llm` _[LLMProviderReference](#llmproviderreference)_ | llm is the provider deep work runs on: one driving ClaudeCode, an<br />LLMProvider or a platform model provider. Crewlet's `llm`. |  | Required: \{\} <br /> |
| `timeoutSeconds` _integer_ | timeoutSeconds is the longest one deep-work run may take. Unset takes<br />Crewlet's default of 1200, which is also the most: a run lives inside<br />the turn's read grant. Crewlet's `timeout_seconds`. |  | Maximum: 1200 <br />Minimum: 60 <br />Optional: \{\} <br /> |
| `maxSteps` _integer_ | maxSteps is the most agentic rounds and Crewlet tool calls one<br />deep-work task may make. Unset takes Crewlet's default of 150.<br />Crewlet's `max_steps`. |  | Maximum: 400 <br />Minimum: 10 <br />Optional: \{\} <br /> |
| `maxTokens` _integer_ | maxTokens is the most tokens one deep-work task may spend before it<br />is stopped. Unset takes Crewlet's default of 3000000. The person's<br />tokenBudget and the company's still apply. Crewlet's `max_tokens`. |  | Maximum: 2e+07 <br />Minimum: 10000 <br />Optional: \{\} <br /> |


#### CompanyEndpoints



CompanyEndpoints is where a company is reached. Every address is a base URL
with its scheme, so that a caller appends a path to it and never
reconstructs one from the EngineClass's templates.

_Validation:_
- MinProperties: 1

_Appears in:_
- [CompanyStatus](#companystatus)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `api` _string_ | api is the in-cluster base URL of the engine's API: the company's<br />Service, for callers inside the cluster. |  | MaxLength: 2048 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `exposedAPI` _string_ | exposedAPI is the base URL of the engine's API through the class's<br />exposure.api, for callers outside the cluster: https://<hostname><br />when the route terminates TLS (the Ingress has tls, or the Gateway<br />listener the route attaches to is HTTPS), http://<hostname> otherwise,<br />with the hostname template expanded. Set only while exposure.api.mode<br />is Gateway or Ingress and the route has been accepted. |  | MaxLength: 2048 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `publicBaseURL` _string_ | publicBaseURL is the address vendors deliver webhooks to, when the<br />company has one: spec.exposure.publicBaseURL, or https://<hostname><br />from the class's webhooks.hostname. It reaches the engine's public<br />listener, and every vendor route is a path under it, such as<br />/webhooks/forge for an Atlassian Forge relay. Unset while the class's<br />webhooks.mode is None, which exposes nothing, and under External<br />before the Company states its address: the engine is then told the<br />listener's address inside the cluster, http://<company>-engine.<br /><namespace>.svc:8081, which no vendor can reach. |  | MaxLength: 2048 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `dashboardBaseURL` _string_ | dashboardBaseURL is where a browser reaches the engine, its dashboard<br />and its people's sign-in: spec.exposure.dashboardBaseURL, else the<br />address of the class's API route, on the scheme exposedAPI takes, else<br />http://localhost:8080, the address kubectl port-forward serves the<br />engine Service's API port at. It does not wait for the route to be<br />accepted, as exposedAPI does: it is the engine's api.external_url,<br />which the engine reads only at start, and a flip of acceptance would<br />otherwise restart the data pod. The engine builds every link a person<br />follows on it, an invitation's included, so with the third these lead<br />to a localhost only a port-forwarding browser reaches. |  | MaxLength: 2048 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `artifactsBaseURL` _string_ | artifactsBaseURL is where a browser reaches the artifact origin:<br />spec.exposure.artifactsBaseURL, else the class's artifacts route while it<br />serves https. Unset, the data pod opens no artifact listener. |  | MaxLength: 2048 <br />MinLength: 1 <br />Optional: \{\} <br /> |


#### CompanyExposure



CompanyExposure overrides how a company is reached.

_Validation:_
- MinProperties: 1

_Appears in:_
- [CompanySpec](#companyspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `publicBaseURL` _string_ | publicBaseURL is the HTTPS address vendors deliver webhooks to and<br />coding runs call the engine back on, overriding the one the class's<br />webhooks.hostname derives. A seat's executor run in E2B calls the<br />engine's tool bridge there, and exports its traces there while the<br />class sends telemetry, and Ask Crewlet's deep work calls<br />the bridge there wherever it runs; a seat's Direct run, on a data pod<br />or a seat pod, dials its own pod's listener on loopback for both.<br />Required<br />when the class's webhooks.mode is External, where something outside<br />the operator (a relay, an API gateway) forwards it to the engine's<br />public listener. A trailing '/' is dropped, as Crewlet drops it.<br />Crewlet's api.public.external_url, in the data pod's crewlet.yaml, and<br />its CREWLET_MCP_BRIDGE_URL on every engine pod, with its<br />CREWLET_SANDBOX_OTEL_RECEIVER_URL while the class sends telemetry,<br />which the engine reads only at start: changing it restarts the data<br />pod and the seat pods.<br />Its host is a name, an IPv4<br />address or an IPv6 address in brackets, followed by at most one port,<br />1 to 65535: Crewlet refuses to start on any other, but for an IPv6<br />address whose zone holds a ']' (https://[fe80::1%25eth0]]/), which it<br />starts on and no vendor reaches. The API judges the host and the port<br />itself rather than leaving them to the API server's URL parser, which<br />is Go's net/url as the API server was built and is run: it takes such<br />a zone, and under Go's GODEBUG setting urlstrictcolons=0<br />https://h.example:80:80 too. |  | MaxLength: 2048 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `dashboardBaseURL` _string_ | dashboardBaseURL is where a browser reaches the engine: its dashboard,<br />and the sign-in of the company's people. It overrides the address of<br />the class's API route: set it when the class routes no API, or people<br />reach it through something in front of the route (a single sign-on<br />proxy, say). Crewlet's api.external_url, in the data pod's<br />crewlet.yaml, which the engine reads only at start: changing it<br />restarts the data pod. The engine takes from it the origin a person's<br />write must come from, whether the session cookie is Secure (https)<br />and its scope, and the base of every link a person follows: a link an<br />agent composes, an invitation (/dashboard#/invite/...), a password<br />link. An address other than the route's must serve the engine, its<br />/dashboard and its /auth routes included. The route, when the class<br />has one, stays an origin the engine accepts. It is never the public<br />address: the public listener serves no dashboard. A trailing '/' is<br />dropped.<br />Crewlet compares the origin of a person's write with this address as a<br />browser spells it, and refuses to start on an address whose host a<br />browser rewrites before it sends it, so the API refuses it too: a host<br />outside ASCII, as it is or percent-encoded (write its xn-- form,<br />https://xn--bcher-kva.example for https://bücher.example), a host<br />whose last label is a number and that is not an IPv4 address of four<br />decimal octets (127.1, 2130706433, 0x7f.0.0.1, 192.168.010.1,<br />crewlet.123: write 127.0.0.1, or a name that ends in a word), and an<br />IPv6 address with a zone ([fe80::1%25eth0]). Its host is a name, an<br />IPv4 address or an IPv6 address in brackets, followed by at most one<br />port, 1 to 65535 (http://[::1]:8080, not http://::1:8080), which the<br />API judges itself, as for publicBaseURL. |  | MaxLength: 2048 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `artifactsBaseURL` _string_ | artifactsBaseURL is where a browser reaches the artifact origin,<br />ahead of the class's artifacts route: a tunnel, or http://localhost:8082<br />for a browser that port-forwards it. Crewlet's api.artifacts.external_url;<br />changing it restarts the data pod. https, or http on localhost or<br />127.x.x.x; \{artifact\} at the start of the host gives each artifact a host<br />of its own. It may not be the dashboard's or the public listener's<br />origin, nor a parent of either's host (RuntimeReady=False AddressRefused). |  | MaxLength: 2048 <br />MinLength: 1 <br />Optional: \{\} <br /> |


#### CompanyIntegrationSettings



CompanyIntegrationSettings is company-wide behaviour of the integration
reconcile loop. The vendors themselves are Integration objects.

_Validation:_
- MinProperties: 1

_Appears in:_
- [CompanySpec](#companyspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `checkIntervalSeconds` _integer_ | checkIntervalSeconds is how long a working integration is trusted<br />before the engine reads it back, and so how long access revoked at the<br />vendor goes unnoticed. Unset takes Crewlet's default of 600. Crewlet's<br />integrations.check_interval_seconds. |  | Minimum: 60 <br />Optional: \{\} <br /> |


#### CompanyLLMSettings



CompanyLLMSettings is how a company chooses among its model providers.

_Validation:_
- MinProperties: 1

_Appears in:_
- [CompanySpec](#companyspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `order` _[LLMProviderReference](#llmproviderreference) array_ | order is the providers' precedence. A seat with no default chain runs<br />on the first provider here, and on it alone: Crewlet tries no other<br />provider of the order when its keys are all cooling down, so give a<br />seat a chain for a fallback. The providers the order leaves out follow<br />it: the company's LLMProviders by name, then the platform providers by<br />name. Crewlet's providers.llm_order. |  | MaxItems: 32 <br />Optional: \{\} <br /> |
| `usePlatformProviders` _boolean_ | usePlatformProviders adds the EngineClass's platformLLMProviders to the<br />company, so seats can run on models the platform provides. Their keys<br />are pushed into the company's engine, where the tenant can read them<br />(see the class's platformLLMProviders). |  | Optional: \{\} <br /> |


#### CompanyObjects



CompanyObjects is a company's own access to its class's object store.

_Validation:_
- MinProperties: 1

_Appears in:_
- [CompanySpec](#companyspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `credentialsSecretRef` _[SecretReference](#secretreference)_ | credentialsSecretRef is a Secret, in the Company's namespace, holding<br />the keys accessKeyID and secretAccessKey (S3AccessKeyIDKey,<br />S3SecretAccessKeyKey) the engine reaches its class's S3 bucket with:<br />Crewlet's store.objects.s3.access_key_id and secret_access_key. Used<br />only while the class's objects.backend is S3.<br />Issue them per company, with a policy that admits the company's own<br />prefix of the bucket only (the class's objects.s3.prefix, expanded):<br />they are written into the engine pod's crewlet.yaml, and code the<br />tenant runs in the pod (a stdio MCP server, a coding CLI) can read<br />them. Unset uses the pod's own credentials through the SDK's<br />default chain: a workload identity bound through the class's<br />serviceAccount.annotations, which every company of the class shares<br />unless it is scoped per tenant. |  | Optional: \{\} <br /> |


#### CompanyReference



CompanyReference names the Company a namespaced object belongs to. The
Company is always in the referring object's own namespace: an object can be
part of exactly one company, and a reference across namespaces would let one
tenant attach objects to another's company.



_Appears in:_
- [IntegrationSpec](#integrationspec)
- [LLMProviderSpec](#llmproviderspec)
- [MCPServerSpec](#mcpserverspec)
- [ScheduleSpec](#schedulespec)
- [SeatSpec](#seatspec)
- [UnitSpec](#unitspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `name` _string_ | name is the metadata.name of a Company in this object's namespace. |  | MaxLength: 253 <br />MinLength: 1 <br />Required: \{\} <br /> |


#### CompanyRuntime



CompanyRuntime is a company's bounded overrides of its class.

_Validation:_
- MinProperties: 1

_Appears in:_
- [CompanySpec](#companyspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `version` _string_ | version replaces the tag of the class's engine image, for example<br />v1.2.4. It is honoured only when the class sets<br />engine.allowVersionOverride; the operator refuses a version older than<br />the one the company's data was last written by. |  | MaxLength: 128 <br />MinLength: 1 <br />Pattern: `^[A-Za-z0-9_][A-Za-z0-9_.-]\{0,127\}$` <br />Optional: \{\} <br /> |
| `env` _[EnvVar](#envvar) array_ | env adds environment variables to the engine container, for platform<br />wiring the engine reads from its environment. They are merged over the<br />class's podTemplate.spec.env by name: a variable here replaces the<br />class's variable of the same name. They are the engine's environment,<br />not that of the processes it starts: a Stdio tool server is handed only<br />the part Crewlet's allowlist names, such as PATH and the TLS and proxy<br />variables, a coding CLI that part and the variables its Crewlet profile<br />passes through, such as GeminiCLI's GOOGLE_CLOUD_PROJECT and<br />GOOGLE_CLOUD_LOCATION, a seat's Direct executor run that part alone<br />(the allowlist: PATH, the locale, TERM, TZ, the TLS trust and proxy<br />variables), and an E2B run none of it but TZ, which Crewlet hands<br />every executor run as the zone it reads a limit's reset in (UTC where<br />TZ names no zone it knows). So a variable a tool server<br />reads goes in its MCPServer's env (docs/guides/tool-servers.md), one a<br />coding CLI reads in the engine's pod in its LLMProvider's spec.env,<br />and one a seat's executor run reads in the Seat's spec.sandbox.env.<br />Names starting with CREWLET_ or OTEL_ are the operator's own.<br />ANTHROPIC_API_KEY and OPENAI_API_KEY are refused too: Crewlet reads them<br />as the key of a model provider in auth mode api-key, or an embeddings<br />provider, that names none, so a value here would be a credential outside<br />the engine's secret store; give the provider its key with<br />auth.apiKeySecretRef or apiKeySecretRef. |  | MaxItems: 32 <br />Optional: \{\} <br /> |


#### CompanySpec



CompanySpec is a company: the engine that runs it and the company-wide part
of its document. Its units, seats, model providers, tool servers and
integrations are objects of their own that name the Company in their
spec.companyRef.



_Appears in:_
- [Company](#company)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `engineClassName` _string_ | engineClassName is the EngineClass the company runs with. Unset uses<br />the class annotated crewlet.ai/is-default-class=true.<br />Whoever may write a Company may name any class, including one that<br />offers platformLLMProviders or larger limits; a class admits only the<br />namespaces its spec.allowedNamespaces selects, and a Company in any<br />other is not accepted (ClassNotAllowed). |  | MaxLength: 253 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `companyName` _string_ | companyName is the company's name. Crewlet derives every seat's<br />identity from it and the seat's handle, so it cannot be changed: a new<br />name would orphan every seat's memory. Crewlet's `name`. |  | MaxLength: 256 <br />MinLength: 1 <br />Required: \{\} <br /> |
| `mission` _string_ | mission is one line on what the company is for; every seat's prompt<br />carries it. Crewlet's `mission`, held to its bounds: at most 1024<br />characters and one line, both judged with the space around it trimmed<br />(CEL's trim() is Go's strings.TrimSpace, which Crewlet trims with, and<br />size() counts characters as Crewlet does).<br />Judged only when it CHANGES, as Crewlet judges a charter: a Company<br />written before these bounds keeps applying, and is refused only for a<br />mission it edits and leaves at fault. maxLength is the bound this field<br />had before them, kept so such a Company stays valid; it also bounds the<br />rules' cost. |  | MaxLength: 2048 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `vision` _string_ | vision is a longer statement of where the company is going, in<br />paragraphs if it needs them. Crewlet's `vision`, held to its bound: at<br />most 2048 characters with the space around it trimmed, judged only when<br />it changes, and with the bound it had before as maxLength, as on<br />mission. |  | MaxLength: 8192 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `policies` _string array_ | policies are company-wide rules every seat's prompt carries, one item<br />of a list each. Crewlet's `policies`, held to its bounds: at most 25,<br />each with the space around it trimmed not blank, at most 1024<br />characters and one line, and none a repeat of another.<br />Judged on what a change makes, as Crewlet judges it: a policy the<br />Company already held is not judged again, so reordering and removing<br />policies are never refused; the count only when it passes 25 and grows;<br />a repeat only when the change adds a copy. One difference is forced by<br />the API server's budget for a rule's cost: this API recognises a policy<br />it already held, and a repeat, by its exact text, where Crewlet compares<br />them trimmed. Two policies differing only in the space around them are<br />admitted here and refused by Crewlet's write, which the Company reports<br />as Applied=False. maxItems and items' maxLength are the bounds this<br />field had before, as on mission. |  | MaxItems: 64 <br />items:MaxLength: 2048 <br />items:MinLength: 1 <br />Optional: \{\} <br /> |
| `timeZone` _string_ | timeZone is the company's clock, an IANA time zone such as<br />Europe/Berlin: where its days begin for budgets, due dates and<br />schedules. Unset is UTC. Crewlet's `timezone`. |  | MaxLength: 64 <br />MinLength: 1 <br />Pattern: `^[A-Za-z][A-Za-z0-9_+-]*(/[A-Za-z0-9_+-]+)*$` <br />Optional: \{\} <br /> |
| `tracker` _[TrackerSettings](#trackersettings)_ | tracker is which work tracker the company runs. |  | MinProperties: 1 <br />Optional: \{\} <br /> |
| `knowledge` _[KnowledgeSettings](#knowledgesettings)_ | knowledge is which knowledge base the company runs. |  | MinProperties: 1 <br />Optional: \{\} <br /> |
| `chat` _[ChatSettings](#chatsettings)_ | chat is which chat surface the company runs: Chatlet, Crewlet's own,<br />unless it is connected to Slack or Mattermost. Crewlet's `chat`. |  | MinProperties: 1 <br />Optional: \{\} <br /> |
| `tokenBudget` _[TokenBudget](#tokenbudget)_ | tokenBudget caps the tokens all seats together may spend per window.<br />Each window binds every agent seat, so Crewlet refuses one below<br />turn_engine.executor_min_budget_tokens (25000 unless spec.engineConfig<br />sets turn_engine): an executor launch needs that much of every window<br />left, and a seat under a smaller ceiling would never launch one. The<br />refusal comes from the engine's dry run, Invalid on the Company.<br />Crewlet's `token_budget`. |  | MinProperties: 1 <br />Optional: \{\} <br /> |
| `llm` _[CompanyLLMSettings](#companyllmsettings)_ | llm is how the company chooses among its model providers. |  | MinProperties: 1 <br />Optional: \{\} <br /> |
| `assistant` _[CompanyAssistant](#companyassistant)_ | assistant configures Ask Crewlet. Unset leaves it off.<br />Crewlet's `assistant`. |  | MinProperties: 1 <br />Optional: \{\} <br /> |
| `embeddings` _[EmbeddingSettings](#embeddingsettings)_ | embeddings is the provider vectors are computed with. Unset leaves<br />search keyword-only. Crewlet's providers.embeddings. |  | Optional: \{\} <br /> |
| `sandbox` _[SandboxSettings](#sandboxsettings)_ | sandbox is where the company's agent seats' executors run. Required<br />of a company with an Agent seat and a model provider, which Crewlet<br />refuses without it (SandboxRequired). Crewlet's providers.sandbox. |  | Optional: \{\} <br /> |
| `integrations` _[CompanyIntegrationSettings](#companyintegrationsettings)_ | integrations is company-wide integration behaviour. |  | MinProperties: 1 <br />Optional: \{\} <br /> |
| `engineConfig` _[EngineConfigEntry](#engineconfigentry) array_ | engineConfig is passed through into the company document as written,<br />for the engine's tuning blocks that have no field here: turn_engine,<br />learning, scheduling, workers, skill_variables, artifacts and the<br />notification_* settings, spelled as Crewlet spells them. Each entry is<br />one top-level key of the document and its value. The operator does not<br />interpret it; the engine validates it in the dry run before every<br />apply, and a refusal is reported on the Company.<br />It may not set what another field or object of this API owns: name,<br />mission, vision, policies, timezone, tracker, knowledge, chat,<br />token_budget, assistant, providers, integrations, mcp_servers, roles,<br />units or seat_access_migrated, which the operator writes with every<br />integration kind so the engine acts on each Seat's spec.integrations.<br />Every position Crewlet holds a credential in lives under one of those<br />keys, so engineConfig can never carry a credential: the API server<br />refuses a Company whose engineConfig names one of them, before anything<br />is stored. |  | MaxItems: 64 <br />Optional: \{\} <br /> |
| `config` _[ConfigSettings](#configsettings)_ | config is how the operator manages the company's document. | \{ managementPolicy:Enforce \} | MinProperties: 1 <br />Optional: \{\} <br /> |
| `topology` _[CompanyTopology](#companytopology)_ | topology is how the engine is laid out in pods. | \{ data:map[replicas:1] \} | MinProperties: 1 <br />Optional: \{\} <br /> |
| `exposure` _[CompanyExposure](#companyexposure)_ | exposure overrides how the company is reached. |  | MinProperties: 1 <br />Optional: \{\} <br /> |
| `runtime` _[CompanyRuntime](#companyruntime)_ | runtime is the company's bounded overrides of its class. |  | MinProperties: 1 <br />Optional: \{\} <br /> |
| `objects` _[CompanyObjects](#companyobjects)_ | objects is the company's own access to its class's object store. |  | MinProperties: 1 <br />Optional: \{\} <br /> |
| `suspend` _boolean_ | suspend stops the engine and keeps its data volumes; setting it back<br />to false starts it again. It takes effect whatever else is wrong with<br />the Company, even while it is not Accepted. Meanwhile the Company<br />reports Ready=False with the reason Suspended, and vendors keep<br />delivering webhooks, some disabling a subscription after a long run of<br />failed deliveries. |  | Optional: \{\} <br /> |
| `deletionPolicy` _[DeletionPolicy](#deletionpolicy)_ | deletionPolicy is what happens to the data volumes when the Company is<br />deleted. With Retain the keyring Secret is kept as well, since the<br />volumes cannot be read without it. | Retain | Enum: [Retain Delete] <br />Optional: \{\} <br /> |


#### CompanyStatus



CompanyStatus is what the operator observed about a Company.

_Validation:_
- MinProperties: 1

_Appears in:_
- [Company](#company)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.37/#condition-v1-meta) array_ | conditions are Ready (the summary), Accepted, RuntimeReady,<br />SecretsSynced, ConfigApplied and Exposed, which Ready summarizes, and<br />EngineHealthy, IdentityClaimed and SeatsPlaced, which it does not. |  | MaxItems: 16 <br />Optional: \{\} <br /> |
| `observedGeneration` _integer_ | observedGeneration is the metadata.generation this status describes. |  | Minimum: 1 <br />Optional: \{\} <br /> |
| `engine` _[EngineStatus](#enginestatus)_ | engine is what runs the company. |  | MinProperties: 1 <br />Optional: \{\} <br /> |
| `topology` _[TopologyStatus](#topologystatus)_ | topology is the state of the company's pods. |  | MinProperties: 1 <br />Optional: \{\} <br /> |
| `config` _[ConfigStatus](#configstatus)_ | config is the revision the engine runs. |  | MinProperties: 1 <br />Optional: \{\} <br /> |
| `endpoints` _[CompanyEndpoints](#companyendpoints)_ | endpoints is where the company is reached. |  | MinProperties: 1 <br />Optional: \{\} <br /> |
| `apiAccessSecretRef` _[SecretReference](#secretreference)_ | apiAccessSecretRef names the Secret, in the Company's namespace, that<br />holds a bearer token for the engine's API under the key token<br />(APIAccessTokenKey) and the API's in-cluster base URL under the key<br />url (APIAccessURLKey). It is for the company's consumers (a control<br />plane, a dashboard); the operator uses a token of its own, so revoking<br />this one never locks the operator out.<br />The token holds Crewlet's admin grant, which takes in every app, so<br />whoever holds it can rewrite the company document where the operator<br />does not manage it, reveal every value in the engine's secret store<br />(the class's platform model keys included: it is a deployment's own<br />token, not a person's machine token, which Crewlet refuses a reveal),<br />and invite or create the company's people. Grant read on this Secret<br />only to whoever may do that, by resourceNames: read on every Secret of<br />the namespace also exposes <company>-api-tokens, <company>-keyring and<br /><company>-bootstrap. |  | Optional: \{\} <br /> |


#### CompanyTopology



CompanyTopology is how a company's engine is laid out in pods: one data pod
that holds the estate, serves the API and runs the background workers, and
the seat pools, stateless pods that run the seats placed in them. Without
seat pools every seat runs on the data pod.

_Validation:_
- MinProperties: 1

_Appears in:_
- [CompanySpec](#companyspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `data` _[DataTopology](#datatopology)_ | data is the pods that hold the estate. | \{ replicas:1 \} | MinProperties: 1 <br />Optional: \{\} <br /> |
| `defaultSeatPool` _string_ | defaultSeatPool is the pool of every agent seat whose Seat names no<br />spec.placement.pool: data, or the name of a Shared pool of seatPools. | data | MaxLength: 20 <br />MinLength: 1 <br />Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$` <br />Optional: \{\} <br /> |
| `seatPools` _[SeatPool](#seatpool) array_ | seatPools are stateless pods that run seats. They need the class's<br />spec.seatPools.policy Allowed, and together run at most its maxPods<br />pods. |  | MaxItems: 8 <br />Optional: \{\} <br /> |


#### ConfigSettings



ConfigSettings is how the operator manages a company's document.

_Validation:_
- MinProperties: 1

_Appears in:_
- [CompanySpec](#companyspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `managementPolicy` _[ManagementPolicy](#managementpolicy)_ | managementPolicy says who owns the document. Under Enforce the data<br />pod's crewlet.yaml sets Crewlet's api.auth.company_writers to the<br />operator's own token, so the engine refuses every other credential a<br />change to the document; under Observe and Seed it sets none, and<br />Crewlet's authority table decides who may. The engine reads<br />crewlet.yaml only at start, so changing the policy to or from Enforce<br />restarts the data pod. | Enforce | Enum: [Enforce Observe Seed] <br />Optional: \{\} <br /> |


#### ConfigStatus



ConfigStatus is the revision of the company document the engine runs.

_Validation:_
- MinProperties: 1

_Appears in:_
- [CompanyStatus](#companystatus)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `revisionID` _string_ | revisionID is the engine's id of the last revision the operator saw<br />run the rendered document: the one it applied, one the engine<br />activated with the same content (a reload), or, under Observe, the<br />one it found in sync. Under Seed it is the revision the document was<br />seeded as. |  | MaxLength: 128 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `epoch` _integer_ | epoch is the engine's activation counter for that revision. The<br />engine applies a revision asynchronously; it runs it once the applied<br />epoch its /health reports has reached this. |  | Minimum: 0 <br />Optional: \{\} <br /> |
| `appliedHash` _string_ | appliedHash is the hash of the rendered document and of the values<br />of the Secret keys it references, as the revision recorded runs<br />them: the operator's last write, or a revision it found running that<br />document after every value it wrote. The values enter it only as<br />keyed fingerprints, so it reveals nothing about them. |  | MaxLength: 128 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `appliedAt` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.37/#time-v1-meta)_ | appliedAt is when the operator activated the revision this records,<br />or found the engine running it where it adopted a revision of the<br />rendered document it did not write (a reload), or a write of its own<br />whose activation the engine could not confirm (unconfirmed), which may<br />have landed any time since it was written: what the operator's wait<br />for the engine to apply its epoch counts from. |  | Optional: \{\} <br /> |
| `objects` _[AppliedObjectCounts](#appliedobjectcounts)_ | objects counts the objects the revision was rendered from. |  | MinProperties: 1 <br />Optional: \{\} <br /> |
| `unconfirmed` _[UnconfirmedRevision](#unconfirmedrevision) array_ | unconfirmed are the revisions of the rendered document the operator<br />wrote, which the engine stored, and whose activation the engine sent<br />to its fleet and could not confirm (a 503 naming the revision it<br />stored): the fleet may run one of them or none. Before it writes<br />again, the operator reads which revision the engine runs. If it runs<br />one of these, that write landed: status.config records it as the<br />operator's write, as though the engine had confirmed it. If it runs the<br />revision one of them was built on, that one has not landed and still<br />may, so it stays, and the write is sent again on the same condition,<br />which the engine refuses once one of them lands. Any other can no<br />longer land, and goes, to overtaken where it was written into an<br />engine that ran no document. A reload the operator asks for, to<br />activate a revision of its own again, is recorded here too when the<br />engine stores it and cannot confirm activating it, as a write of that<br />revision's document, whether or not a read after it could say which<br />revision runs. They are oldest first, and a seventeenth drops the<br />oldest. |  | MaxItems: 16 <br />Optional: \{\} <br /> |
| `overtaken` _[UnconfirmedRevision](#unconfirmedrevision) array_ | overtaken are writes from unconfirmed into an engine that ran no<br />document that another revision the engine activated has overtaken.<br />None of them can land any more, and under Seed one of them is taken as<br />the seed whatever revision runs now: the engine stored it while it had<br />none, so either it landed and was replaced since, or another writer's<br />create reached the engine first, which nothing the engine says tells<br />apart. Each is kept until a reconcile decides with it, and they go<br />once status.config records a revision of the rendered document in<br />sync, a write of it, or the seed. They are oldest first, and a<br />seventeenth drops the oldest. |  | MaxItems: 16 <br />Optional: \{\} <br /> |
| `placement` _[RevisionPlacement](#revisionplacement)_ | placement is where the revision the engine runs pins its agent seats,<br />read from the engine's document under every management policy. The<br />operator keeps a seat pool's pods running while the running revision<br />pins a seat to them, even after the pool or the seat's placement is<br />gone from the spec: a pod stopped while its seat is still pinned to<br />it would leave the seat held by nobody, and a blocked document keeps<br />the last good revision running. Once a revision that pins nothing to<br />them runs, the pods are deleted. |  | MinProperties: 1 <br />Optional: \{\} <br /> |


#### ConfluenceIntegration



ConfluenceIntegration turns Confluence on for a company: page changes wake
the seats they concern, and the company may run Confluence as its knowledge
base (the Company's spec.knowledge.backend Confluence). It maps onto
Crewlet's integrations.confluence. Each seat's Confluence identity is its
own token, a credential of the MCPServer named atlassian in its Seat's
spec.mcp.



_Appears in:_
- [IntegrationSpec](#integrationspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `url` _string_ | url is a Data Center instance's or a Cloud site's base URL. Unset<br />with cloudID unset, the company's Atlassian Integration discovers the<br />site. Crewlet's `url`. |  | MaxLength: 2048 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `cloudID` _string_ | cloudID is an Atlassian Cloud site's id; requests go through the API<br />gateway of the Cloud siteURL is on: Atlassian Government Cloud's,<br />api.atlassian-us-gov-mod.com, for a site under<br />atlassian-us-gov-mod.net, and api.atlassian.com otherwise. Crewlet's<br />`cloud_id`. |  | MaxLength: 64 <br />MinLength: 1 <br />Pattern: `^[A-Za-z0-9-]+$` <br />Optional: \{\} <br /> |
| `siteURL` _string_ | siteURL is the site's address as a browser opens it, for the links<br />the engine hands people; needed with cloudID, which is read through<br />the gateway of this site's Cloud. Unset is url. Crewlet's<br />`site_url`. |  | MaxLength: 2048 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `email` _string_ | email is the account's address, for Confluence Cloud's basic<br />authentication. Unset sends the token as a bearer token. Crewlet's<br />`email`. |  | MaxLength: 254 <br />MinLength: 3 <br />Pattern: `^[^@\s]+@[^@\s]+$` <br />Optional: \{\} <br /> |
| `tokenSecretRef` _[SecretKeyReference](#secretkeyreference)_ | tokenSecretRef is the Secret key holding the API token (Cloud) or<br />personal access token (Data Center) of the account a seat without a<br />Confluence credential of its own searches as, which also reads the<br />tool-skill pages. Crewlet's `token`, a credential position. |  | Required: \{\} <br /> |
| `webhookSecretRef` _[SecretKeyReference](#secretkeyreference)_ | webhookSecretRef is the Secret key holding the secret a Data Center<br />instance signs webhook deliveries with. Required for Data Center.<br />Crewlet's `webhook_secret`, a credential position. |  | Optional: \{\} <br /> |
| `webhookTokenSecretRef` _[SecretKeyReference](#secretkeyreference)_ | webhookTokenSecretRef is the Secret key holding the token a Confluence<br />Cloud webhook carries in its delivery URL, Cloud signing nothing: at<br />least 26 characters, random. Crewlet's `webhook_token`, a credential<br />position. |  | Optional: \{\} <br /> |


#### ConfluenceSeatIntegration



ConfluenceSeatIntegration is a seat's access on Confluence. It maps onto
Crewlet's role integrations.confluence and needs the company's Confluence
Integration. With the company's Atlassian Integration the engine creates
the seat's account, grants it Confluence and gives it the access in the
spaces; without one the account is made outside the engine, and the engine
reports the seat's access as managed outside Crewlet. A site with
Confluence's role-based access grants by spaceRole; a site without it
grants space permissions by operation.



_Appears in:_
- [SeatIntegrations](#seatintegrations)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `enabled` _boolean_ | enabled is whether the seat is on Confluence. False takes away the<br />account's access in its spaces and narrows its token, and keeps the<br />account and its Confluence product access. Crewlet's `enabled`. |  | Required: \{\} <br /> |
| `spaceRole` _string_ | spaceRole is the space role the seat holds in each of spaces, by its<br />id on the site (Confluence's role-based access): Viewer, Collaborator,<br />Manager, Admin, or a custom role. The engine checks it against the<br />site's roles on every pass, and reports one that no longer exists<br />rather than falling back to another. It or operations is required<br />while the seat is on in spaces; with neither and no spaces, the seat<br />holds Confluence product access only. Crewlet's `space_role`. |  | MaxLength: 128 <br />MinLength: 1 <br />Pattern: `^[A-Za-z0-9][A-Za-z0-9_:-]*$` <br />Optional: \{\} <br /> |
| `operations` _string array_ | operations are Confluence's space permissions, as<br /><operation>:<target> under Confluence's own names, such as read:space<br />or create:page, the seat holds in each of spaces, for a site whose<br />role-based access is off. Crewlet's `operations`. |  | MaxItems: 64 <br />items:MaxLength: 64 <br />items:MinLength: 3 <br />items:Pattern: `^[a-z_]+:[a-z_]+$` <br />Optional: \{\} <br /> |
| `spaces` _string array_ | spaces are the spaces, by key, the seat holds spaceRole or<br />operations in. Each must be a space the company's document names, as<br />a Unit's or a Seat's spec.space: Crewlet refuses another, which the<br />engine's dry run reports as Invalid on the Seat. Crewlet's `spaces`. |  | MaxItems: 128 <br />items:MaxLength: 255 <br />items:MinLength: 1 <br />items:Pattern: `^~?[A-Za-z0-9]+$` <br />Optional: \{\} <br /> |


#### ContainerWebhookMode

_Underlying type:_ _string_

ContainerWebhookMode is how webhooks are registered at GitHub: once on the
organization, or once per repository. It maps onto Crewlet's org_webhook
(Auto is `auto`, Require is `true`, Never is `false`).

_Validation:_
- Enum: [Auto Require Never]

_Appears in:_
- [GitHubProvisioning](#githubprovisioning)
- [GitLabEngineProvisioning](#gitlabengineprovisioning)

| Field | Description |
| --- | --- |
| `Auto` | ContainerWebhookAuto uses one organization hook where the token may<br />create one, and per-repository hooks otherwise.<br /> |
| `Require` | ContainerWebhookRequire demands an organization hook.<br /> |
| `Never` | ContainerWebhookNever always registers per-repository hooks.<br /> |


#### DataPodSettings



DataPodSettings sizes the pods that hold a company's estate. In v1alpha1 a
company runs exactly one data pod, which also serves the API, runs the
background workers and runs every seat placed in the pool data.



_Appears in:_
- [EngineClassSpec](#engineclassspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `allowedReplicas` _integer array_ | allowedReplicas is the set of data-pod counts a Company of this class<br />may choose in spec.topology.data.replicas. v1alpha1 runs exactly one<br />data pod, so the only value admitted is 1; 3 and 5, a highly available<br />estate, are added when the operator can run them. | [1] | MaxItems: 1 <br />MinItems: 1 <br />items:Enum: [1] <br />Optional: \{\} <br /> |
| `resources` _[ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.37/#resourcerequirements-v1-core)_ | resources are the compute resources of the engine container. Its<br />memory holds the engine, the CLI processes its providers run in its<br />process (each provider's maxConcurrent of them, 200 to 450 MB each),<br />a seat's Direct executor run, one CLI and the tools it starts, for<br />each agent seat the pod holds that runs Direct, and the stopped<br />processes of each Direct run parked on a person's question, which keep<br />their memory until the run resumes or its pause TTL expires: a run<br />that takes the container past its limit can take the engine with it. |  | Optional: \{\} <br /> |
| `storage` _[DataStorage](#datastorage)_ | storage is the data volume each data pod gets. |  | Required: \{\} <br /> |
| `startupSeconds` _integer_ | startupSeconds is how long a data pod's engine may take, from its<br />start, to answer /health 200: the time it takes to recover what it holds<br />on its volume (the store, the event stream, the replicated estate) and<br />bring its broker up. Crewlet waits that recovery out rather than<br />bounding it, because it grows with the data, so the startup probe is<br />what bounds it: it allows at least this long from the container's<br />start, and less than ten seconds more. A boot that runs past it is<br />restarted and begins its recovery again, so err long: a window that is<br />too long costs nothing on a healthy boot, only the time to restart one<br />that hung.<br />It is at least every bound Crewlet puts on a data pod's boot, laid end<br />to end, which a window may not cut short: 1866 seconds, or 2006 with<br />objects.backend S3, whose bucket every boot probes. Those are its waits<br />for its own broker and store (provisioning the event stream, the<br />coordination buckets, the object store and the state logs, two minutes<br />a window on the broker of one member a data pod runs, and the requests<br />around them), never for a peer or a seat pod. One of them grows with<br />what the node holds and is left to the recovery's share, as the<br />recovery is: the claim of each batch of a seat pod's events the node<br />kept and could not settle, 15 s a batch. Unset derives it from the<br />data volume: that floor plus six seconds per GiB of the volume. That is<br />four times the second and a half per GiB Crewlet measured recovering<br />after a crash on a fast local disk, for volumes that are<br />network-attached; set this for disks slower than that. Nothing the<br />company configures counts: the engine answers /health once it has<br />recovered, and only then reads the company's secrets, starts its tool<br />servers and restores its CLIs' logins.<br />Changing it changes the data pods' template, which restarts them. |  | Maximum: 86400 <br />Minimum: 1866 <br />Optional: \{\} <br /> |
| `terminationGracePeriodSeconds` _integer_ | terminationGracePeriodSeconds is how long a data pod may take to stop.<br />The engine finishes the turn segments it runs in its own process<br />before it exits (a seat's launch, the collection of its run, the<br />review, a delegated worker) and puts no bound on that itself, so the<br />default is five minutes, which covers a long segment, rather than the<br />Kubernetes default of thirty seconds, which does not. A seat's<br />executor run is not waited for: a Direct one on the pod is a process<br />of it and ends with it, its box with the pod's sandboxes volume, and<br />Crewlet carries its round on in a fresh run once the pod is back, and<br />an E2B one carries on in its sandbox. | 300 | Maximum: 3600 <br />Minimum: 30 <br />Optional: \{\} <br /> |
| `scratchSizeLimit` _[Quantity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.37/#quantity-resource-api)_ | scratchSizeLimit caps the emptyDir a data pod keeps its /tmp and HOME<br />on: what the processes the engine runs on the pod write off its data<br />volume, the packages and files of the stdio tool servers it starts<br />(a launcher such as npx or uvx installs a server under HOME), git's<br />and their scratch files, the sockets of its tool sessions, and what a<br />seat's Direct executor run writes outside its box. Crewlet points a<br />run's temporary directories into its box but confines it to nothing<br />else, so a command that names /tmp or the engine's home outright<br />writes here. A pod that writes more is evicted, with every run and<br />turn on it and the company's API; its data volume is untouched. Unset<br />is 10Gi.<br />It bounds and reserves as sandboxSizeLimit does, and the<br />ephemeral-storage limit in resources bounds the two together with the<br />container's own writes. Changing it changes the data pods' template,<br />which restarts them. |  | Optional: \{\} <br /> |
| `sandboxSizeLimit` _[Quantity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.37/#quantity-resource-api)_ | sandboxSizeLimit caps the emptyDir a data pod keeps its sandboxes in,<br />at /var/lib/crewlet-sandboxes: the boxes Crewlet makes on the pod<br />itself for the executor runs it places there (its direct cell, under<br />Crewlet's providers.sandbox.local.state_dir): one for each agent seat<br />of the pod whose run is running, a seat running one at a time, and one<br />for each run parked on a person's question, which frees its seat for<br />its next run and keeps its box, its processes stopped, until it<br />resumes or its pause TTL expires (the Seat's pauseTTLSeconds, else the<br />Company's spec.sandbox.defaultPauseTTLSeconds, 1800 seconds unless<br />set; 0 removes the box at once). It holds the confined box of each<br />Ask Crewlet deep-work run placed on the pod too, in a<br />directory of its own. A box is removed when its run ends, and holds<br />the run's checkout, its coding CLI's home and temporary files, and<br />whatever the run installs and builds. A pod whose boxes<br />write more is evicted, with every run and turn on it; its data volume<br />is untouched. Unset is 20Gi. It bounds the boxes alone: what a run<br />writes outside its box counts against scratchSizeLimit, or, under<br />/var/lib/crewlet, against the data volume.<br />It bounds the boxes and reserves nothing: the scheduler places the<br />pod by the ephemeral-storage request in resources, and an<br />ephemeral-storage limit there bounds the container's own writes and<br />every emptyDir of the pod together, so give it room for this one.<br />Changing it changes the data pods' template, which restarts them. |  | Optional: \{\} <br /> |


#### DataStorage



DataStorage is the volume each data pod keeps the company's estate on.



_Appears in:_
- [DataPodSettings](#datapodsettings)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `storageClassName` _string_ | storageClassName is the StorageClass of the data volumes. Unset uses<br />the cluster's default class. |  | MaxLength: 253 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `size` _[Quantity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.37/#quantity-resource-api)_ | size is the capacity requested for each data volume. It holds the<br />store, the event stream and the store's cache. There is no default: how<br />much a tenant may keep is a platform decision.<br />Three quarters of it is the engine's event stream, Crewlet's<br />stream.store_max_bytes: the stream reserves what a node keeps there up<br />front, and a fresh node refuses to boot on a share that cannot hold it<br />(Crewlet's engine.BrokerFloor, and its deployment guide's "minimum room<br />for a fresh node"). Its nine state logs' ceilings at their smallest<br />come to 8120172544 bytes, so a volume must be at least 11Gi, whose share<br />of 8.25Gi holds them. With objects.backend NATS, the default, the object<br />store's bucket reserves a quarter of the share beside them, 10826896725<br />bytes in all, so such a class must give at least 14Gi, whose share is<br />10.5Gi. That is the least that boots: the mailboxes and coordination<br />buckets grow into what is left, so give a company that runs for long<br />more. The stream's ceiling is 64Ti (config.StoreMaxBytesCeiling, a<br />guard against a unit mistake), so a volume larger than about 85Ti gives<br />the stream 64Ti and the rest to the store and its snapshots.<br />It applies to the data volumes of companies created after it is set.<br />An existing company's volumes keep the size they were created with:<br />they are claimed through the StatefulSet's volume claim templates,<br />which Kubernetes does not let change, and growing a volume is a<br />decision about one company's storage class and data, not the class's.<br />Its owner expands the company's claim instead, and once the expansion<br />lands the operator sizes the stream from what the claim then has. |  | Required: \{\} <br /> |


#### DataTopology



DataTopology is the pods that hold a company's estate.

_Validation:_
- MinProperties: 1

_Appears in:_
- [CompanyTopology](#companytopology)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `replicas` _integer_ | replicas is the number of data pods. It must be one of the class's<br />spec.data.allowedReplicas. v1alpha1 runs exactly one data pod, so 1 is<br />the only value admitted. A highly available estate of 3 or 5 is a<br />later addition, and it comes with a rule that the count cannot change<br />once set, because the event stream's replication is fixed when the<br />estate is created: admitting 3 or 5 before the operator can run them<br />would leave Companies that could never be corrected. | 1 | Enum: [1] <br />Minimum: 1 <br />Optional: \{\} <br /> |


#### DataTopologyStatus



DataTopologyStatus is the state of a company's data pods.

_Validation:_
- MinProperties: 1

_Appears in:_
- [TopologyStatus](#topologystatus)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `replicas` _integer_ | replicas is the number of data pods. |  | Minimum: 0 <br />Optional: \{\} <br /> |
| `readyReplicas` _integer_ | readyReplicas is the number of data pods that are ready. |  | Minimum: 0 <br />Optional: \{\} <br /> |
| `updatedReplicas` _integer_ | updatedReplicas is the number of data pods that run the current pod<br />template. |  | Minimum: 0 <br />Optional: \{\} <br /> |


#### DatadogIntegration



DatadogIntegration turns Datadog on for a company: a firing monitor wakes
the seat its tags name. It maps onto Crewlet's integrations.datadog. The
engine registers the webhook at Datadog itself and creates a service
account for each agent Seat whose spec.integrations.datadog is enabled,
with the role that block names, so the Integration's provisioning is
Engine.



_Appears in:_
- [IntegrationSpec](#integrationspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `webhookTokenSecretRef` _[SecretKeyReference](#secretkeyreference)_ | webhookTokenSecretRef is the Secret key holding the token every<br />delivery carries in its X-Crewlet-Token header: at least 26<br />characters, random. Datadog signs nothing, so this token is the whole<br />of the check. Crewlet's `webhook_token`, a credential position. |  | Required: \{\} <br /> |
| `routeTo` _[DatadogRouteTo](#datadogrouteto)_ | routeTo is where an alert goes whose monitor names no seat.<br />Crewlet's `route_to`. |  | MinProperties: 1 <br />Required: \{\} <br /> |
| `site` _[DatadogSite](#datadogsite)_ | site is the region the organization, and so its keys, are in.<br />Crewlet's `provisioning.site`. |  | Enum: [US1 US3 US5 EU1 AP1 AP2 US1FED] <br />Required: \{\} <br /> |
| `apiKeySecretRef` _[SecretKeyReference](#secretkeyreference)_ | apiKeySecretRef is the Secret key holding an API key of the<br />organization, which says which organization a call is for. Crewlet's<br />`provisioning.api_key`, a credential position. |  | Required: \{\} <br /> |
| `appKeySecretRef` _[SecretKeyReference](#secretkeyreference)_ | appKeySecretRef is the Secret key holding an application key, which<br />says which user acts: one allowed to manage webhooks and service<br />accounts. Crewlet's `provisioning.app_key`, a credential position. |  | Required: \{\} <br /> |
| `emailDomain` _string_ | emailDomain is the domain the service accounts' addresses are built<br />under; Datadog requires an address and never writes to it. Unset<br />takes Crewlet's default, agents.crewlet.invalid. Crewlet's<br />`provisioning.email_domain`. |  | MaxLength: 253 <br />MinLength: 1 <br />Pattern: `^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$` <br />Optional: \{\} <br /> |
| `webhookName` _string_ | webhookName is the name of the webhook the engine keeps at Datadog,<br />and so the handle monitors write: @webhook-<name>. Unset is crewlet.<br />Crewlet's `webhook_name`. |  | MaxLength: 128 <br />MinLength: 1 <br />Pattern: `^[^ @,]+$` <br />Optional: \{\} <br /> |
| `handleTag` _string_ | handleTag is the monitor tag key whose value names the seat an alert<br />wakes, such as crewlet:sre-lead. Unset is crewlet. Crewlet's<br />`handle_tag`. |  | MaxLength: 128 <br />MinLength: 1 <br />Pattern: `^[a-z][a-z0-9_./-]*$` <br />Optional: \{\} <br /> |


#### DatadogRouteTo



DatadogRouteTo is where an alert goes whose monitor names no seat.

_Validation:_
- MinProperties: 1

_Appears in:_
- [DatadogIntegration](#datadogintegration)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `seatRef` _[LocalObjectReference](#localobjectreference)_ | seatRef names the agent Seat, in this namespace, the alert wakes.<br />Crewlet's `route_to`, as the seat's handle. |  | Optional: \{\} <br /> |
| `dismiss` _boolean_ | dismiss wakes nobody: only monitors that name a seat reach an agent,<br />and the rest stay with whatever Datadog already does about them.<br />Crewlet's `route_to: none`. |  | Optional: \{\} <br /> |


#### DatadogSeatIntegration



DatadogSeatIntegration is a seat's service account on Datadog. It maps onto
Crewlet's role integrations.datadog and needs the company's Datadog
Integration, under which the engine creates the account with the role and
mints its application key.



_Appears in:_
- [SeatIntegrations](#seatintegrations)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `enabled` _boolean_ | enabled is whether the seat is on Datadog. False disables the service<br />account and deletes its key; Datadog never erases a user, so its<br />history keeps its author. Crewlet's `enabled`. |  | Required: \{\} <br /> |
| `role` _string_ | role is the Datadog role the account holds, by its id<br />(GET /api/v2/roles): a managed role, such as Datadog Read Only Role,<br />or a custom one. The engine checks it against the organization's<br />roles on every pass, and reports one that no longer exists rather than<br />falling back to another. Required while the seat is on. Crewlet's<br />`role`. |  | MaxLength: 64 <br />MinLength: 1 <br />Pattern: `^[A-Za-z0-9][A-Za-z0-9-]*$` <br />Optional: \{\} <br /> |


#### DatadogSite

_Underlying type:_ _string_

DatadogSite is the Datadog region a company's organization is in. It maps
onto Crewlet's provisioning.site, the region's host name (US1 is
datadoghq.com, US3 us3.datadoghq.com, US5 us5.datadoghq.com, EU1
datadoghq.eu, AP1 ap1.datadoghq.com, AP2 ap2.datadoghq.com, US1FED
ddog-gov.com).

_Validation:_
- Enum: [US1 US3 US5 EU1 AP1 AP2 US1FED]

_Appears in:_
- [DatadogIntegration](#datadogintegration)

| Field | Description |
| --- | --- |
| `US1` |  |
| `US3` |  |
| `US5` |  |
| `EU1` |  |
| `AP1` |  |
| `AP2` |  |
| `US1FED` |  |


#### DeletionPolicy

_Underlying type:_ _string_

DeletionPolicy is what happens to a company's data volumes when the Company
is deleted.

_Validation:_
- Enum: [Retain Delete]

_Appears in:_
- [CompanySpec](#companyspec)

| Field | Description |
| --- | --- |
| `Retain` | DeletionPolicyRetain keeps the data volumes and the keyring Secret<br /><name>-keyring that opens the secrets sealed on them. A Company created<br />again with the same name and namespace finds both and its estate again.<br /> |
| `Delete` | DeletionPolicyDelete deletes them with the Company.<br /> |


#### E2BSandbox



E2BSandbox is the remote sandbox service a seat's executor run placed in
E2B happens in. Each field maps onto the same-named field of Crewlet's
providers.sandbox.e2b.



_Appears in:_
- [SandboxSettings](#sandboxsettings)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `apiKeySecretRef` _[SecretKeyReference](#secretkeyreference)_ | apiKeySecretRef is the Secret key holding the service's API key.<br />Crewlet's `api_key`, a credential position. |  | Required: \{\} <br /> |
| `domain` _string_ | domain points at a self-hosted cluster of the service. Unset is the<br />vendor's cloud. |  | MaxLength: 253 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `template` _string_ | template is the sandbox template, which also fixes each sandbox's CPU,<br />memory and disk. Unset, each run gets the vendor's prebuilt template<br />for its CLI (claude or opencode); a template set here is used for every<br />run, so it must carry the CLI of every ClaudeCode or OpenCode provider<br />whose executor runs are placed in E2B. For OpenCode that is<br />OpenCode 2, the @opencode/cli package (opencode --version prints<br />opencode v2.…): Crewlet's OpenCode runner ends a run at once in a box<br />with OpenCode 1.x (npm's opencode-ai), and E2B does not say which<br />release its prebuilt opencode template carries, so a company whose<br />OpenCode runs end that way sets template to one built with<br />@opencode/cli. |  | MaxLength: 253 <br />MinLength: 1 <br />Optional: \{\} <br /> |


#### EmbeddingProviderType

_Underlying type:_ _string_

EmbeddingProviderType is which embeddings API a company uses. It maps onto
Crewlet's providers.embeddings.type (OpenAI is `openai`, OpenAICompatible
is `openai-compatible`).

_Validation:_
- Enum: [OpenAI OpenAICompatible]

_Appears in:_
- [EmbeddingSettings](#embeddingsettings)

| Field | Description |
| --- | --- |
| `OpenAI` | EmbeddingProviderOpenAI is OpenAI's embeddings API.<br /> |
| `OpenAICompatible` | EmbeddingProviderOpenAICompatible is any endpoint that speaks it.<br /> |


#### EmbeddingSettings



EmbeddingSettings is the provider a company computes vectors with, for
semantic knowledge search and for recall of a seat's memory. Each field maps
onto the same-named field of Crewlet's providers.embeddings.



_Appears in:_
- [CompanySpec](#companyspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `type` _[EmbeddingProviderType](#embeddingprovidertype)_ | type is which embeddings API the provider speaks. | OpenAI | Enum: [OpenAI OpenAICompatible] <br />Optional: \{\} <br /> |
| `model` _string_ | model is the embedding model id. Crewlet's `model`. Crewlet trims it of<br />white space and refuses an embeddings provider with nothing left, as<br />naming no model. |  | MaxLength: 256 <br />MinLength: 1 <br />Required: \{\} <br /> |
| `apiKeySecretRef` _[SecretKeyReference](#secretkeyreference)_ | apiKeySecretRef is the Secret key holding the API key. Crewlet's<br />`api_key`, a credential position. Required for type OpenAI: Crewlet<br />reads OPENAI_API_KEY from the environment when it is unset, and the<br />engine's environment never carries one (see spec.runtime.env). An<br />OpenAICompatible endpoint that needs no key may omit it. |  | Optional: \{\} <br /> |
| `baseURL` _string_ | baseURL is the endpoint of an OpenAI-compatible service. Crewlet's<br />`base_url`. |  | MaxLength: 2048 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `dimensions` _integer_ | dimensions is the vector width. Unset takes the model's own width,<br />which Crewlet knows for the models it names; any other model needs it<br />stated, and it must match what the model produces. |  | Maximum: 4096 <br />Minimum: 64 <br />Optional: \{\} <br /> |
| `maxInputTokens` _integer_ | maxInputTokens is the most tokens one input may hold. Unset takes the<br />model's documented window; it may only lower it. |  | Minimum: 1 <br />Optional: \{\} <br /> |
| `maxBatchInputs` _integer_ | maxBatchInputs is the most inputs one request may carry. Unset takes<br />the model's documented limit; it may only lower it. |  | Minimum: 1 <br />Optional: \{\} <br /> |
| `maxBatchTokens` _integer_ | maxBatchTokens is the most tokens one request may carry, summed over<br />its inputs. Unset takes the model's documented limit; it may only<br />lower it. |  | Minimum: 1 <br />Optional: \{\} <br /> |


#### EngineClass



EngineClass is a platform's defaults and guard rails for running Crewlet
engines: the image, the size of the data pods, how companies are exposed,
and limits. A Company names one in spec.engineClassName; a platform that
hosts many tenants usually writes one class for each service tier it
offers them.

Anyone who may write a Company may name any class; a class admits the
namespaces its spec.allowedNamespaces selects, and no others.





| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `apiVersion` _string_ | `crewlet.ai/v1alpha1` | | |
| `kind` _string_ | `EngineClass` | | |
| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.37/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. |  | Optional: \{\} <br /> |
| `spec` _[EngineClassSpec](#engineclassspec)_ | spec is the class's desired state. |  | Required: \{\} <br /> |
| `status` _[EngineClassStatus](#engineclassstatus)_ | status is the class's observed state. |  | MinProperties: 1 <br />Optional: \{\} <br /> |


#### EngineClassSpec



EngineClassSpec is the defaults and guard rails a platform sets once for
every Company that names the class, the way a StorageClass does for volumes.
The data volume's floor and the data pods' startup window follow where the
class keeps files (see DataStorage.size and DataPodSettings.startupSeconds):
a company's object store cannot move under them, since Crewlet refuses to
start a node that names another store than the one it recorded, so the
backend a volume and a window were sized for is the one it runs with.



_Appears in:_
- [EngineClass](#engineclass)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `allowedNamespaces` _[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.37/#labelselector-v1-meta)_ | allowedNamespaces selects, by their labels, the namespaces whose<br />Companies may run with this class, as a Gateway's<br />allowedRoutes.namespaces.selector does; a Company in any other<br />namespace is not accepted (Accepted=False, ClassNotAllowed). Unset, or<br />an empty selector, admits every namespace.<br />Running with a class is a privilege, and any subject that may write a<br />Company may name any class: the class carries the platform's Secrets<br />it references (platform model keys, telemetry headers, env values)<br />into each of its companies' namespaces and engines, its workload<br />identity onto the engine ServiceAccount, and its scheduling onto the<br />platform's nodes. A class with any of those should name the<br />namespaces it is for. To select namespaces by name, match the label<br />kubernetes.io/metadata.name, which the API server sets on every<br />namespace. |  | Optional: \{\} <br /> |
| `engine` _[EngineSettings](#enginesettings)_ | engine is the engine image. |  | Required: \{\} <br /> |
| `data` _[DataPodSettings](#datapodsettings)_ | data sizes the pods that hold each company's estate. |  | Required: \{\} <br /> |
| `seatPools` _[SeatPoolSettings](#seatpoolsettings)_ | seatPools is whether each company may run seats on stateless pods of<br />its own, and how many. | \{ policy:Forbidden \} | MinProperties: 1 <br />Optional: \{\} <br /> |
| `stream` _[StreamSettings](#streamsettings)_ | stream is how each company's event stream runs. | \{ mode:Embedded \} | MinProperties: 1 <br />Optional: \{\} <br /> |
| `objects` _[ObjectSettings](#objectsettings)_ | objects is where each company's files are kept. | \{ backend:NATS \} | MinProperties: 1 <br />Optional: \{\} <br /> |
| `exposure` _[ExposureSettings](#exposuresettings)_ | exposure is how each company is reached from outside its namespace. | \{ api:map[mode:ClusterInternal] artifacts:map[mode:None] webhooks:map[mode:None] \} | MinProperties: 1 <br />Optional: \{\} <br /> |
| `networkPolicy` _[NetworkPolicySettings](#networkpolicysettings)_ | networkPolicy is the NetworkPolicy the operator puts around each<br />company's engine pods. | \{ mode:Isolated \} | MinProperties: 1 <br />Optional: \{\} <br /> |
| `podTemplate` _[EnginePodTemplate](#enginepodtemplate)_ | podTemplate is what is added to every engine pod. |  | MinProperties: 1 <br />Optional: \{\} <br /> |
| `serviceAccount` _[EngineServiceAccount](#engineserviceaccount)_ | serviceAccount is what is added to each company's engine<br />ServiceAccount. |  | MinProperties: 1 <br />Optional: \{\} <br /> |
| `service` _[EngineService](#engineservice)_ | service is what is added to each company's engine Service, which the<br />class's routes send to. |  | MinProperties: 1 <br />Optional: \{\} <br /> |
| `platformLLMProviders` _[PlatformLLMProvider](#platformllmprovider) array_ | platformLLMProviders are model providers the platform offers to<br />companies that opt in. |  | MaxItems: 16 <br />Optional: \{\} <br /> |
| `limits` _[EngineLimits](#enginelimits)_ | limits caps what a company may declare. |  | MinProperties: 1 <br />Optional: \{\} <br /> |
| `telemetry` _[TelemetrySettings](#telemetrysettings)_ | telemetry sends the engine's traces to a collector. Unset exports<br />nothing. |  | Optional: \{\} <br /> |
| `retention` _[RetentionSettings](#retentionsettings)_ | retention is who answers for backups. |  | Optional: \{\} <br /> |
| `signIn` _[SignInSettings](#signinsettings)_ | signIn is how people prove who they are when they sign in to each<br />company's dashboard. Unset, everyone gives a second factor, as<br />Crewlet requires by default. |  | MinProperties: 1 <br />Optional: \{\} <br /> |


#### EngineClassStatus



EngineClassStatus is what the operator observed about an EngineClass.

_Validation:_
- MinProperties: 1

_Appears in:_
- [EngineClass](#engineclass)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.37/#condition-v1-meta) array_ | conditions has Accepted: whether the objects the class names in other<br />namespaces exist, which its schema cannot check. It is False with<br />SecretNotFound when a Secret or key the class references does not<br />exist, GatewayAPINotInstalled when it routes through Gateways on a<br />cluster without the Gateway API, and GatewayNotFound when a Gateway<br />a route names with its namespace does not exist. Companies of a class<br />that is not accepted still run, and report what the problem does to<br />them on their own conditions. |  | MaxItems: 8 <br />Optional: \{\} <br /> |
| `observedGeneration` _integer_ | observedGeneration is the metadata.generation this status describes. |  | Minimum: 1 <br />Optional: \{\} <br /> |


#### EngineConfigEntry



EngineConfigEntry is one top-level key of the company document that
spec.engineConfig passes through, and its value.



_Appears in:_
- [CompanySpec](#companyspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `name` _string_ | name is the key, as Crewlet spells it, such as turn_engine. |  | MaxLength: 63 <br />MinLength: 1 <br />Pattern: `^[a-z][a-z0-9_]*$` <br />Required: \{\} <br /> |
| `value` _[EngineConfigValue](#engineconfigvalue)_ | value is the key's value: an object, a list, a string, a number or a<br />boolean, kept as written. |  | Type:  <br />Required: \{\} <br /> |


#### EngineConfigValue



EngineConfigValue is any JSON value, kept byte for byte as it was written.

_Validation:_
- Type: 

_Appears in:_
- [EngineConfigEntry](#engineconfigentry)



#### EngineLimits



EngineLimits caps what a Company of a class may declare. The operator
refuses to apply a company that exceeds a limit and reports it on the
Company. A control plane should refuse such a request before it writes the
Company; this is the cluster's defence in depth.

_Validation:_
- MinProperties: 1

_Appears in:_
- [EngineClassSpec](#engineclassspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `maxSeats` _integer_ | maxSeats is the most Seats a Company may have. Unset is unlimited. |  | Minimum: 0 <br />Optional: \{\} <br /> |
| `maxMCPServers` _integer_ | maxMCPServers is the most MCPServers a Company may have. Unset is<br />unlimited. |  | Minimum: 0 <br />Optional: \{\} <br /> |


#### EnginePodMetadata



EnginePodMetadata is metadata added to every engine pod.

_Validation:_
- MinProperties: 1

_Appears in:_
- [EnginePodTemplate](#enginepodtemplate)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `labels` _object (keys:string, values:string)_ | labels are added to every engine pod. |  | MaxProperties: 32 <br />Optional: \{\} <br /> |
| `annotations` _object (keys:string, values:string)_ | annotations are added to every engine pod. |  | MaxProperties: 32 <br />Optional: \{\} <br /> |


#### EnginePodSpec



EnginePodSpec is the part of a pod's spec a class may set on engine pods.
It is a closed list rather than a whole PodSpec: the operator owns the
containers, volumes, probes and security context, because the engine's data
safety depends on them.

_Validation:_
- MinProperties: 1

_Appears in:_
- [EnginePodTemplate](#enginepodtemplate)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `nodeSelector` _object (keys:string, values:string)_ | nodeSelector constrains engine pods to nodes with these labels. |  | MaxProperties: 32 <br />Optional: \{\} <br /> |
| `tolerations` _[Toleration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.37/#toleration-v1-core) array_ | tolerations let engine pods run on tainted nodes. |  | MaxItems: 32 <br />Optional: \{\} <br /> |
| `affinity` _[Affinity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.37/#affinity-v1-core)_ | affinity is the engine pods' scheduling affinity. |  | Optional: \{\} <br /> |
| `topologySpreadConstraints` _[TopologySpreadConstraint](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.37/#topologyspreadconstraint-v1-core) array_ | topologySpreadConstraints spread engine pods across topology domains. |  | MaxItems: 8 <br />Optional: \{\} <br /> |
| `runtimeClassName` _string_ | runtimeClassName is the RuntimeClass engine pods run with, for example<br />a sandboxed runtime such as gVisor. |  | MaxLength: 253 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `priorityClassName` _string_ | priorityClassName is the PriorityClass of engine pods. |  | MaxLength: 253 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `env` _[ClassEnvVar](#classenvvar) array_ | env adds environment variables to the engine container of every<br />Company of the class: platform wiring that is the same for all of<br />them, such as the address of the platform's own API. Every value,<br />one from a Secret included, reaches every tenant of the class: code<br />the tenant runs in the engine's pod can read its environment. They are<br />the engine's environment, not that of the processes it starts: a Stdio<br />tool server is handed only the part Crewlet's allowlist names, such as<br />PATH and the TLS and proxy variables, a coding CLI that part and the<br />variables its Crewlet profile passes through, such as GeminiCLI's<br />GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION, a seat's Direct<br />executor run that part alone (the allowlist: PATH, the locale, TERM,<br />TZ, the TLS trust and proxy variables), and an E2B run none of it but<br />TZ, which Crewlet hands every executor run as the zone it reads a<br />limit's reset in (UTC where TZ names no zone it knows). So a<br />variable a tool server reads goes in its MCPServer's env<br />(docs/guides/tool-servers.md), one a coding CLI reads in the engine's<br />pod in its LLMProvider's spec.env, and one a seat's executor run reads<br />in the Seat's spec.sandbox.env. A Company's spec.runtime.env is merged over<br />this env by name. The same names are refused as there: those<br />starting with CREWLET_ or OTEL_, and ANTHROPIC_API_KEY and<br />OPENAI_API_KEY. |  | MaxItems: 32 <br />Optional: \{\} <br /> |


#### EnginePodTemplate



EnginePodTemplate is what a class adds to every engine pod.

_Validation:_
- MinProperties: 1

_Appears in:_
- [EngineClassSpec](#engineclassspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `metadata` _[EnginePodMetadata](#enginepodmetadata)_ | Refer to Kubernetes API documentation for fields of `metadata`. |  | MinProperties: 1 <br />Optional: \{\} <br /> |
| `spec` _[EnginePodSpec](#enginepodspec)_ | spec is merged into every engine pod's spec. |  | MinProperties: 1 <br />Optional: \{\} <br /> |


#### EngineService



EngineService is what a class adds to the Service <company>-engine the
operator creates in front of each Company's data pods, which the class's
routes send to. It has no Crewlet field: the engine never sees its
Service.

_Validation:_
- MinProperties: 1

_Appears in:_
- [EngineClassSpec](#engineclassspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `annotations` _object (keys:string, values:string)_ | annotations are added to the Service, for a load balancer controller<br />that reads a backend's settings from it. On GKE an Ingress takes its<br />health check from cloud.google.com/backend-config, naming a<br />BackendConfig in each company's namespace: point its check at port<br />8080, path /ready, since the public port the webhooks' route sends to<br />answers 404 on every path it does not serve, / included. |  | MaxProperties: 16 <br />Optional: \{\} <br /> |


#### EngineServiceAccount



EngineServiceAccount is what a class adds to the ServiceAccount the operator
creates for each Company's engine pods.

_Validation:_
- MinProperties: 1

_Appears in:_
- [EngineClassSpec](#engineclassspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `annotations` _object (keys:string, values:string)_ | annotations are added to the ServiceAccount, for a workload identity<br />that is bound through one: eks.amazonaws.com/role-arn for IRSA,<br />iam.gke.io/gcp-service-account for GKE Workload Identity. That is how<br />the engine reaches an S3 bucket when its Company names no<br />spec.objects.credentialsSecretRef. The same annotations go on every<br />company's ServiceAccount, so the identity is every tenant's: scope it<br />per tenant (a role per company, or a session policy limited to the<br />company's prefix), or give each Company keys of its own instead. |  | MaxProperties: 16 <br />Optional: \{\} <br /> |


#### EngineSettings



EngineSettings is the engine image a class runs.



_Appears in:_
- [EngineClassSpec](#engineclassspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `image` _string_ | image is the Crewlet engine image, by tag or by digest, for example<br />registry.example.com/crewlet:v1.2.3. There is no default: the platform<br />decides which build its tenants run. A Company's spec.runtime.version<br />replaces the tag, so an image pinned by digest cannot be combined with<br />allowVersionOverride. |  | MaxLength: 512 <br />MinLength: 1 <br />Required: \{\} <br /> |
| `imagePullPolicy` _[PullPolicy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.37/#pullpolicy-v1-core)_ | imagePullPolicy is the pull policy of the engine container. Unset<br />takes the Kubernetes default for the image reference. |  | Enum: [Always IfNotPresent Never] <br />Optional: \{\} <br /> |
| `imagePullSecrets` _[LocalObjectReference](#localobjectreference) array_ | imagePullSecrets name Secrets in each Company's namespace that pull<br />the image. They are referenced, not copied: the platform puts them<br />into the tenant namespaces it creates. |  | MaxItems: 8 <br />Optional: \{\} <br /> |
| `allowVersionOverride` _boolean_ | allowVersionOverride lets a Company of this class choose its own engine<br />version with spec.runtime.version. Off by default: the platform<br />usually decides which version a class's tenants run. |  | Optional: \{\} <br /> |


#### EngineStatus



EngineStatus is what runs a company.

_Validation:_
- MinProperties: 1

_Appears in:_
- [CompanyStatus](#companystatus)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `image` _string_ | image is the engine image the data pods last ran on, recorded once<br />every data pod ran it and was ready. A rollout that has not finished<br />leaves the previous image here. |  | MaxLength: 512 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `version` _string_ | version is the tag of that image, such as v1.2.3; unset for an image<br />pinned by digest alone. The engine migrates its data forward only, so<br />the operator refuses to roll the data pods to an image whose tag is an<br />older semantic version than this one (RuntimeReady=False,<br />DowngradeRefused). The operator also records it on each data volume<br />claim (the annotation crewlet.ai/engine-version), which keeps the floor<br />when this status is lost. A version that never became ready is never<br />recorded, so a rollout that failed can still be taken back. |  | MaxLength: 128 <br />MinLength: 1 <br />Optional: \{\} <br /> |


#### EnvVar



EnvVar is an environment variable set on the engine's pods. Unlike
SecretEnvVar it may carry a literal value, because it is not a Crewlet
credential position but platform wiring (a feature flag, an endpoint); a
sensitive value is referenced from a Secret with valueFrom, which Kubernetes
resolves when it starts the container, so the value never appears in the pod
template.



_Appears in:_
- [CompanyRuntime](#companyruntime)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `name` _string_ | name is the variable's name. |  | MaxLength: 128 <br />MinLength: 1 <br />Pattern: `^[A-Za-z_][A-Za-z0-9_]*$` <br />Required: \{\} <br /> |
| `value` _string_ | value is the variable's literal value. An empty string is a valid<br />value, which is why the field is a pointer. |  | MaxLength: 4096 <br />Optional: \{\} <br /> |
| `valueFrom` _[SecretValueSource](#secretvaluesource)_ | valueFrom reads the value from a Secret key in the Company's namespace. |  | Optional: \{\} <br /> |


#### ExposureSettings



ExposureSettings is how a class's companies are reached.

_Validation:_
- MinProperties: 1

_Appears in:_
- [EngineClassSpec](#engineclassspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `webhooks` _[WebhookExposure](#webhookexposure)_ | webhooks is how vendors' webhooks reach the engine. | \{ mode:None \} | MinProperties: 1 <br />Optional: \{\} <br /> |
| `api` _[APIExposure](#apiexposure)_ | api is how the engine's API is reached. | \{ mode:ClusterInternal \} | MinProperties: 1 <br />Optional: \{\} <br /> |
| `artifacts` _[ArtifactExposure](#artifactexposure)_ | artifacts is how browsers reach the artifact origin. | \{ mode:None \} | MinProperties: 1 <br />Optional: \{\} <br /> |
| `trustedProxies` _string array_ | trustedProxies are the address blocks of what forwards requests to<br />the engine: the Gateway's proxies or the Ingress controller of the<br />class's routes, and whatever balances in front of them. Crewlet takes<br />a request's client address from its X-Forwarded-For header only when<br />the request arrives from one of these, and otherwise uses the address<br />it arrives from, which behind a proxy is the proxy's for every<br />caller: the sign-in throttle then counts everyone's attempts at one<br />login together, so a stranger guessing at a person's login holds up<br />that person's own sign-in, and the audit trail names the proxy. Each<br />is a canonical IPv4 or IPv6 CIDR narrower than the whole address<br />space; a single host is a /32 or /128. Unset, no forwarded header is<br />believed. Crewlet's api.trusted_proxies. |  | MaxItems: 16 <br />MinItems: 1 <br />items:MaxLength: 43 <br />Optional: \{\} <br /> |


#### ExternalExposure



ExternalExposure is where the forwarder of a class's webhooks runs, when
something outside the operator forwards them (webhooks.mode External).

_Validation:_
- MinProperties: 1

_Appears in:_
- [WebhookExposure](#webhookexposure)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `forwarders` _[NetworkPolicyPeer](#networkpolicypeer) array_ | forwarders are the pods that forward webhooks to the engine's public<br />port: a tunnel's or a relay's pods in the cluster. They are required<br />under networkPolicy Isolated, which admits them to that port and to<br />nothing else of the engine, and refused under any other mode, which<br />has no policy to admit them to. A forwarder outside the pod network (a<br />load balancer of your own that sends traffic from the nodes or from<br />outside the cluster) cannot be admitted by namespace: isolate those<br />engines with your CNI's own policy and networkPolicy.mode None. |  | MaxItems: 16 <br />MinItems: 1 <br />Optional: \{\} <br /> |


#### GatewayExposure



GatewayExposure attaches a company's routes to Gateways.



_Appears in:_
- [APIExposure](#apiexposure)
- [ArtifactExposure](#artifactexposure)
- [WebhookExposure](#webhookexposure)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `parentRefs` _[GatewayParentReference](#gatewayparentreference) array_ | parentRefs are the Gateways the HTTPRoute attaches to. |  | MaxItems: 8 <br />MinItems: 1 <br />Required: \{\} <br /> |
| `proxyNamespaces` _string array_ | proxyNamespaces are the namespaces the pods that carry the Gateways'<br />traffic run in. Under networkPolicy Isolated they are admitted to the<br />one port of the engine the route reaches: the public listener for the<br />webhooks' route, the API port for the API's, the artifact listener for<br />the artifacts'. Unset is the namespaces<br />of parentRefs, which is right for<br />implementations that run a proxy beside each Gateway (Istio, for<br />example); implementations with a shared data plane run it elsewhere<br />(Envoy Gateway in envoy-gateway-system, for example) and need it named<br />here. |  | MaxItems: 8 <br />MinItems: 1 <br />items:MaxLength: 63 <br />items:MinLength: 1 <br />items:Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$` <br />Optional: \{\} <br /> |


#### GatewayParentReference



GatewayParentReference names a Gateway API Gateway (or one listener of it)
that the operator attaches a company's HTTPRoute to.



_Appears in:_
- [GatewayExposure](#gatewayexposure)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `namespace` _string_ | namespace is the Gateway's namespace. Unset is the Company's own<br />namespace. |  | MaxLength: 63 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `name` _string_ | name is the Gateway's name. |  | MaxLength: 253 <br />MinLength: 1 <br />Required: \{\} <br /> |
| `sectionName` _string_ | sectionName is the name of one listener of the Gateway. Unset attaches<br />to every listener that accepts the route. |  | MaxLength: 253 <br />MinLength: 1 <br />Optional: \{\} <br /> |


#### GitHubApp



GitHubApp is the GitHub App a seat acts as. An app carries exactly one bot
identity, so every agent seat that works on GitHub has its own.



_Appears in:_
- [GitHubSeatIntegration](#githubseatintegration)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `id` _integer_ | id is the app's numeric id. Crewlet's `app_id`. |  | Minimum: 1 <br />Required: \{\} <br /> |
| `slug` _string_ | slug is the app's slug; the bot's login, and so how the seat is<br />mentioned, derives from it. Crewlet's `app_slug`. |  | MaxLength: 128 <br />MinLength: 1 <br />Pattern: `^[a-z0-9][a-z0-9-]*$` <br />Required: \{\} <br /> |
| `installationID` _integer_ | installationID is the app's installation on the organization. Unset<br />while the app is created but not yet installed. Crewlet's<br />`installation_id`. |  | Minimum: 1 <br />Optional: \{\} <br /> |
| `credentialsSecretRef` _[SecretReference](#secretreference)_ | credentialsSecretRef is a Secret holding the app's credentials under<br />the keys privateKey (the app's PEM key) and webhookSecret (which<br />verifies the app's own webhook deliveries). Crewlet's `private_key`<br />and `webhook_secret`, both credential positions. The Secret is the<br />seat's alone: Crewlet refuses one another seat or an Integration names<br />too. |  | Required: \{\} <br /> |


#### GitHubIntegration



GitHubIntegration turns GitHub on for a company: webhooks from github.com or
a GitHub Enterprise Server wake the seats they concern. It maps onto
Crewlet's integrations.github. Each agent seat's own GitHub App is in its
Seat's spec.integrations.github; the GitHub tools are an MCPServer.



_Appears in:_
- [IntegrationSpec](#integrationspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `url` _string_ | url is the base URL of a GitHub Enterprise Server, such as<br />https://github.example.com. Unset is github.com. Crewlet's `url`. |  | MaxLength: 2048 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `webhookSecretRef` _[SecretKeyReference](#secretkeyreference)_ | webhookSecretRef is the Secret key holding the secret that verifies<br />webhooks delivered to the company-wide route. Crewlet's<br />`webhook_secret`, a credential position. |  | Required: \{\} <br /> |
| `tokenSecretRef` _[SecretKeyReference](#secretkeyreference)_ | tokenSecretRef is the Secret key holding an organization token with<br />the admin:org_hook scope, which the engine registers the company's<br />webhooks with. Unset registers none. Crewlet's `token`, a credential<br />position. |  | Optional: \{\} <br /> |
| `provisioning` _[GitHubProvisioning](#githubprovisioning)_ | provisioning is where the webhooks are registered. It requires<br />tokenSecretRef, without which the engine registers nothing. |  | MinProperties: 1 <br />Optional: \{\} <br /> |


#### GitHubPermission

_Underlying type:_ _string_

GitHubPermission is how much of one GitHub App permission a seat holds. It
maps onto the level GitHub's API takes for it (Read is `read`, Write is
`write`), and the dashboard shows it under GitHub's names, Read-only and
Read and write. A permission left unset is GitHub's No access.

_Validation:_
- Enum: [Read Write]

_Appears in:_
- [GitHubPermissions](#githubpermissions)

| Field | Description |
| --- | --- |
| `Read` |  |
| `Write` |  |


#### GitHubPermissions



GitHubPermissions are the GitHub App permissions a seat holds, one field per
permission GitHub defines for an app, each under GitHub's own key. They map
onto Crewlet's role integrations.github.permissions. A permission left unset
is No access; Metadata, which GitHub grants every app read-only, is not
listed. The engine registers the seat's app with these permissions and
narrows each installation token to them, so lowering one applies to the next
token, and raising one past what the app was registered with waits for an
owner of the organization to accept the app's new permissions.

_Validation:_
- MinProperties: 1

_Appears in:_
- [GitHubSeatIntegration](#githubseatintegration)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `contents` _[GitHubPermission](#githubpermission)_ | contents is the repository's code, branches and releases. Crewlet's<br />`contents`. |  | Enum: [Read Write] <br />Optional: \{\} <br /> |
| `issues` _[GitHubPermission](#githubpermission)_ | issues is the repository's issues and their comments. Crewlet's<br />`issues`. |  | Enum: [Read Write] <br />Optional: \{\} <br /> |
| `pullRequests` _[GitHubPermission](#githubpermission)_ | pullRequests is the repository's pull requests, their reviews and<br />comments. Crewlet's `pull_requests`. |  | Enum: [Read Write] <br />Optional: \{\} <br /> |
| `checks` _[GitHubPermission](#githubpermission)_ | checks is the check runs and suites on the repository's commits.<br />Crewlet's `checks`. |  | Enum: [Read Write] <br />Optional: \{\} <br /> |
| `actions` _[GitHubPermission](#githubpermission)_ | actions is the repository's workflow runs and artifacts. Crewlet's<br />`actions`. |  | Enum: [Read Write] <br />Optional: \{\} <br /> |
| `deployments` _[GitHubPermission](#githubpermission)_ | deployments is the repository's deployments and their statuses.<br />Crewlet's `deployments`. |  | Enum: [Read Write] <br />Optional: \{\} <br /> |
| `workflows` _[GitHubPermission](#githubpermission)_ | workflows lets the seat push a commit that changes a file under<br />.github/workflows, which GitHub refuses otherwise. GitHub offers it as<br />Read and write alone, and a push needs contents Write too. The same<br />grant lets<br />the seat's branches run a workflow it rewrote with the secrets the<br />repository hands its runs, so pair it with branch protection and<br />environment-scoped secrets. Crewlet's `workflows`. |  | Enum: [Read Write] <br />Optional: \{\} <br /> |


#### GitHubProvisioning



GitHubProvisioning is where the engine registers the company's webhooks at
GitHub. It maps onto Crewlet's integrations.github.provisioning. The engine
registers them with the organization token (tokenSecretRef); without one it
registers nothing and each seat's own app delivers its own webhooks.

_Validation:_
- MinProperties: 1

_Appears in:_
- [GitHubIntegration](#githubintegration)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `org` _string_ | org is the GitHub organization holding the repositories. Crewlet's<br />`org`. |  | MaxLength: 39 <br />MinLength: 1 <br />Pattern: `^[A-Za-z0-9-]+$` <br />Optional: \{\} <br /> |
| `repos` _string array_ | repos are repositories, as owner/name, to register a webhook on one by<br />one. Crewlet's `repos`. |  | MaxItems: 128 <br />items:MaxLength: 201 <br />items:Pattern: `^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$` <br />Optional: \{\} <br /> |
| `orgWebhook` _[ContainerWebhookMode](#containerwebhookmode)_ | orgWebhook is whether one organization hook replaces the<br />per-repository ones. Unset is Auto. Crewlet's `org_webhook`. |  | Enum: [Auto Require Never] <br />Optional: \{\} <br /> |


#### GitHubSeatIntegration



GitHubSeatIntegration is a seat's identity and access on GitHub. It maps
onto Crewlet's role integrations.github and needs the company's GitHub
Integration.



_Appears in:_
- [SeatIntegrations](#seatintegrations)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `enabled` _boolean_ | enabled is whether the seat is on GitHub. False keeps the block, and<br />the engine suspends the app's installation rather than uninstalling<br />it, so turning it back on needs no person. Crewlet's `enabled`. |  | Required: \{\} <br /> |
| `permissions` _[GitHubPermissions](#githubpermissions)_ | permissions are the GitHub App permissions the seat holds. Unset is<br />No access on every permission but Metadata. Crewlet's `permissions`. |  | MinProperties: 1 <br />Optional: \{\} <br /> |
| `repos` _string array_ | repos are the repositories the seat's tokens are narrowed to, as<br />owner/name. Unset is every repository the app's installation covers,<br />which is the organization's choice at GitHub. Where the Integration<br />lists provisioning repos, each must be one of them: Crewlet refuses<br />another, which the engine's dry run reports as Invalid on the Seat.<br />Crewlet's `repos`. |  | MaxItems: 64 <br />items:MaxLength: 201 <br />items:Pattern: `^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$` <br />Optional: \{\} <br /> |
| `app` _[GitHubApp](#githubapp)_ | app is the GitHub App the seat acts as. |  | Optional: \{\} <br /> |


#### GitHubSeatStatus



GitHubSeatStatus is the GitHub side of a seat, as the operator computed it.

_Validation:_
- MinProperties: 1

_Appears in:_
- [SeatIntegrationsStatus](#seatintegrationsstatus)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `webhookURL` _string_ | webhookURL is the URL the seat's GitHub App must deliver webhooks to,<br /><publicBaseURL>/webhooks/github/<handle>. Like the Slack requestURL it<br />is set whenever the Company has a GitHub Integration and a public base<br />URL, before the seat's app exists, and it never changes for a seat. |  | MaxLength: 2048 <br />MinLength: 1 <br />Optional: \{\} <br /> |


#### GitLabAccessLevel

_Underlying type:_ _string_

GitLabAccessLevel is a GitLab role, the level of a seat's membership in the
group and its projects, under GitLab's own name. It maps onto Crewlet's
access_level, the integer GitLab's Members API takes (Guest is 10, Planner
15, Reporter 20, Developer 30, Maintainer 40, Owner 50). Security Manager,
a beta GitLab leaves off by default, and Minimal Access, which grants an
agent nothing, are not offered. The token the engine mints follows the
role: below Developer it can read the API and the repositories but not
push.

_Validation:_
- Enum: [Guest Planner Reporter Developer Maintainer Owner]

_Appears in:_
- [GitLabSeatIntegration](#gitlabseatintegration)

| Field | Description |
| --- | --- |
| `Guest` |  |
| `Planner` |  |
| `Reporter` |  |
| `Developer` |  |
| `Maintainer` |  |
| `Owner` |  |


#### GitLabAccountOwner

_Underlying type:_ _string_

GitLabAccountOwner is where the engine creates the seats' GitLab service
accounts. It maps onto Crewlet's provisioning mode (Group is `group`,
Instance is `instance`).

_Validation:_
- Enum: [Group Instance]

_Appears in:_
- [GitLabEngineProvisioning](#gitlabengineprovisioning)

| Field | Description |
| --- | --- |
| `Group` | GitLabAccountOwnerGroup creates them under the group, which is all<br />GitLab.com offers.<br /> |
| `Instance` | GitLabAccountOwnerInstance creates them on a self-managed instance<br />itself, with an instance administrator's token.<br /> |


#### GitLabEngineProvisioning



GitLabEngineProvisioning is how the engine provisions the seats' GitLab
accounts under provisioning Engine. It maps onto Crewlet's
integrations.gitlab.provisioning: for each agent Seat whose
spec.integrations.gitlab is enabled, the engine creates a service account,
makes it a member of the group, or of the seat's projects, at the seat's
role, mints its token into an entry of its secret store it names for the
seat, and registers the webhook. Each seat's role and projects are on its
Seat.



_Appears in:_
- [GitLabIntegration](#gitlabintegration)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `group` _string_ | group is the top-level group, by its path, the service accounts join<br />and the webhook is registered on. Crewlet's `group`. |  | MaxLength: 255 <br />MinLength: 1 <br />Pattern: `^[A-Za-z0-9_.][A-Za-z0-9_./-]*$` <br />Required: \{\} <br /> |
| `adminTokenSecretRef` _[SecretKeyReference](#secretkeyreference)_ | adminTokenSecretRef is the Secret key holding a personal access token<br />with the api scope of an Owner of the group (of an instance<br />administrator, for accountOwner Instance), which creates and removes<br />the service accounts. Crewlet's `admin_token`, a credential position. |  | Required: \{\} <br /> |
| `accountOwner` _[GitLabAccountOwner](#gitlabaccountowner)_ | accountOwner is where the service accounts are created. Unset is<br />Group. Crewlet's `mode`. |  | Enum: [Group Instance] <br />Optional: \{\} <br /> |
| `usernamePrefix` _string_ | usernamePrefix is put before each seat's handle to form its account's<br />username, for a group shared with people. Crewlet's<br />`username_prefix`. |  | MaxLength: 32 <br />MinLength: 1 <br />Pattern: `^[A-Za-z0-9_.-]+$` <br />Optional: \{\} <br /> |
| `projects` _string array_ | projects are the projects, by path, a seat's spec.integrations.gitlab<br />projects may name, and the ones the webhook is registered on one by<br />one when no group hook is. Crewlet's `projects`. |  | MaxItems: 128 <br />items:MaxLength: 255 <br />items:MinLength: 1 <br />items:Pattern: `^[A-Za-z0-9_.][A-Za-z0-9_./-]*$` <br />Optional: \{\} <br /> |
| `groupWebhook` _[ContainerWebhookMode](#containerwebhookmode)_ | groupWebhook is whether one group hook replaces the per-project ones.<br />Unset is Auto. Crewlet's `group_webhook`. |  | Enum: [Auto Require Never] <br />Optional: \{\} <br /> |


#### GitLabIntegration



GitLabIntegration turns GitLab on for a company: webhooks from a GitLab
instance wake the seats they concern. It maps onto Crewlet's
integrations.gitlab. Each seat's GitLab account and access are in its
Seat's spec.integrations.gitlab.



_Appears in:_
- [IntegrationSpec](#integrationspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `url` _string_ | url is the instance's base URL, such as https://gitlab.com. Crewlet's<br />`url`. |  | MaxLength: 2048 <br />MinLength: 1 <br />Required: \{\} <br /> |
| `signingSecretRef` _[SecretKeyReference](#secretkeyreference)_ | signingSecretRef is the Secret key holding the signing token every<br />webhook delivery is verified against: whsec_ followed by the standard<br />base64 of 32 bytes, the only form GitLab signs with (its "Generate<br />signing token" button makes one). Crewlet's `signing_secret`, a<br />credential position. |  | Required: \{\} <br /> |
| `tokenSecretRef` _[SecretKeyReference](#secretkeyreference)_ | tokenSecretRef is the Secret key holding a personal access token with<br />the read_api scope, which the engine reads an issue's or merge<br />request's participants with, so that everyone in a thread hears its<br />activity. Unset routes to the people a delivery names only. Crewlet's<br />`token`, a credential position. |  | Optional: \{\} <br /> |
| `webhookName` _string_ | webhookName is the name of the hooks the engine registers, which is<br />how it tells its own from others on the instance: two deployments<br />watching one instance need two names. Unset is crewlet. Crewlet's<br />`webhook_name`. |  | MaxLength: 255 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `engineProvisioning` _[GitLabEngineProvisioning](#gitlabengineprovisioning)_ | engineProvisioning is how the engine creates the seats' accounts.<br />Required with provisioning Engine, and not allowed with External. |  | Optional: \{\} <br /> |


#### GitLabSeatIntegration



GitLabSeatIntegration is a seat's account and access on GitLab. It maps onto
Crewlet's role integrations.gitlab and needs the company's GitLab
Integration. Under its provisioning Engine the engine creates the seat's
service account, gives it the role in the projects, and mints its token.
Under External the account is made outside the engine, which changes
nothing at GitLab: enabled then turns the seat's own GitLab tools on and
off, and the engine reports the seat's access as managed outside Crewlet.



_Appears in:_
- [SeatIntegrations](#seatintegrations)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `enabled` _boolean_ | enabled is whether the seat is on GitLab. False keeps the account,<br />which the engine blocks and whose tokens it revokes, so its history<br />keeps its author and turning it back on needs no person. Crewlet's<br />`enabled`. |  | Required: \{\} <br /> |
| `accessLevel` _[GitLabAccessLevel](#gitlabaccesslevel)_ | accessLevel is the seat's GitLab role. One of it and memberRoleID is<br />required while the seat is on. Crewlet's `access_level`. |  | Enum: [Guest Planner Reporter Developer Maintainer Owner] <br />Optional: \{\} <br /> |
| `memberRoleID` _integer_ | memberRoleID is a custom role of the group, by its id, in place of<br />accessLevel: GitLab Ultimate only. The engine checks it against the<br />group's roles on every pass, and reports one that no longer exists<br />rather than falling back to another. Crewlet's `member_role_id`. |  | Minimum: 1 <br />Optional: \{\} <br /> |
| `projects` _string array_ | projects are the projects, by path, the seat is a member of. Unset is<br />the whole group. Where the Integration lists engineProvisioning<br />projects, each must be one of them, so a seat cannot widen the<br />company's reach: Crewlet refuses another, which the engine's dry run<br />reports as Invalid on the Seat. Crewlet's `projects`. |  | MaxItems: 128 <br />items:MaxLength: 255 <br />items:MinLength: 1 <br />items:Pattern: `^[A-Za-z0-9_.][A-Za-z0-9_./-]*$` <br />Optional: \{\} <br /> |


#### IngressExposure



IngressExposure puts a company's routes on an Ingress.



_Appears in:_
- [APIExposure](#apiexposure)
- [ArtifactExposure](#artifactexposure)
- [WebhookExposure](#webhookexposure)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `className` _string_ | className is the IngressClass. Unset uses the cluster's default class. |  | MaxLength: 253 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `annotations` _object (keys:string, values:string)_ | annotations are added to the Ingress, for the controller that serves it<br />or a certificate controller. |  | MaxProperties: 32 <br />Optional: \{\} <br /> |
| `tls` _[IngressTLS](#ingresstls)_ | tls terminates TLS on the Ingress. Unset serves plain HTTP, which is<br />right only behind something else that terminates TLS: vendors deliver<br />webhooks over HTTPS only. |  | Optional: \{\} <br /> |
| `controllerNamespaces` _string array_ | controllerNamespaces are the namespaces the Ingress controller's pods<br />run in. Under networkPolicy Isolated they are admitted to the one port<br />of the engine the Ingress reaches (the public listener for the<br />webhooks' Ingress, the API port for the API's, the artifact listener<br />for the artifacts'), and they are required<br />there: an Ingress does not say which pods<br />serve it, and without them the policy would refuse every request the<br />Ingress forwards. |  | MaxItems: 8 <br />MinItems: 1 <br />items:MaxLength: 63 <br />items:MinLength: 1 <br />items:Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$` <br />Optional: \{\} <br /> |


#### IngressTLS



IngressTLS terminates TLS on a company's Ingress.



_Appears in:_
- [IngressExposure](#ingressexposure)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `secretName` _string_ | secretName is the TLS Secret, in the Company's namespace, the Ingress<br />presents. It is a template like the hostname: \{\{namespace\}\}, \{\{name\}\}<br />and \{\{uid\}\} are replaced. A certificate controller that issues<br />certificates from Ingress annotations creates it; set those annotations<br />under ingress.annotations. |  | MaxLength: 253 <br />MinLength: 1 <br />Required: \{\} <br /> |


#### Integration



Integration connects a company to a vendor (Slack, GitHub, GitLab,
Mattermost, Jira, Confluence, Datadog or an Atlassian organization): the
company-wide settings, the credentials that verify the vendor's webhooks,
and, where the engine creates the seats' accounts, the administrator
credential it creates them with. Credentials that belong to one seat, such
as its own Slack app or its GitLab token, are on the Seat.





| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `apiVersion` _string_ | `crewlet.ai/v1alpha1` | | |
| `kind` _string_ | `Integration` | | |
| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.37/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. |  | Optional: \{\} <br /> |
| `spec` _[IntegrationSpec](#integrationspec)_ | spec is the integration's desired state. |  | Required: \{\} <br /> |
| `status` _[IntegrationStatus](#integrationstatus)_ | status is the integration's observed state. |  | MinProperties: 1 <br />Optional: \{\} <br /> |


#### IntegrationProvisioning

_Underlying type:_ _string_

IntegrationProvisioning is who creates the seats' accounts at a vendor, and
so where their credentials come from.

_Validation:_
- Enum: [External Engine]

_Appears in:_
- [IntegrationSpec](#integrationspec)

| Field | Description |
| --- | --- |
| `External` | IntegrationProvisioningExternal leaves the seats' accounts to someone<br />outside the engine (a person, a platform): each seat's credentials are<br />Secrets its Seat references, and the engine is given no administrator<br />credential, so it creates, changes and removes nothing at the vendor.<br /> |
| `Engine` | IntegrationProvisioningEngine has the engine create each agent seat's<br />account with an administrator credential the Integration references,<br />mint the account's credential into the engine's secret store, register<br />the company's webhooks, and heal all of it on a schedule. Seats name<br />the minted credentials as provisioned values.<br /> |


#### IntegrationSpec



IntegrationSpec connects a company to one vendor. Exactly one vendor member
is set; the Integration's kind of vendor cannot change, and a company has at
most one Integration per vendor (a second is reported as a conflict).

provisioning says who creates the seats' accounts at the vendor. Under
External (the default) someone else does, and every per-seat credential
comes from a Secret its Seat references; the Integration then holds no
administrator credential. Under Engine the engine creates them, from the
administrator credential the vendor member references, and seats name the
credentials it mints as provisioned values. The engine can create accounts
at GitLab, Mattermost, Datadog and Atlassian; Datadog and Atlassian are
always provisioned by the engine, and Slack, GitHub, Jira and Confluence
never are (the engine mints no credential there).



_Appears in:_
- [Integration](#integration)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `companyRef` _[CompanyReference](#companyreference)_ | companyRef names the Company this integration belongs to. Immutable. |  | Required: \{\} <br /> |
| `provisioning` _[IntegrationProvisioning](#integrationprovisioning)_ | provisioning is who creates the seats' accounts at the vendor. Unset<br />is External. |  | Enum: [External Engine] <br />Optional: \{\} <br /> |
| `slack` _[SlackIntegration](#slackintegration)_ | slack connects Slack. |  | Optional: \{\} <br /> |
| `github` _[GitHubIntegration](#githubintegration)_ | github connects GitHub. |  | Optional: \{\} <br /> |
| `gitlab` _[GitLabIntegration](#gitlabintegration)_ | gitlab connects GitLab. |  | Optional: \{\} <br /> |
| `mattermost` _[MattermostIntegration](#mattermostintegration)_ | mattermost connects Mattermost. |  | Optional: \{\} <br /> |
| `jira` _[JiraIntegration](#jiraintegration)_ | jira connects Jira. |  | Optional: \{\} <br /> |
| `confluence` _[ConfluenceIntegration](#confluenceintegration)_ | confluence connects Confluence. |  | Optional: \{\} <br /> |
| `datadog` _[DatadogIntegration](#datadogintegration)_ | datadog connects Datadog. |  | Optional: \{\} <br /> |
| `atlassian` _[AtlassianIntegration](#atlassianintegration)_ | atlassian connects an Atlassian Cloud organization. |  | Optional: \{\} <br /> |


#### IntegrationStatus



IntegrationStatus is what the operator observed about an Integration.

_Validation:_
- MinProperties: 1

_Appears in:_
- [Integration](#integration)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.37/#condition-v1-meta) array_ | conditions are Accepted (the Company exists and has no other<br />Integration for the vendor), ResolvedRefs (every Secret key exists),<br />Applied (the integration is in the revision the engine runs) and<br />Healthy (the engine's own check of the vendor passes). |  | MaxItems: 8 <br />Optional: \{\} <br /> |
| `observedGeneration` _integer_ | observedGeneration is the metadata.generation this status describes. |  | Minimum: 1 <br />Optional: \{\} <br /> |
| `webhookURL` _string_ | webhookURL is the company-wide URL the vendor delivers webhooks to,<br />when the company is exposed and the vendor has one:<br /><publicBaseURL>/webhooks/<vendor> for GitHub, GitLab, Jira,<br />Confluence (a Data Center instance's; Confluence Cloud delivers to<br /><webhookURL>/<event>, a hook the engine registers per event) and<br />Datadog. Slack, Mattermost and Atlassian have none; Slack's and<br />GitHub's per-seat URLs are in each Seat's status. |  | MaxLength: 2048 <br />MinLength: 1 <br />Optional: \{\} <br /> |


#### JiraIntegration



JiraIntegration turns Jira on for a company: webhooks from a Jira site wake
the seats they concern, and the company may run Jira as its tracker (the
Company's spec.tracker.backend Jira). It maps onto Crewlet's
integrations.jira. Each seat's Jira identity is its own token, a credential
of the MCPServer named atlassian (or jira) in its Seat's spec.mcp.



_Appears in:_
- [IntegrationSpec](#integrationspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `url` _string_ | url is a Data Center instance's or a Cloud site's base URL. Unset<br />with cloudID unset, the company's Atlassian Integration discovers the<br />site. Crewlet's `url`. |  | MaxLength: 2048 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `cloudID` _string_ | cloudID is an Atlassian Cloud site's id; requests go through the API<br />gateway of the Cloud siteURL is on: Atlassian Government Cloud's,<br />api.atlassian-us-gov-mod.com, for a site under<br />atlassian-us-gov-mod.net, and api.atlassian.com otherwise. Crewlet's<br />`cloud_id`. |  | MaxLength: 64 <br />MinLength: 1 <br />Pattern: `^[A-Za-z0-9-]+$` <br />Optional: \{\} <br /> |
| `siteURL` _string_ | siteURL is the site's address as a browser opens it, for the links<br />the engine hands people; needed with cloudID, whose gateway address<br />opens nothing in a browser, and which is read through the gateway of<br />this site's Cloud. Unset is url. Crewlet's `site_url`. |  | MaxLength: 2048 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `email` _string_ | email is the account's address, for Jira Cloud's basic<br />authentication. Unset sends the token as a bearer token, as a service<br />account and a Data Center personal access token want. Crewlet's<br />`email`. |  | MaxLength: 254 <br />MinLength: 3 <br />Pattern: `^[^@\s]+@[^@\s]+$` <br />Optional: \{\} <br /> |
| `tokenSecretRef` _[SecretKeyReference](#secretkeyreference)_ | tokenSecretRef is the Secret key holding the API token (Cloud) or<br />personal access token (Data Center) of an administrator account. The<br />engine reads an issue's watchers with it, which no webhook carries,<br />and registers the company's webhook. Crewlet's `token`, a credential<br />position. |  | Required: \{\} <br /> |
| `webhookSecretRef` _[SecretKeyReference](#secretkeyreference)_ | webhookSecretRef is the Secret key holding the secret webhook<br />deliveries are signed with. Required for a Data Center instance, whose<br />route answers none without it; on Cloud, webhooks the engine<br />registers are signed with it, and the Forge relay needs none.<br />Crewlet's `webhook_secret`, a credential position. |  | Optional: \{\} <br /> |
| `webhookName` _string_ | webhookName is the name of the webhook the engine registers, which is<br />how it tells its own from others on the site: two deployments<br />watching one site need two names. Unset is crewlet. Crewlet's<br />`webhook_name`. |  | MaxLength: 255 <br />MinLength: 1 <br />Optional: \{\} <br /> |


#### JiraSeatIntegration



JiraSeatIntegration is a seat's access on Jira. It maps onto Crewlet's role
integrations.jira and needs the company's Jira Integration. With the
company's Atlassian Integration the engine creates the seat's account,
grants it Jira and gives it the project role in the projects; without one
(a Data Center instance) the account is made outside the engine, and the
engine reports the seat's access as managed outside Crewlet.



_Appears in:_
- [SeatIntegrations](#seatintegrations)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `enabled` _boolean_ | enabled is whether the seat is on Jira. False takes the account out of<br />its project roles and narrows its token, and keeps the account and its<br />Jira product access. Crewlet's `enabled`. |  | Required: \{\} <br /> |
| `projectRole` _string_ | projectRole is the project role the seat holds in each of projects,<br />by its id on the site (GET /rest/api/3/role), such as 10101. What a<br />role may do is each project's permission scheme. The engine checks it<br />against the site's roles on every pass, and reports one that no<br />longer exists rather than falling back to another. Required while<br />the seat is on in projects; with neither, the seat holds Jira product<br />access only. Crewlet's `project_role`. |  | MaxLength: 32 <br />MinLength: 1 <br />Pattern: `^[0-9]+$` <br />Optional: \{\} <br /> |
| `projects` _string array_ | projects are the projects, by key, the seat holds projectRole in.<br />Each must be a project the company's document names, as a Unit's or<br />a Seat's spec.project, so a seat cannot widen the company's reach:<br />Crewlet refuses another, which the engine's dry run reports as<br />Invalid on the Seat. Crewlet's `projects`. |  | MaxItems: 128 <br />items:MaxLength: 255 <br />items:MinLength: 1 <br />items:Pattern: `^[A-Z][A-Z0-9_]*$` <br />Optional: \{\} <br /> |


#### KnowledgeBackend

_Underlying type:_ _string_

KnowledgeBackend is which knowledge base a company runs. It maps onto
Crewlet's knowledge.backend (Doclet is `doclet`, Confluence is
`confluence`, None is `none`).

_Validation:_
- Enum: [Doclet Confluence None]

_Appears in:_
- [KnowledgeSettings](#knowledgesettings)

| Field | Description |
| --- | --- |
| `Doclet` | KnowledgeDoclet is Doclet, the engine's own knowledge base.<br /> |
| `Confluence` | KnowledgeConfluence is Confluence, connected by the company's<br />Confluence Integration.<br /> |
| `None` | KnowledgeNone is a company with no knowledge base.<br /> |


#### KnowledgeSettings



KnowledgeSettings is which knowledge base a company runs and how it is
searched. It maps onto Crewlet's knowledge block.

_Validation:_
- MinProperties: 1

_Appears in:_
- [CompanySpec](#companyspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `backend` _[KnowledgeBackend](#knowledgebackend)_ | backend is which knowledge base the company runs. | Doclet | Enum: [Doclet Confluence None] <br />Optional: \{\} <br /> |
| `scope` _string array_ | scope narrows every knowledge search to these containers. Empty<br />searches the whole company. Each is a container key, which Crewlet<br />requires to be an upper-case letter followed by 1 to 9 upper-case<br />letters or digits, such as PLAT. Crewlet's `scope`. |  | MaxItems: 64 <br />items:MaxLength: 10 <br />items:MinLength: 2 <br />items:Pattern: `^[A-Z][A-Z0-9]\{1,9\}$` <br />Optional: \{\} <br /> |
| `skillsContainer` _string_ | skillsContainer is the container holding tool-skill pages, a container<br />key (see scope). Unset takes Crewlet's default container; an empty<br />string turns tool skills off. Crewlet's `skills_container`. |  | MaxLength: 10 <br />Optional: \{\} <br /> |
| `rootSpace` _string_ | rootSpace is the container holding the company's own pages, such as<br />the root onboarding page, a container key (see scope). Unset takes<br />Crewlet's default. Crewlet's `root_space`. |  | MaxLength: 10 <br />MinLength: 2 <br />Pattern: `^[A-Z][A-Z0-9]\{1,9\}$` <br />Optional: \{\} <br /> |
| `vectors` _boolean_ | vectors fuses semantic recall into knowledge and work search; false<br />also stops embedding the corpus. Unset is on exactly when the company<br />has an embeddings provider; true requires one (spec.embeddings).<br />Crewlet's `vectors`. |  | Optional: \{\} <br /> |


#### LLMProvider



LLMProvider is a model a company's seats can run on: a coding CLI the
engine drives, one entry of Crewlet's providers.llm, keyed by its name. The
name default is refused: Crewlet runs a seat that names no chain on the
provider keyed default when there is one, whatever the Company's
spec.llm.order says.





| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `apiVersion` _string_ | `crewlet.ai/v1alpha1` | | |
| `kind` _string_ | `LLMProvider` | | |
| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.37/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. |  | Optional: \{\} <br /> |
| `spec` _[LLMProviderSpec](#llmproviderspec)_ | spec is the provider's desired state. |  | Required: \{\} <br /> |
| `status` _[LLMProviderStatus](#llmproviderstatus)_ | status is the provider's observed state. |  | MinProperties: 1 <br />Optional: \{\} <br /> |


#### LLMProviderKind

_Underlying type:_ _string_

LLMProviderKind is the kind of model provider a reference names.

_Validation:_
- Enum: [LLMProvider PlatformLLMProvider]

_Appears in:_
- [LLMProviderReference](#llmproviderreference)

| Field | Description |
| --- | --- |
| `LLMProvider` | LLMProviderKindLLMProvider is an LLMProvider in the referring object's<br />namespace.<br /> |
| `PlatformLLMProvider` | LLMProviderKindPlatform is an entry of the Company's EngineClass<br />spec.platformLLMProviders; the Company must set<br />spec.llm.usePlatformProviders.<br /> |


#### LLMProviderReference



LLMProviderReference names a model provider: an LLMProvider in the
referring object's namespace, or a provider the EngineClass offers.



_Appears in:_
- [CompanyAssistant](#companyassistant)
- [CompanyAssistantDeepWork](#companyassistantdeepwork)
- [CompanyLLMSettings](#companyllmsettings)
- [SeatLLM](#seatllm)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `kind` _[LLMProviderKind](#llmproviderkind)_ | kind is the kind of provider named. | LLMProvider | Enum: [LLMProvider PlatformLLMProvider] <br />Optional: \{\} <br /> |
| `name` _string_ | name is the LLMProvider's metadata.name, or the platform provider's<br />name. |  | MaxLength: 253 <br />MinLength: 1 <br />Required: \{\} <br /> |


#### LLMProviderSettings



LLMProviderSettings is what a company's model provider and a platform's
share: the coding CLI, the model it runs, and the bounds on its calls.
LLMProvider and the EngineClass's platform providers embed it, so a
platform-provided model is described exactly like a tenant's own. Each field
maps onto the same-named field of a Crewlet providers.llm entry.

Every model Crewlet runs is a coding CLI it drives: Claude Code for
Anthropic's models, on a subscription or an API key, Codex for OpenAI's,
OpenCode for open models on any provider. The CLI is a binary in the
engine's image, which the official image does not ship: a class running a
company's seats names an image derived from the engine's with the CLI
installed (docs/guides/cli-agents.md). For OpenCode that is OpenCode 2, the
@opencode/cli package: Crewlet drives no other release, and every command
it runs carries --standalone, which OpenCode 1.x (npm's opencode-ai)
rejects.

The cross-field rules over these fields are declared on each type that
embeds this one (LLMProviderSpec and PlatformLLMProvider), because
controller-gen does not carry a validation declared on an embedded type into
the schema of the type that inlines it. The API tests exercise both copies.



_Appears in:_
- [LLMProviderSpec](#llmproviderspec)
- [PlatformLLMProvider](#platformllmprovider)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `agent` _[CLIAgentName](#cliagentname)_ | agent is which CLI to drive. The model is written as this CLI reads<br />it, and a seat's executor run on the provider is handed it unchanged:<br />OpenCode reads `<provider>/<model>`, such as<br />`anthropic/claude-sonnet-5`. Only ClaudeCode and OpenCode run a<br />seat's executor; every CLI serves a seat's other phases. Crewlet's<br />`agent`. |  | Enum: [ClaudeCode Codex GeminiCLI QwenCode OpenCode CursorAgent Copilot Grok MuseCode KimiCode Hermes Pi] <br />Required: \{\} <br /> |
| `model` _string_ | model is the model the CLI runs, in the CLI's own grammar: an alias<br />or an id for ClaudeCode (`sonnet`, `claude-opus-5-5`), an OpenAI id<br />for Codex, `<provider>/<model>` for OpenCode. Crewlet's `model`.<br />Crewlet trims it of white space and refuses a provider with nothing<br />left, as naming no model. |  | MaxLength: 256 <br />MinLength: 1 <br />Required: \{\} <br /> |
| `timeoutSeconds` _integer_ | timeoutSeconds bounds one stretch of the CLI's model work, wall clock,<br />with no call of a seat's tool in flight: from the CLI's launch, or the<br />answer to its last tool call, to its next tool call or its end, the<br />model's answer and the CLI's own retries in it. It is not a bound on<br />a run of the CLI, which asks the model many times and calls the<br />seat's tools between: a tool call stops the clock however long it<br />takes (a delegation, a slow tool server), and the next stretch starts<br />afresh. Unset takes Crewlet's default of 600, the ceiling Anthropic<br />documents for one answer of a current Claude model at its full<br />output. A timeout is retryable, so a seat's chain moves on to its<br />next provider. It bounds the phases the CLI runs in the engine's<br />process (the reviewer, delegated workers, the summariser, the judge);<br />a seat's executor run on the provider, its CLI's own run in a box, is<br />bounded by its round cap instead (the Company's<br />spec.sandbox.defaultMaxTurns and the Seat's spec.sandbox.maxTurns).<br />Crewlet's `timeout_seconds`. |  | Minimum: 1 <br />Optional: \{\} <br /> |
| `maxConcurrent` _integer_ | maxConcurrent is how many of the provider's CLI processes run at once<br />in each engine pod; each takes 200 to 450 MB of the pod's memory,<br />OpenCode's at the top of that range (docs/guides/cli-agents.md). One<br />process lives for a whole run of the CLI, many model requests and<br />tool calls long, and holds its place for all of it, so this is also<br />how many seats' runs the provider has going at once in a pod: a run<br />past it waits for a place. A model call made on the same provider<br />from inside one of a run's tool calls (a delegated worker's) borrows<br />the run's place rather than wait for another, which the runs holding<br />every place could leave it waiting for forever. Unset takes<br />Crewlet's default of 4. A seat's executor run takes none: it is a<br />process of its own box, and a seat runs one at a time. Crewlet's<br />`max_concurrent`. |  | Maximum: 64 <br />Minimum: 1 <br />Optional: \{\} <br /> |
| `webTools` _[CLIAgentWebTools](#cliagentwebtools)_ | webTools is whether the CLI keeps its own web tools. Unset is<br />Allowed, every seat's default. Denied is required of every provider<br />Ask Crewlet runs on (spec.assistant.llm), and<br />is refused for a CLI Crewlet has no way to turn the web off for: it<br />takes ClaudeCode, Codex, OpenCode or Pi. Crewlet's<br />`overrides.web_tools`. |  | Enum: [Allowed Denied] <br />Optional: \{\} <br /> |


#### LLMProviderSpec



LLMProviderSpec is one model provider of a company: a coding CLI the engine
drives. It renders to one entry of Crewlet's providers.llm, keyed by the
LLMProvider's metadata.name; Seats and the Company's model order refer to it
by that name.

Its login, and the per-seat homes the CLI keeps, are on the data volume, so
a restart or a new pod keeps them.

Its rules hold every credential to a variable Crewlet's profile for the
CLI reads, as Crewlet's own admission does (providers.llm.*): the engine
refuses a write that names a credential its CLI would never be given, so
the API refuses it on the object instead. The lists of CLIs the rules name
and the variables they quote are those whose profiles set token_env,
api_key_env, env_sign_in or sign_in_env in the engine the operator is tested
against, Crewlet's main; a test holds them to that engine's own verdict. The rules also keep env off the variables
Crewlet sets on every call to keep each seat's CLI inside its own home and
its call's working directory (HOME, the XDG directories, TMPDIR, and the
configuration directory or switch each CLI's profile names in config_env,
work_config_env and isolation_env): env is layered over them, so a value
there would replace that isolation for every seat on the provider, and
Crewlet refuses the document. A test holds that list to the engine's
refusals too.

A seat's executor, which does the seat's work, is its CLI's own agentic
run: the CLI's loop with its own shell and editor, fully permissioned, as
a headless run has nobody to answer a permission prompt, calling the
seat's tools as one MCP server through the engine's tool bridge. Crewlet
runs it on the first member of the seat's executor chain that drives
ClaudeCode or OpenCode, the CLIs it has an in-box runner for, and is not
sitting out its spent plan on the node, in a box placed by that member's
runIn, else by the Company's spec.sandbox.defaultRunIn: Direct, a process
of the engine pod that holds the seat, or E2B, the Company's E2B sandbox.
Every other CLI serves a seat's other phases alone (the reviewer,
delegated workers, the summariser and the judge), in the engine's pod.
Crewlet hands an executor run its provider's model exactly as the
provider's runs in the engine's pod pass it, so one model serves every
phase. A Direct box is seeded with the provider's login, its credential
files or the document OpenCode 2's export printed, and writes a refreshed
login back. An E2B box never receives it, as the login carries a refresh
token the engine keeps rotating, so there a Subscription login reaches the
run only as a variable of its environment, which for ClaudeCode is its
headless token and for OpenCode its model provider's key in env. Under
auth mode APIKey or Env no login is seeded in either cell: the key, or
env, is the sign-in, and it follows the run wherever it runs.



_Appears in:_
- [LLMProvider](#llmprovider)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `companyRef` _[CompanyReference](#companyreference)_ | companyRef names the Company this provider belongs to. Immutable. |  | Required: \{\} <br /> |
| `agent` _[CLIAgentName](#cliagentname)_ | agent is which CLI to drive. The model is written as this CLI reads<br />it, and a seat's executor run on the provider is handed it unchanged:<br />OpenCode reads `<provider>/<model>`, such as<br />`anthropic/claude-sonnet-5`. Only ClaudeCode and OpenCode run a<br />seat's executor; every CLI serves a seat's other phases. Crewlet's<br />`agent`. |  | Enum: [ClaudeCode Codex GeminiCLI QwenCode OpenCode CursorAgent Copilot Grok MuseCode KimiCode Hermes Pi] <br />Required: \{\} <br /> |
| `model` _string_ | model is the model the CLI runs, in the CLI's own grammar: an alias<br />or an id for ClaudeCode (`sonnet`, `claude-opus-5-5`), an OpenAI id<br />for Codex, `<provider>/<model>` for OpenCode. Crewlet's `model`.<br />Crewlet trims it of white space and refuses a provider with nothing<br />left, as naming no model. |  | MaxLength: 256 <br />MinLength: 1 <br />Required: \{\} <br /> |
| `timeoutSeconds` _integer_ | timeoutSeconds bounds one stretch of the CLI's model work, wall clock,<br />with no call of a seat's tool in flight: from the CLI's launch, or the<br />answer to its last tool call, to its next tool call or its end, the<br />model's answer and the CLI's own retries in it. It is not a bound on<br />a run of the CLI, which asks the model many times and calls the<br />seat's tools between: a tool call stops the clock however long it<br />takes (a delegation, a slow tool server), and the next stretch starts<br />afresh. Unset takes Crewlet's default of 600, the ceiling Anthropic<br />documents for one answer of a current Claude model at its full<br />output. A timeout is retryable, so a seat's chain moves on to its<br />next provider. It bounds the phases the CLI runs in the engine's<br />process (the reviewer, delegated workers, the summariser, the judge);<br />a seat's executor run on the provider, its CLI's own run in a box, is<br />bounded by its round cap instead (the Company's<br />spec.sandbox.defaultMaxTurns and the Seat's spec.sandbox.maxTurns).<br />Crewlet's `timeout_seconds`. |  | Minimum: 1 <br />Optional: \{\} <br /> |
| `maxConcurrent` _integer_ | maxConcurrent is how many of the provider's CLI processes run at once<br />in each engine pod; each takes 200 to 450 MB of the pod's memory,<br />OpenCode's at the top of that range (docs/guides/cli-agents.md). One<br />process lives for a whole run of the CLI, many model requests and<br />tool calls long, and holds its place for all of it, so this is also<br />how many seats' runs the provider has going at once in a pod: a run<br />past it waits for a place. A model call made on the same provider<br />from inside one of a run's tool calls (a delegated worker's) borrows<br />the run's place rather than wait for another, which the runs holding<br />every place could leave it waiting for forever. Unset takes<br />Crewlet's default of 4. A seat's executor run takes none: it is a<br />process of its own box, and a seat runs one at a time. Crewlet's<br />`max_concurrent`. |  | Maximum: 64 <br />Minimum: 1 <br />Optional: \{\} <br /> |
| `webTools` _[CLIAgentWebTools](#cliagentwebtools)_ | webTools is whether the CLI keeps its own web tools. Unset is<br />Allowed, every seat's default. Denied is required of every provider<br />Ask Crewlet runs on (spec.assistant.llm), and<br />is refused for a CLI Crewlet has no way to turn the web off for: it<br />takes ClaudeCode, Codex, OpenCode or Pi. Crewlet's<br />`overrides.web_tools`. |  | Enum: [Allowed Denied] <br />Optional: \{\} <br /> |
| `runIn` _[SandboxPlacement](#sandboxplacement)_ | runIn is where a seat's executor run launched on the provider happens:<br />Direct, a process of the engine pod that holds the seat, or E2B, the<br />Company's E2B sandbox, which spec.sandbox.e2b must then configure.<br />Unset takes the Company's spec.sandbox.defaultRunIn. It is read<br />wherever a seat's executor can launch on the provider: as the first<br />ClaudeCode or OpenCode member of its executor chain, and as a later<br />one a launch falls back to while the members before it sit out their<br />spent plans, so each run is placed by the member it runs on. Only<br />ClaudeCode and OpenCode take it, as only they run an executor.<br />Crewlet's `run_in`. |  | Enum: [Direct E2B] <br />Optional: \{\} <br /> |
| `auth` _[CLIAgentAuth](#cliagentauth)_ | auth is how the CLI signs in. Crewlet's `auth`. |  | MinProperties: 1 <br />Required: \{\} <br /> |
| `env` _[SecretEnvVar](#secretenvvar) array_ | env is extra environment of the CLI, in every phase a seat runs on the<br />provider, its executor run included. In the engine's pod the CLI does<br />not get the engine's environment: it gets the part Crewlet's<br />allowlist names, such as PATH and the TLS and proxy variables, and the<br />variables the CLI's Crewlet profile passes through, such as<br />GeminiCLI's GOOGLE_CLOUD_PROJECT, with a HOME, a TMPDIR and XDG<br />directories of its seat's own rather than the engine's.<br />So a variable the CLI needs beyond that is given here, such as the<br />address of a gateway a CLI reads from its environment (ClaudeCode's<br />ANTHROPIC_BASE_URL). It is how Hermes, Pi and OpenCode sign in under<br />auth mode Subscription or Env with no login of their own: their model<br />provider's key, under a name Crewlet reads as a credential, such as<br />OPENROUTER_API_KEY. Under auth mode Env it is the whole sign-in of<br />ClaudeCode too: a gateway's ANTHROPIC_AUTH_TOKEN, or a cloud<br />provider's switch (CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX,<br />CLAUDE_CODE_USE_FOUNDRY) with that provider's credentials, names it may<br />set under no other mode, which hands the CLI a credential of its own<br />beside them. It may not set the CLI's own token or key<br />variable, which auth owns, nor a variable Crewlet sets to keep the CLI<br />inside its seat's home and its call's working directory: HOME, the XDG<br />directories, TMPDIR, and the CLI's own configuration directory or<br />switch (docs/guides/cli-agents.md), nor TZ, as Crewlet hands every CLI<br />the engine's own zone and reads its limit resets in it. Under auth mode<br />Subscription it may<br />not set a variable Crewlet sets there to sign the CLI in with its<br />seat's login either: GeminiCLI's GOOGLE_GENAI_USE_GCA.<br />A seat's executor run on the provider, Direct or E2B, gets all of env,<br />beneath the Seat's own spec.sandbox.env, which wins a name: a<br />gateway's address and the bearer token it takes, a cloud switch such<br />as CLAUDE_CODE_USE_BEDROCK and its region, a proxy, so the run reaches<br />its model as the provider's other phases do. So under auth mode Env,<br />env signs an E2B run in as it signs the provider's other phases in. A<br />Seat whose spec.sandbox.env signs ClaudeCode in itself<br />keeps every sign-in of the provider's out of its runs, and the rest of<br />env in them. Crewlet's `env`, a credential position. |  | MaxItems: 32 <br />Optional: \{\} <br /> |
| `loginName` _string_ | loginName names the login, and the per-seat homes, the provider<br />keeps on the data volume. Providers of the company with the same<br />loginName that drive the same CLI share one login, which is how<br />several models run off one subscription; each CLI keeps its own<br />beside the others' (Crewlet's <state_dir>/<agent>), so one of another<br />CLI shares the directory and nothing in it. Unset is the provider's<br />own metadata.name. Crewlet's `state_dir`, as<br />/var/lib/crewlet/llm-cli/<loginName>. |  | MaxLength: 63 <br />MinLength: 1 <br />Pattern: `^[a-z0-9][a-z0-9-]*$` <br />Optional: \{\} <br /> |


#### LLMProviderStatus



LLMProviderStatus is what the operator observed about an LLMProvider.

_Validation:_
- MinProperties: 1

_Appears in:_
- [LLMProvider](#llmprovider)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.37/#condition-v1-meta) array_ | conditions are Accepted (the Company exists), ResolvedRefs (every<br />Secret key exists) and Applied (the provider is in the revision the<br />engine runs; False with SandboxPlacementNotOffered while a seat's<br />executor can launch on it in a cell the Company's spec.sandbox does<br />not configure). |  | MaxItems: 8 <br />Optional: \{\} <br /> |
| `observedGeneration` _integer_ | observedGeneration is the metadata.generation this status describes. |  | Minimum: 1 <br />Optional: \{\} <br /> |


#### LocalObjectReference



LocalObjectReference names another object of the kind the referring field
documents, in the referring object's own namespace.



_Appears in:_
- [DatadogRouteTo](#datadogrouteto)
- [EngineSettings](#enginesettings)
- [ScheduleTarget](#scheduletarget)
- [SeatSandbox](#seatsandbox)
- [SeatSpec](#seatspec)
- [UnitSpec](#unitspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `name` _string_ | name is the metadata.name of the referenced object. |  | MaxLength: 253 <br />MinLength: 1 <br />Required: \{\} <br /> |


#### MCPCredentialValue



MCPCredentialValue is one value a tool server is started with for a seat:
one of its credentials, from a Secret, or a setting that is no credential,
written as a literal value. Whether it is an
environment variable or a request header depends on the server's
transport, which is why its name follows the grammar of an HTTP header
name, of which an environment variable's name is a subset.

A literal value is for a setting such as a path: slack-mcp-server, for one,
keeps the channels its bot can see in a file named after the workspace
alone, so each seat names its own (SLACK_MCP_CHANNELS_CACHE), or seats on
one engine pod are shown each other's private channels. Crewlet treats every
value of mcp_env as a credential and masks it on every read, and cannot
tell a setting from a credential; the name can, so a name that says it
holds a credential, as Crewlet reads one (see MCPEnvVar), takes valueFrom.



_Appears in:_
- [MCPCredentials](#mcpcredentials)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `name` _string_ | name is the environment variable's name (Stdio) or the header's name<br />(HTTP). |  | MaxLength: 128 <br />MinLength: 1 <br />Pattern: `^[A-Za-z0-9!#$%&'*+.^_\|~-]+$` <br />Required: \{\} <br /> |
| `value` _string_ | value is a literal value, for a setting that is no credential. It<br />lands in the company document as written, where anyone who can read<br />this object reads it too. An empty string is a valid value, which is<br />why the field is a pointer. |  | MaxLength: 4096 <br />Optional: \{\} <br /> |
| `valueFrom` _[SecretValueSource](#secretvaluesource)_ | valueFrom is the Secret key a credential comes from. For a header the<br />value is the whole header, scheme included (for example "Bearer<br /><token>"). A credential the engine mints for a seat's account at a<br />vendor it provisions is never named here: the engine gives it to the<br />vendor's tool server itself, and refuses a credential of that vendor's<br />server here. |  | Optional: \{\} <br /> |


#### MCPCredentials



MCPCredentials are the values one tool server is started with for a seat:
environment variables for a Stdio server, request headers for an HTTP one.
They map onto one server's entry of Crewlet's mcp_env, a credential
position.

The server is named by a top-level name, as an imagePullSecrets entry names
its Secret, rather than by a nested reference, because name is the key of
the list that holds these: with a scalar key, server-side apply merges the
list entry by entry, so that one field manager (a control plane's GitHub
flow, say) can own the credentials of one server without owning, or
overwriting, every other server's.



_Appears in:_
- [SeatSpec](#seatspec)
- [UnitSpec](#unitspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `name` _string_ | name is the metadata.name of the MCPServer, in this namespace, the<br />values are for. |  | MaxLength: 253 <br />MinLength: 1 <br />Required: \{\} <br /> |
| `env` _[MCPCredentialValue](#mcpcredentialvalue) array_ | env are the values. For a Stdio server each is an environment<br />variable of its process; for an HTTP server each is a request header<br />(the name is the header's name). Names must differ in more than case:<br />HTTP header names are case-insensitive, so Authorization and<br />authorization are one header. |  | MaxItems: 32 <br />MinItems: 1 <br />Required: \{\} <br /> |


#### MCPEnvVar



MCPEnvVar is one variable of a Stdio tool server's environment, which every
instance of the server starts with: a credential, read from a Secret, or a
setting that is no credential, written as a literal value, such as the
address of the service the server reaches or a switch that turns one of its
tools on.

Crewlet treats a server's whole environment as credentials, masking every
value on every read, so it cannot tell the two apart; a name can. A name
says it holds a credential when one of its parts, cut at every character
that is not a letter or a digit and read without case, is KEY, KEYS,
APIKEY, ACCESSKEY, SECRETKEY, TOKEN, SECRET, PASSWORD, PASSWD, CREDENTIAL,
CREDENTIALS, AUTH, OAUTH or PAT, which is how Crewlet itself reads a
credential's name (cliprofile.IsCredentialName), or when it is one of the
HTTP headers that carry one, Authorization, Proxy-Authorization and
Cookie; such a name takes valueFrom, never a literal. So GITLAB_TOKEN,
TAVILY_API_KEY and X-Api-Key come from Secrets, and JIRA_URL or
SLACK_MCP_ADD_MESSAGE_TOOL may be written out. The rule keeps a credential
from being typed where a setting goes; a credential under a name that says
nothing (a URL with a password in it, say) is still yours to keep in a
Secret.



_Appears in:_
- [MCPServerSpec](#mcpserverspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `name` _string_ | name is the variable's name. |  | MaxLength: 128 <br />MinLength: 1 <br />Pattern: `^[A-Za-z_][A-Za-z0-9_]*$` <br />Required: \{\} <br /> |
| `value` _string_ | value is a literal value, for a setting that is no credential. It<br />lands in the company document as written, where anyone who can read<br />this object reads it too. An empty string is a valid value, which is<br />why the field is a pointer. |  | MaxLength: 4096 <br />Optional: \{\} <br /> |
| `valueFrom` _[SecretValueSource](#secretvaluesource)_ | valueFrom reads a credential from a Secret key. |  | Optional: \{\} <br /> |


#### MCPHeader



MCPHeader is one header of every request to an HTTP tool server, which every
instance of the server sends: a credential, read from a Secret, such as the
Authorization header, or a setting that is no credential, written as a
literal value, by the rule MCPEnvVar states.



_Appears in:_
- [MCPServerSpec](#mcpserverspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `name` _string_ | name is the header's name. |  | MaxLength: 128 <br />MinLength: 1 <br />Pattern: `^[A-Za-z0-9!#$%&'*+.^_\|~-]+$` <br />Required: \{\} <br /> |
| `value` _string_ | value is a literal value, for a setting that is no credential. It<br />lands in the company document as written, where anyone who can read<br />this object reads it too. An empty string is a valid value, which is<br />why the field is a pointer. |  | MaxLength: 4096 <br />Optional: \{\} <br /> |
| `valueFrom` _[SecretValueSource](#secretvaluesource)_ | valueFrom reads a credential from a Secret key, which holds the whole<br />header value, scheme included (for example "Bearer <token>"). |  | Optional: \{\} <br /> |


#### MCPSeatCredential



MCPSeatCredential is one per-seat credential a tool server reads. It maps
onto one entry of Crewlet's seat_credentials. The value is the engine's to
give each seat's instance; nothing here names a credential.



_Appears in:_
- [MCPServerSpec](#mcpserverspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `kind` _[SeatCredentialKind](#seatcredentialkind)_ | kind is the integration whose seat credential the server reads.<br />Crewlet's `kind`. |  | Enum: [Atlassian Datadog GitHub GitLab Mattermost Slack] <br />Required: \{\} <br /> |
| `field` _[SeatCredentialField](#seatcredentialfield)_ | field is which of an Atlassian account's credentials, its Token or<br />its Email. Unset is the integration's credential itself, an<br />Atlassian account's Token. Crewlet's `field`. |  | Enum: [Token Email] <br />Optional: \{\} <br /> |
| `key` _string_ | key is the variable (Stdio) or header (HTTP) the server reads it<br />under, which the server's transport decides. Crewlet's `key`. |  | MaxLength: 128 <br />MinLength: 1 <br />Pattern: `^[A-Za-z0-9!#$%&'*+.^_\|~-]+$` <br />Required: \{\} <br /> |
| `prefix` _string_ | prefix is text the value follows, such as "Bearer " for an<br />Authorization header. Crewlet's `prefix`. |  | MaxLength: 32 <br />MinLength: 1 <br />Optional: \{\} <br /> |


#### MCPServer



MCPServer is a Model Context Protocol tool server a company's agents call.

The name crewlet is reserved: the engine gives a seat's own tools that name,
as the one MCP server each run of its coding CLI calls them through, inside
an executor's box beside the servers its spec.sandbox.mcpServerRefs name.





| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `apiVersion` _string_ | `crewlet.ai/v1alpha1` | | |
| `kind` _string_ | `MCPServer` | | |
| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.37/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. |  | Optional: \{\} <br /> |
| `spec` _[MCPServerSpec](#mcpserverspec)_ | spec is the server's desired state. |  | Required: \{\} <br /> |
| `status` _[MCPServerStatus](#mcpserverstatus)_ | status is the server's observed state. |  | MinProperties: 1 <br />Optional: \{\} <br /> |


#### MCPServerSpec



MCPServerSpec is one tool server a company's agents call. It renders to one
entry of Crewlet's mcp_servers, named by the MCPServer's metadata.name;
Seats and Units give it per-seat values by that name.



_Appears in:_
- [MCPServer](#mcpserver)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `companyRef` _[CompanyReference](#companyreference)_ | companyRef names the Company this server belongs to. Immutable. |  | Required: \{\} <br /> |
| `transport` _[MCPTransport](#mcptransport)_ | transport is how the engine reaches the server. Crewlet's `transport`. | Stdio | Enum: [Stdio HTTP] <br />Optional: \{\} <br /> |
| `shared` _boolean_ | shared launches one instance whose tools every agent calls. false<br />makes the server a template instead: every agent seat that names it<br />in spec.mcp, its own or its unit's, gets an instance of its own,<br />which is how each agent acts as itself on the server. An entry of<br />settings alone starts one too, with none of the seat's credentials.<br />Crewlet's `shared`. | true | Optional: \{\} <br /> |
| `command` _string_ | command is the executable a Stdio server is launched with, as a process<br />of the engine's container, by the engine's user. It must be installed<br />in the engine image, and Crewlet's image ships no Python or Node.js<br />runtime (docs/guides/tool-servers.md). Crewlet's `command`, which it<br />passes on as written: it resolves no $\{NAME\} in it. |  | MaxLength: 1024 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `args` _string array_ | args are the executable's arguments. Crewlet's `args`, which it passes<br />on as written: it resolves no $\{NAME\} in them. |  | MaxItems: 64 <br />items:MaxLength: 4096 <br />Optional: \{\} <br /> |
| `env` _[MCPEnvVar](#mcpenvvar) array_ | env is the environment of a Stdio server's process, shared by every<br />instance; per-seat values belong in a Seat's or a Unit's spec.mcp,<br />which win over these. It is laid over the part of the engine's own<br />environment Crewlet hands a tool server: PATH, the locale, the TLS and<br />proxy variables and the engine user's HOME, among a few others<br />(docs/guides/tool-servers.md). Nothing else of the engine's<br />environment reaches the server: a variable the engine image sets with<br />ENV, or the class or the Company sets on the pod, reaches it only when<br />it is one of those, so every other variable the server reads is given<br />here. Crewlet's `env`, a credential position. |  | MaxItems: 32 <br />Optional: \{\} <br /> |
| `url` _string_ | url is the endpoint of an HTTP server. Crewlet's `url`. |  | MaxLength: 2048 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `headers` _[MCPHeader](#mcpheader) array_ | headers are sent with every request to an HTTP server, shared by every<br />instance; per-seat values belong in a Seat's or a Unit's spec.mcp.<br />Header names are case-insensitive, so names must differ in more than<br />case. Crewlet's `headers`, a credential position. |  | MaxItems: 32 <br />Optional: \{\} <br /> |
| `optionalKeys` _string array_ | optionalKeys names the keys whose value may go missing: variables of env<br />(Stdio) or headers (HTTP), and the values every Seat and Unit gives the<br />server in spec.mcp, which land in the same environment or the same headers.<br />Crewlet starts a server only once every value it is started with has one, so<br />a value read from a Secret that does not exist, holds no such key or holds<br />an empty value keeps the server from starting. Under a key listed here, such<br />a value is left out instead, whole: the server starts without the variable,<br />or its requests go without the header, as Kubernetes starts a container<br />without an optional secretKeyRef. A missing Secret or key under one is then<br />no failure of the references of the object that gives the value, and holds<br />nothing back. Under the Enforce policy the operator also takes the value it<br />pushed for it out of the engine's secret store, and has the engine read the<br />store again whether or not the document can be applied, so the server is not<br />started again with a deleted Secret's value, but by a revision the engine<br />runs that reads the key as required (one from before the key was listed) or<br />whose reading the operator does not know (another document somebody else<br />activated), which keeps the value until the next document runs, and that one<br />is activated once with it and at once again without it; a Secret key that is<br />also read where it is required holds the document while it is missing, and<br />keeps the value it had in a revision the engine runs that requires it too<br />until the document applies. A Seat's or a Unit's value for a key replaces<br />the server's whole, so one that goes missing leaves the key out rather than<br />handing the server's own value back; and a provisioned value an Integration<br />mints for a seat is waited for whatever this says. Every entry must name a<br />key at least one value read from a Secret, or provisioned, is written under,<br />here or in a Seat's or a Unit's spec.mcp for this server: one under which<br />every value is a literal, which is never missing, or no value at all, leaves<br />nothing out and holds the document (ResolvedRefs=False with<br />OptionalKeyUnused), as Crewlet refuses it. A Stdio server's keys are<br />compared as written, an HTTP server's without case, as headers are.<br />Crewlet's `optional_keys`. |  | MaxItems: 32 <br />items:MaxLength: 128 <br />items:MinLength: 1 <br />items:Pattern: `^[A-Za-z0-9!#$%&'*+.^_\|~-]+$` <br />Optional: \{\} <br /> |
| `seatCredentials` _[MCPSeatCredential](#mcpseatcredential) array_ | seatCredentials declare which integration's per-seat credential the<br />server reads, and under which variable (Stdio) or header (HTTP), so<br />the engine gives each seat's instance that seat's own credential: the<br />one it minted for the seat's account, or the one the Seat hands in<br />for an integration it does not provision. Unset, a server the engine<br />recognises by its command or address (glab mcp serve, slack-mcp-server,<br />mcp-server-mattermost, mcp-atlassian, GitHub's and Datadog's remote<br />servers) reads what the engine knows it reads; a declaration replaces<br />that. A shared server reads none. Crewlet's `seat_credentials`. |  | MaxItems: 8 <br />Optional: \{\} <br /> |
| `toolPrefix` _string_ | toolPrefix is put in front of the server's tool names, to keep them<br />apart from another server's. Crewlet's `tool_prefix`. |  | MaxLength: 32 <br />MinLength: 1 <br />Pattern: `^[A-Za-z][A-Za-z0-9_-]*$` <br />Optional: \{\} <br /> |
| `toolAnnotations` _[MCPToolAnnotations](#mcptoolannotations) array_ | toolAnnotations correct the hints individual tools advertise.<br />Crewlet's `tool_annotations`. |  | MaxItems: 128 <br />Optional: \{\} <br /> |
| `startupTimeoutSeconds` _integer_ | startupTimeoutSeconds bounds starting the server and the handshake,<br />and separately its first tool listing, so a start can take up to twice<br />it before Crewlet gives the server up. Unset takes Crewlet's default<br />of 120. Crewlet's `startup_timeout_seconds`. |  | Minimum: 1 <br />Optional: \{\} <br /> |
| `requestTimeoutSeconds` _integer_ | requestTimeoutSeconds bounds one tool call. Unset takes Crewlet's<br />default of 300. Crewlet's `request_timeout_seconds`. |  | Minimum: 1 <br />Optional: \{\} <br /> |


#### MCPServerStatus



MCPServerStatus is what the operator observed about an MCPServer.

_Validation:_
- MinProperties: 1

_Appears in:_
- [MCPServer](#mcpserver)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.37/#condition-v1-meta) array_ | conditions are Accepted (the Company exists), ResolvedRefs (every<br />Secret key exists) and Applied (the server is in the revision the<br />engine runs). |  | MaxItems: 8 <br />Optional: \{\} <br /> |
| `observedGeneration` _integer_ | observedGeneration is the metadata.generation this status describes. |  | Minimum: 1 <br />Optional: \{\} <br /> |


#### MCPToolAnnotations



MCPToolAnnotations corrects the behavioural hints one tool advertises. The
engine decides from them what a tool may be used for, such as whether a
delegated worker may call it. Each field maps onto Crewlet's
tool_annotations entry; unset keeps what the server says.



_Appears in:_
- [MCPServerSpec](#mcpserverspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `tool` _string_ | tool is the tool's name as the server publishes it, without any<br />prefix. |  | MaxLength: 128 <br />MinLength: 1 <br />Required: \{\} <br /> |
| `readOnly` _boolean_ | readOnly marks a tool that changes nothing. Crewlet's `read_only`. |  | Optional: \{\} <br /> |
| `destructive` _boolean_ | destructive marks a tool whose effect cannot be undone. Crewlet's<br />`destructive`. |  | Optional: \{\} <br /> |
| `idempotent` _boolean_ | idempotent marks a tool that can be repeated safely. Crewlet's<br />`idempotent`. |  | Optional: \{\} <br /> |
| `openWorld` _boolean_ | openWorld marks a tool that reaches outside the company. Crewlet's<br />`open_world`. |  | Optional: \{\} <br /> |


#### MCPTransport

_Underlying type:_ _string_

MCPTransport is how the engine reaches a tool server. It maps onto
Crewlet's mcp_servers[].transport (Stdio is `stdio`, HTTP is `http`).

_Validation:_
- Enum: [Stdio HTTP]

_Appears in:_
- [MCPServerSpec](#mcpserverspec)

| Field | Description |
| --- | --- |
| `Stdio` | MCPTransportStdio launches the server as a process next to the engine<br />and speaks to it over its standard input and output. The command must<br />exist in the engine image.<br /> |
| `HTTP` | MCPTransportHTTP connects to a remote server over Streamable HTTP.<br /> |


#### ManagedKind

_Underlying type:_ _string_

ManagedKind is the kind of object a seat manages.

_Validation:_
- Enum: [Seat Unit]

_Appears in:_
- [ManagedReference](#managedreference)

| Field | Description |
| --- | --- |
| `Seat` | ManagedKindSeat is a single Seat.<br /> |
| `Unit` | ManagedKindUnit is every seat of a Unit and of the units below it.<br /> |


#### ManagedReference



ManagedReference names a Seat or a Unit, in the referring Seat's namespace,
that a seat manages.



_Appears in:_
- [SeatSpec](#seatspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `kind` _[ManagedKind](#managedkind)_ | kind is the kind of object named. | Seat | Enum: [Seat Unit] <br />Optional: \{\} <br /> |
| `name` _string_ | name is the object's metadata.name. |  | MaxLength: 253 <br />MinLength: 1 <br />Required: \{\} <br /> |


#### ManagementPolicy

_Underlying type:_ _string_

ManagementPolicy says who owns a company's live document.

_Validation:_
- Enum: [Enforce Observe Seed]

_Appears in:_
- [ConfigSettings](#configsettings)

| Field | Description |
| --- | --- |
| `Enforce` | ManagementPolicyEnforce makes the operator the document's only<br />writer. The engine refuses every other credential a change to the<br />document (403 config_managed), the published access token and a person<br />signed in at its dashboard included, and its dashboard shows the<br />document read-only; a revision made some other way all the same (the<br />engine's own writes, or one made before the data pod restarted onto the<br />policy) is reported and overwritten.<br /> |
| `Observe` | ManagementPolicyObserve renders and compares, and never writes; a<br />difference is reported only. The engine's own users may change the<br />document.<br /> |
| `Seed` | ManagementPolicySeed writes the document once, into an engine that<br />has none, and then leaves it to the engine and its dashboard, whose<br />users may change it. Changes to the Company's children are ignored<br />afterwards and say so in their status.<br /> |


#### MattermostEngineProvisioning



MattermostEngineProvisioning is how the engine provisions the seats'
Mattermost bots under provisioning Engine. It maps onto Crewlet's
integrations.mattermost.provisioning: for each agent seat whose
spec.integrations.mattermost.botToken is provisioned, the engine creates a
bot, adds it to the team and the channels, and mints its token into that
value.



_Appears in:_
- [MattermostIntegration](#mattermostintegration)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `adminTokenSecretRef` _[SecretKeyReference](#secretkeyreference)_ | adminTokenSecretRef is the Secret key holding a system<br />administrator's personal access token, which creates and disables the<br />bots. Crewlet's `admin_token`, a credential position. |  | Required: \{\} <br /> |
| `usernamePrefix` _string_ | usernamePrefix is put before each seat's handle to form its bot's<br />username, for a server shared with people. Crewlet's<br />`username_prefix`. |  | MaxLength: 32 <br />MinLength: 1 <br />Pattern: `^[a-z0-9._-]+$` <br />Optional: \{\} <br /> |
| `channels` _string array_ | channels are channels, by name (the URL slug), every bot joins: a bot<br />hears only the channels it is in. Crewlet's `channels`. |  | MaxItems: 64 <br />items:MaxLength: 64 <br />items:MinLength: 1 <br />items:Pattern: `^[a-z0-9][a-z0-9_-]*$` <br />Optional: \{\} <br /> |
| `displayNameSuffix` _string_ | displayNameSuffix is put after each bot's display name, such as<br />" (AI)", to tell agents from people at a glance. Crewlet's<br />`display_name_suffix`. |  | MaxLength: 64 <br />MinLength: 1 <br />Optional: \{\} <br /> |


#### MattermostIntegration



MattermostIntegration turns Mattermost on for a company. It maps onto
Crewlet's integrations.mattermost. Mattermost delivers no webhook the engine
can use: the engine holds a websocket per seat's bot instead, so the
integration needs no public address. Each seat's bot is in its Seat's
spec.integrations.mattermost.



_Appears in:_
- [IntegrationSpec](#integrationspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `url` _string_ | url is the address the engine reaches the server at, such as<br />https://chat.example.com: each seat's websocket, the REST calls and<br />the bots' provisioning go to it. It need not be the server's Site URL,<br />which people browse and from which Mattermost builds its links; the<br />engine builds none from url. Any route to the server serves, such as<br />its in-cluster Service: the engine's websockets carry no Origin<br />header, so Mattermost's origin check, which holds a browser to the<br />Site URL, never applies to them. The server has to answer its API at<br />url without a redirect, which neither the engine nor the seats'<br />Mattermost tool server, given the same address as its MATTERMOST_URL,<br />follows: on the scheme that address is served on, and at the Site<br />URL's path, outside which Mattermost redirects every request.<br />Crewlet's `url`. |  | MaxLength: 2048 <br />MinLength: 1 <br />Required: \{\} <br /> |
| `team` _string_ | team is the team, by name (the URL slug), the bots belong to.<br />Crewlet's `team`. |  | MaxLength: 64 <br />MinLength: 1 <br />Pattern: `^[a-z0-9][a-z0-9_-]*$` <br />Required: \{\} <br /> |
| `typingStatus` _[WorkingStatus](#workingstatus)_ | typingStatus is when a seat shows that it is typing. Unset takes<br />Crewlet's default, Always; each indicator costs a request every few<br />seconds while the seat works. Crewlet's `typing_status`. |  | Enum: [Always Addressed] <br />Optional: \{\} <br /> |
| `engineProvisioning` _[MattermostEngineProvisioning](#mattermostengineprovisioning)_ | engineProvisioning is how the engine creates the seats' bots.<br />Required with provisioning Engine, and not allowed with External. |  | Optional: \{\} <br /> |


#### MattermostRole

_Underlying type:_ _string_

MattermostRole is a role or permission of a Mattermost account, under the
identifier Mattermost's API takes (SystemUser is `system_user`, the Member
role; SystemPostAllPublic is `system_post_all_public`, post:channels;
SystemPostAll is `system_post_all`, post:all; SystemAdmin is
`system_admin`, System Admin).

_Validation:_
- Enum: [SystemUser SystemPostAllPublic SystemPostAll SystemAdmin]

_Appears in:_
- [MattermostSeatIntegration](#mattermostseatintegration)

| Field | Description |
| --- | --- |
| `SystemUser` | MattermostSystemUser is Member, the role every account holds.<br /> |
| `SystemPostAllPublic` | MattermostSystemPostAllPublic is post:channels: post in every public<br />channel, a member or not.<br /> |
| `SystemPostAll` | MattermostSystemPostAll is post:all: post in every channel, private<br />ones and direct messages included.<br /> |
| `SystemAdmin` | MattermostSystemAdmin is System Admin, which grants every other<br />administration privilege of the server too.<br /> |


#### MattermostSeatIntegration



MattermostSeatIntegration is a seat's own Mattermost bot. It maps onto
Crewlet's role integrations.mattermost and needs the company's Mattermost
Integration. One credential covers everything the bot does: the websocket
the engine listens on, its REST calls, and the Mattermost tool server.
Under the Integration's provisioning Engine the engine creates the bot,
gives it the roles and the channels, and mints its token; under External
the bot is made outside the engine, and the engine reports its access as
managed outside Crewlet.



_Appears in:_
- [SeatIntegrations](#seatintegrations)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `enabled` _boolean_ | enabled is whether the seat is on Mattermost. False keeps the bot,<br />which the engine deactivates and whose tokens it revokes. Crewlet's<br />`enabled`. |  | Required: \{\} <br /> |
| `roles` _[MattermostRole](#mattermostrole) array_ | roles are the bot account's roles: Member (SystemUser) alone, or<br />Member with one of post:channels, post:all and System Admin. Required<br />while the seat is on. Crewlet's `roles`. |  | Enum: [SystemUser SystemPostAllPublic SystemPostAll SystemAdmin] <br />MaxItems: 4 <br />MinItems: 1 <br />Optional: \{\} <br /> |
| `channels` _string array_ | channels are the channels, by name (the URL slug), the bot is a<br />member of: it hears only the channels it is in. Where the Integration<br />lists engineProvisioning channels, each must be one of them: Crewlet<br />refuses another, which the engine's dry run reports as Invalid on the<br />Seat. Crewlet's `channels`. |  | MaxItems: 64 <br />items:MaxLength: 64 <br />items:MinLength: 1 <br />items:Pattern: `^[a-z0-9][a-z0-9_-]*$` <br />Optional: \{\} <br /> |
| `botToken` _[SecretValueSource](#secretvaluesource)_ | botToken is the Secret key holding the personal access token of a bot<br />made outside the engine, under a Mattermost Integration with<br />provisioning External. Under provisioning Engine leave it unset: the<br />engine creates the bot and mints its token, which no document names,<br />and refuses one given here. The Secret key is the seat's alone:<br />Crewlet refuses one another seat or a company block names too.<br />Crewlet's `bot_token`, a credential position. |  | Optional: \{\} <br /> |
| `username` _string_ | username is the bot's username, for a bot that exists under a name<br />other than the seat's handle (with the Integration's<br />engineProvisioning.usernamePrefix before it). Crewlet's `username`. |  | MaxLength: 64 <br />MinLength: 1 <br />Pattern: `^[a-z0-9][a-z0-9._-]*$` <br />Optional: \{\} <br /> |


#### NamespacedSecretEnvVar



NamespacedSecretEnvVar is a named credential an EngineClass gives, delivered
as an environment variable whose value is read from a Secret in a namespace
the platform controls, such as a platform model provider's key. Like
SecretEnvVar it takes no literal value, and like NamespacedSecretKeyReference
it is used only by the cluster-scoped EngineClass.



_Appears in:_
- [PlatformLLMProvider](#platformllmprovider)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `name` _string_ | name is the variable's name. |  | MaxLength: 128 <br />MinLength: 1 <br />Pattern: `^[A-Za-z_][A-Za-z0-9_]*$` <br />Required: \{\} <br /> |
| `valueFrom` _[NamespacedSecretValueSource](#namespacedsecretvaluesource)_ | valueFrom is the Secret key the value is read from. |  | Required: \{\} <br /> |


#### NamespacedSecretKeyReference



NamespacedSecretKeyReference selects one key of a Secret in a named
namespace. Only the cluster-scoped EngineClass uses it: a platform-owned
value (a managed LLM key, telemetry headers) lives in a namespace the
platform controls rather than in each tenant's. The value itself still
reaches every tenant that runs with it (see the field that references
it); the namespace keeps tenants from the platform's Secret, not from the
value.



_Appears in:_
- [NamespacedSecretValueSource](#namespacedsecretvaluesource)
- [PlatformLLMProviderAuth](#platformllmproviderauth)
- [TelemetrySettings](#telemetrysettings)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `namespace` _string_ | namespace is the namespace the Secret is in. |  | MaxLength: 63 <br />MinLength: 1 <br />Required: \{\} <br /> |
| `name` _string_ | name is the metadata.name of the Secret. |  | MaxLength: 253 <br />MinLength: 1 <br />Required: \{\} <br /> |
| `key` _string_ | key is the key within the Secret's data. |  | MaxLength: 253 <br />MinLength: 1 <br />Pattern: `^[-._a-zA-Z0-9]+$` <br />Required: \{\} <br /> |




#### NamespacedSecretValueSource



NamespacedSecretValueSource says where a value set by the cluster-scoped
EngineClass comes from: a Secret in a namespace the platform controls.



_Appears in:_
- [ClassEnvVar](#classenvvar)
- [NamespacedSecretEnvVar](#namespacedsecretenvvar)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `secretKeyRef` _[NamespacedSecretKeyReference](#namespacedsecretkeyreference)_ | secretKeyRef selects the Secret key that holds the value. |  | Required: \{\} <br /> |


#### NetworkPolicyEgress



NetworkPolicyEgress is where the engine may connect to, beyond DNS and
its own namespace.

_Validation:_
- MinProperties: 1

_Appears in:_
- [NetworkPolicySettings](#networkpolicysettings)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `exceptCIDRs` _string array_ | exceptCIDRs are address blocks the engine may not reach, besides the<br />cloud metadata endpoints. List the cluster's pod, Service and node<br />networks here: a NetworkPolicy has no other way to tell an address in<br />the cluster from one outside it, and without them an engine reaches<br />other tenants' pods, the Kubernetes API server and the nodes. Each is<br />a canonical IPv4 or IPv6 CIDR, narrower than the whole address space. |  | MaxItems: 32 <br />MinItems: 1 <br />items:MaxLength: 43 <br />Optional: \{\} <br /> |
| `to` _[NetworkPolicyPeer](#networkpolicypeer) array_ | to are pods in the cluster the engine may reach although<br />exceptCIDRs covers them: an in-cluster model gateway, the telemetry<br />collector, an object store. |  | MaxItems: 16 <br />MinItems: 1 <br />Optional: \{\} <br /> |


#### NetworkPolicyMode

_Underlying type:_ _string_

NetworkPolicyMode is whether the operator restricts traffic to the engine.

_Validation:_
- Enum: [Isolated None]

_Appears in:_
- [NetworkPolicySettings](#networkpolicysettings)

| Field | Description |
| --- | --- |
| `Isolated` | NetworkPolicyIsolated admits traffic to the engine's API port only<br />from the operator's pods, from the namespaces the Gateway proxies or<br />Ingress controller of the class's API route run in<br />(gateway.proxyNamespaces, ingress.controllerNamespaces), and from the<br />class's apiConsumers; to its public port only from where the webhooks'<br />route arrives from (the same fields of exposure.webhooks, or<br />webhooks.external.forwarders); and<br />lets the engine connect only as networkPolicy.egress says. It needs a<br />CNI that enforces NetworkPolicy, egress included.<br /> |
| `None` | NetworkPolicyNone creates no NetworkPolicy.<br /> |


#### NetworkPolicyPeer



NetworkPolicyPeer is the pods its podSelector selects in the namespaces
its namespaceSelector selects, as a NetworkPolicy peer that sets both.



_Appears in:_
- [ExternalExposure](#externalexposure)
- [NetworkPolicyEgress](#networkpolicyegress)
- [NetworkPolicySettings](#networkpolicysettings)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `namespaceSelector` _[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.37/#labelselector-v1-meta)_ | namespaceSelector selects namespaces by their labels; an empty one<br />selects every namespace. Select a namespace by name with the label<br />kubernetes.io/metadata.name, which the API server sets on every<br />namespace. |  | Required: \{\} <br /> |
| `podSelector` _[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.37/#labelselector-v1-meta)_ | podSelector selects pods in those namespaces by their labels. Unset<br />selects every pod in them. |  | Optional: \{\} <br /> |


#### NetworkPolicySettings



NetworkPolicySettings is the NetworkPolicy the operator puts around each
company's engine pods.

_Validation:_
- MinProperties: 1

_Appears in:_
- [EngineClassSpec](#engineclassspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `mode` _[NetworkPolicyMode](#networkpolicymode)_ | mode is whether the operator restricts the engine's traffic. | Isolated | Enum: [Isolated None] <br />Optional: \{\} <br /> |
| `apiConsumers` _[NetworkPolicyPeer](#networkpolicypeer) array_ | apiConsumers are the pods admitted to the engine's API port besides<br />the operator and the Gateway proxies or Ingress controller of the<br />class's API route, and to nothing else of the engine (the public<br />port, which the webhooks reach, admits only where they arrive from):<br />the platform's own components (a control plane, a dashboard) that<br />call the engines of this class's companies. Each holds an access<br />token, which the engine still requires. |  | MaxItems: 16 <br />MinItems: 1 <br />Optional: \{\} <br /> |
| `egress` _[NetworkPolicyEgress](#networkpolicyegress)_ | egress narrows where the engine may connect to. The engine runs code<br />the tenant supplies in its pod (stdio MCP servers, coding CLIs, and<br />what its agents have them do), so under Isolated its pods may reach<br />DNS, the pods of their own namespace, and every address outside the<br />cluster except the cloud metadata endpoints (169.254.169.254,<br />fd00:ec2::254), which hand out the node's credentials. What else is in<br />the cluster is unreachable only if listed in exceptCIDRs. A seat's<br />Direct executor run is a process of the engine pod, so it egresses<br />under this policy, its box's setup commands included: its vendor, its<br />code host and the package registries it installs from are reached<br />from the pod; it calls its tools and sends its traces to its own pod's<br />listener on loopback, which no policy polices. A data pod also calls<br />the Company's public address, for Ask Crewlet's deep work,<br />which Crewlet holds to it in whichever cell it runs. A call that lands<br />on the public route's proxies inside the cluster is admitted by a rule<br />of the data pods' own, naming the webhooks route's proxy namespaces or<br />the class's external forwarders; a load balancer the call leaves the<br />cluster through must stay outside exceptCIDRs. An E2B run happens in<br />the Company's E2B sandbox, which this policy does not reach. |  | MinProperties: 1 <br />Optional: \{\} <br /> |


#### ObjectBackend

_Underlying type:_ _string_

ObjectBackend is where a company's files are kept. It maps onto Crewlet's
store.objects.backend (NATS is `nats`, S3 is `s3`).

_Validation:_
- Enum: [NATS S3]

_Appears in:_
- [ObjectSettings](#objectsettings)

| Field | Description |
| --- | --- |
| `NATS` | ObjectBackendNATS keeps files in a bucket on the company's own event<br />stream, on the data volume.<br /> |
| `S3` | ObjectBackendS3 keeps files in an S3-compatible bucket.<br /> |


#### ObjectSettings



ObjectSettings is where a class's companies keep their files.

_Validation:_
- MinProperties: 1

_Appears in:_
- [EngineClassSpec](#engineclassspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `backend` _[ObjectBackend](#objectbackend)_ | backend is where files are kept. Changing it does not move existing<br />files. | NATS | Enum: [NATS S3] <br />Optional: \{\} <br /> |
| `s3` _[S3ObjectSettings](#s3objectsettings)_ | s3 is the bucket, for backend S3. |  | Optional: \{\} <br /> |


#### PlatformLLMProvider



PlatformLLMProvider is a model the platform offers to every Company of a
class that sets spec.llm.usePlatformProviders: a coding CLI, as a tenant's
own LLMProvider is, signed in with a key whose Secret lives in a namespace
the platform controls and is pushed into the secret store of each opted-in
company's engine.

That store is the tenant's to read: the engine's API reveals any value in
it to whoever holds the company's access token (status.apiAccessSecretRef
of the Company), and code the tenant runs in the engine's pod can open it
with the keyring the pod holds. So every opted-in tenant can read these
keys. Offer keys you would give each of them: one per tenant, or the
per-tenant virtual keys of an LLM gateway, never the platform's own.

It signs its CLI in with a key and nothing else: auth mode APIKey for a CLI
Crewlet hands a key to; auth mode Env, whose env signs the CLI in alone,
such as a ClaudeCode provider on the platform's gateway with the token it
issued the tenant in ANTHROPIC_AUTH_TOKEN; or, for Hermes, Pi and OpenCode,
which read their model provider's key from that provider's own variable,
the key in env. A
subscription's headless token or login is one account's, which every tenant
of the class would share: it belongs on a tenant's own LLMProvider. The
phases it serves in the engine's pod keep their per-seat homes on the data
volume under /var/lib/crewlet/llm-cli-platform/<name>, apart from every
tenant's loginName.

A ClaudeCode or OpenCode platform provider may also be the member a seat's
executor launches on, its CLI's own run, in the Company's
spec.sandbox.defaultRunIn, as a platform provider names no runIn: its key
is then in the tenant's engine pod, where the tenant reads it already, for
a Direct run, or in the tenant's E2B sandbox. That run gets its whole env,
as of an LLMProvider's, so a ClaudeCode platform provider whose env points
it at the platform's gateway (ANTHROPIC_BASE_URL) runs its seats'
executors through the gateway too, with the key it issued. Its rules are an
LLMProvider's that apply to such a provider, each with the same message's
start, and hold to the same engine.



_Appears in:_
- [EngineClassSpec](#engineclassspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `name` _string_ | name is the provider's name. Seats and the Company's model order refer<br />to it with kind PlatformLLMProvider. It may not be default, which<br />Crewlet would run every chainless seat of every opted-in company on,<br />whatever the company's own order says. |  | MaxLength: 63 <br />MinLength: 1 <br />Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$` <br />Required: \{\} <br /> |
| `agent` _[CLIAgentName](#cliagentname)_ | agent is which CLI to drive. The model is written as this CLI reads<br />it, and a seat's executor run on the provider is handed it unchanged:<br />OpenCode reads `<provider>/<model>`, such as<br />`anthropic/claude-sonnet-5`. Only ClaudeCode and OpenCode run a<br />seat's executor; every CLI serves a seat's other phases. Crewlet's<br />`agent`. |  | Enum: [ClaudeCode Codex GeminiCLI QwenCode OpenCode CursorAgent Copilot Grok MuseCode KimiCode Hermes Pi] <br />Required: \{\} <br /> |
| `model` _string_ | model is the model the CLI runs, in the CLI's own grammar: an alias<br />or an id for ClaudeCode (`sonnet`, `claude-opus-5-5`), an OpenAI id<br />for Codex, `<provider>/<model>` for OpenCode. Crewlet's `model`.<br />Crewlet trims it of white space and refuses a provider with nothing<br />left, as naming no model. |  | MaxLength: 256 <br />MinLength: 1 <br />Required: \{\} <br /> |
| `timeoutSeconds` _integer_ | timeoutSeconds bounds one stretch of the CLI's model work, wall clock,<br />with no call of a seat's tool in flight: from the CLI's launch, or the<br />answer to its last tool call, to its next tool call or its end, the<br />model's answer and the CLI's own retries in it. It is not a bound on<br />a run of the CLI, which asks the model many times and calls the<br />seat's tools between: a tool call stops the clock however long it<br />takes (a delegation, a slow tool server), and the next stretch starts<br />afresh. Unset takes Crewlet's default of 600, the ceiling Anthropic<br />documents for one answer of a current Claude model at its full<br />output. A timeout is retryable, so a seat's chain moves on to its<br />next provider. It bounds the phases the CLI runs in the engine's<br />process (the reviewer, delegated workers, the summariser, the judge);<br />a seat's executor run on the provider, its CLI's own run in a box, is<br />bounded by its round cap instead (the Company's<br />spec.sandbox.defaultMaxTurns and the Seat's spec.sandbox.maxTurns).<br />Crewlet's `timeout_seconds`. |  | Minimum: 1 <br />Optional: \{\} <br /> |
| `maxConcurrent` _integer_ | maxConcurrent is how many of the provider's CLI processes run at once<br />in each engine pod; each takes 200 to 450 MB of the pod's memory,<br />OpenCode's at the top of that range (docs/guides/cli-agents.md). One<br />process lives for a whole run of the CLI, many model requests and<br />tool calls long, and holds its place for all of it, so this is also<br />how many seats' runs the provider has going at once in a pod: a run<br />past it waits for a place. A model call made on the same provider<br />from inside one of a run's tool calls (a delegated worker's) borrows<br />the run's place rather than wait for another, which the runs holding<br />every place could leave it waiting for forever. Unset takes<br />Crewlet's default of 4. A seat's executor run takes none: it is a<br />process of its own box, and a seat runs one at a time. Crewlet's<br />`max_concurrent`. |  | Maximum: 64 <br />Minimum: 1 <br />Optional: \{\} <br /> |
| `webTools` _[CLIAgentWebTools](#cliagentwebtools)_ | webTools is whether the CLI keeps its own web tools. Unset is<br />Allowed, every seat's default. Denied is required of every provider<br />Ask Crewlet runs on (spec.assistant.llm), and<br />is refused for a CLI Crewlet has no way to turn the web off for: it<br />takes ClaudeCode, Codex, OpenCode or Pi. Crewlet's<br />`overrides.web_tools`. |  | Enum: [Allowed Denied] <br />Optional: \{\} <br /> |
| `auth` _[PlatformLLMProviderAuth](#platformllmproviderauth)_ | auth is how the CLI signs in. Crewlet's `auth`. |  | MinProperties: 1 <br />Required: \{\} <br /> |
| `env` _[NamespacedSecretEnvVar](#namespacedsecretenvvar) array_ | env is extra environment of the CLI, as an LLMProvider's spec.env is,<br />each value read from a Secret in a namespace the platform controls:<br />the model provider's key Hermes, Pi or OpenCode signs in with, the<br />address of the platform's gateway a CLI reads from its environment<br />(ClaudeCode's ANTHROPIC_BASE_URL), or, under auth mode Env, the token<br />that gateway issued the tenant (ANTHROPIC_AUTH_TOKEN), for every phase<br />the provider serves. ClaudeCode's sign-in names (ANTHROPIC_AUTH_TOKEN<br />and the CLAUDE_CODE_USE_* switches) are refused under every other<br />mode. A seat's executor run on the provider gets all of it, beneath<br />the Seat's own spec.sandbox.env, Direct on the tenant's engine pod or<br />in the tenant's own E2B sandbox, the gateway's address included.<br />Crewlet's `env`, a credential position. |  | MaxItems: 16 <br />Optional: \{\} <br /> |


#### PlatformLLMProviderAuth



PlatformLLMProviderAuth is how a platform provider signs its CLI in. It maps
onto the `auth` of a Crewlet providers.llm entry, as an LLMProvider's
CLIAgentAuth does, without the subscription's headless token and credential
bundle, which are one account's.

_Validation:_
- MinProperties: 1

_Appears in:_
- [PlatformLLMProvider](#platformllmprovider)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `mode` _[CLIAgentAuthMode](#cliagentauthmode)_ | mode is how the CLI signs in: APIKey, with apiKeySecretRef; Env, which<br />signs the CLI in with env alone, as an LLMProvider's auth mode Env<br />does; or Subscription, which signs Hermes, Pi or OpenCode in with its<br />model provider's key in env. Unset is Subscription. Crewlet's `mode`. |  | Enum: [Subscription APIKey Env] <br />Optional: \{\} <br /> |
| `apiKeySecretRef` _[NamespacedSecretKeyReference](#namespacedsecretkeyreference)_ | apiKeySecretRef is the Secret key holding the API key auth mode<br />APIKey hands the CLI, in the key variable Crewlet's profile for it<br />names. Crewlet's `api_key`, a credential position. |  | Optional: \{\} <br /> |


#### ProvisionedCredential



ProvisionedCredential is one of a seat's credentials the engine mints: an
Integration with provisioning Engine (GitLab, Mattermost, Datadog,
Atlassian) makes the seat's account at the vendor, mints the account's
credential, and seals it in the engine's own secret store under a name the
engine gives it for the seat, `<VENDOR>_<FIELD>_<HANDLE>`, such as
GITLAB_TOKEN_ANA. The engine hands it to the vendor's tool server itself;
naming it here hands it to the seat's executor runs too, such as the GitLab
token git uses in the seat's box. Nothing but the engine ever writes that
store entry: the operator pushes no value into it and deletes none it finds
there (ADR-0004).



_Appears in:_
- [SeatCredentialSource](#seatcredentialsource)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `vendor` _[ProvisionedVendor](#provisionedvendor)_ | vendor is the vendor whose account the credential is of. |  | Enum: [GitLab Mattermost Datadog Atlassian] <br />Required: \{\} <br /> |
| `field` _[ProvisionedField](#provisionedfield)_ | field is which of the account's credentials. |  | Enum: [Token Email AppKey BotToken] <br />Required: \{\} <br /> |


#### ProvisionedField

_Underlying type:_ _string_

ProvisionedField is one credential the engine mints for a seat's account at
a vendor. It maps onto the field in the engine's own name for it (Token is
`TOKEN`, Email `EMAIL`, AppKey `APP_KEY`, BotToken `BOT_TOKEN`).

_Validation:_
- Enum: [Token Email AppKey BotToken]

_Appears in:_
- [ProvisionedCredential](#provisionedcredential)

| Field | Description |
| --- | --- |
| `Token` |  |
| `Email` |  |
| `AppKey` |  |
| `BotToken` |  |


#### ProvisionedVendor

_Underlying type:_ _string_

ProvisionedVendor is a vendor whose seat accounts the engine creates, under
an Integration with provisioning Engine. It maps onto the vendor's name in
the engine's own name for a credential it mints (GitLab is `gitlab`,
Mattermost `mattermost`, Datadog `datadog`, Atlassian `atlassian`).

_Validation:_
- Enum: [GitLab Mattermost Datadog Atlassian]

_Appears in:_
- [ProvisionedCredential](#provisionedcredential)

| Field | Description |
| --- | --- |
| `GitLab` |  |
| `Mattermost` |  |
| `Datadog` |  |
| `Atlassian` |  |


#### ReplacedRevision

_Underlying type:_ _string_

ReplacedRevision is what a write of the company document replaced where
that was more than the operator's own document.

_Validation:_
- Enum: [Unsealed Drifted]

_Appears in:_
- [UnconfirmedRevision](#unconfirmedrevision)

| Field | Description |
| --- | --- |
| `Unsealed` | ReplacedUnsealed is a revision the engine stores without a seal, which<br />nobody can read and a whole document replaces.<br /> |
| `Drifted` | ReplacedDrifted is a revision the operator did not write whose<br />document differed from the rendered one.<br /> |


#### RetentionSettings



RetentionSettings is who answers for a class's companies' backups.



_Appears in:_
- [EngineClassSpec](#engineclassspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `backupOwner` _string_ | backupOwner names whoever is responsible for backing up the companies'<br />data volumes; the engine warns while none is named. Crewlet's<br />retention.backup_owner. |  | MaxLength: 256 <br />MinLength: 1 <br />Required: \{\} <br /> |


#### RevisionPlacement



RevisionPlacement is where a revision of the company document pins its
agent seats: the values of the two placement labels its roles name. Only
values that can name one of the company's pods are recorded: a pool name
and a seat handle.

_Validation:_
- MinProperties: 1

_Appears in:_
- [ConfigStatus](#configstatus)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `pools` _string array_ | pools are the values of the crewlet.ai/pool placement label: data,<br />and each Shared pool a seat is pinned to. |  | MaxItems: 64 <br />items:MaxLength: 20 <br />items:MinLength: 1 <br />items:Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$` <br />Optional: \{\} <br /> |
| `seats` _string array_ | seats are the values of the crewlet.ai/seat placement label: the<br />handle of each seat pinned to its own pods in a PerSeat pool. A<br />revision that pins more seats than the list holds records the first<br />in handle order; the pods of the others are kept only while their<br />seats stay in a PerSeat pool. |  | MaxItems: 1024 <br />items:MaxLength: 63 <br />items:MinLength: 1 <br />items:Pattern: `^[a-z0-9][a-z0-9-]*$` <br />Optional: \{\} <br /> |


#### S3ObjectSettings



S3ObjectSettings is the S3-compatible bucket a class's companies keep their
files in. Each field maps onto the same-named field of Crewlet's
store.objects.s3.

The bucket's credentials are each Company's own (its
spec.objects.credentialsSecretRef), not the class's: whatever reaches a
company's engine pod is readable by code the tenant runs there (a stdio
MCP server, a coding CLI), so a key the class shared would let every
tenant read and write every other tenant's files.

Crewlet reaches the bucket when it starts (a HeadBucket request, on the data
pods and the seat pods alike), and refuses to start when it cannot. Some
settings fail that request before it is sent, through the S3 client Crewlet
is built with (the AWS SDK for Go), however the bucket is set up, so the API
refuses them where they are written rather than every pod crash-looping on
them: each rule below names one.



_Appears in:_
- [ObjectSettings](#objectsettings)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `endpoint` _string_ | endpoint is the S3 API's base URL. Unset is Amazon S3's own endpoint<br />for the region. Crewlet's S3 client refuses at start an endpoint with a<br />query, one whose host is not a name, an IPv4 address or an IPv6<br />address in brackets (with no percent-encoding in its zone) followed by<br />at most one port, and no connection is made on a port outside 1 to<br />65535, so the API refuses each. |  | MaxLength: 2048 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `region` _string_ | region is the bucket's region. Every request is signed for one, even<br />where the provider ignores it (Cloudflare R2: auto, MinIO: us-east-1).<br />Crewlet's S3 client puts it into a host name, and refuses at start a<br />region that is not one: letters, digits and '-' in labels of at most 63<br />joined by '.', none starting or ending with '-'. Crewlet trims the white<br />space around it first, and refuses one of white space alone. |  | MaxLength: 64 <br />MinLength: 1 <br />Required: \{\} <br /> |
| `bucket` _string_ | bucket is the bucket's name: a general purpose bucket's. Crewlet's S3<br />client reads a name that begins with arn: as an access point's ARN, and<br />one that ends with --x-s3, --xa-s3 or --op-s3 as an S3 Express One Zone<br />directory bucket or an Outposts access point alias, each of which it<br />addresses in a way of its own and refuses at start where it cannot, so<br />the API refuses those names. Crewlet trims the white space around it,<br />and refuses one of white space alone. |  | MaxLength: 63 <br />MinLength: 3 <br />Required: \{\} <br /> |
| `prefix` _string_ | prefix is Crewlet's store.objects.s3.prefix, prepended to every key as<br />it is, so that one bucket holds many companies. It is a template:<br />\{\{namespace\}\}, \{\{name\}\} and \{\{uid\}\} are replaced by the Company's<br />namespace, name and UID, and the result must differ between<br />companies, so it must contain \{\{uid\}\}, or \{\{namespace\}\} and \{\{name\}\}<br />joined by a '/' or '.', which neither can hold (with a '-' between<br />them, team-a/b-web and team-a-b/web would share keys); and it ends<br />with '/', so that no company's prefix starts another's. The default<br />keys files by namespace and name, which is also what the data volumes<br />are named by: a Company re-created under its old name after a Retain<br />deletion finds both its estate and its files again. | \{\{namespace\}\}/\{\{name\}\}/ | MaxLength: 256 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `pathStyle` _boolean_ | pathStyle addresses the bucket in the URL path rather than in the host<br />name; MinIO and most self-hosted gateways need it. |  | Optional: \{\} <br /> |


#### SandboxFile



SandboxFile is a file written into a seat's executor box before its
commands run. Its content is a credential position in Crewlet (it typically
holds a git or registry login), so it always comes from a Secret.



_Appears in:_
- [SandboxSetupStep](#sandboxsetupstep)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `path` _string_ | path is where the file is written in a seat's executor box, whose<br />rule turns on the box's cell. A relative path, such as .npmrc, and one<br />starting ~/ are joined onto the box's home in either cell, and that is<br />the shape that works in both.<br />A Direct box is a directory Crewlet mints for each run on the engine<br />pod, and writes a setup file only inside its own home: an absolute<br />path, one that climbs out with .., and one naming the home itself are<br />refused, since no document can name a home minted per box.<br />An E2B box's own agent writes the file as the account every template<br />runs as, under its home, /home/user, and creates any directory it<br />needs: a relative path is cleaned, so one that climbs with .. (../x)<br />lands outside the home, and an absolute path is written where it<br />names, which works only where that account may write (not under /root,<br />for one). It refuses a path that names a directory rather than a<br />file: the home and every directory above it (such as ~, . or /home)<br />in every template, and a directory only the template made, such as<br />/tmp, at setup, where nothing can tell beforehand.<br />Either box refuses a path starting ~ and a name, such as ~root/.npmrc,<br />since neither expands another account's home. Crewlet refuses a<br />company document that gives a seat's box a path its cell refuses, in<br />every cell a seat's executor can launch in, and a path of white space<br />alone on every step. Crewlet's `files` key.<br />The API refuses white space alone and another account's home itself.<br />The rest turns on the cell and on how .. and repeated separators<br />resolve, so it is left to Crewlet, whose refusal is reported on the<br />Company as ConfigApplied=False Invalid for a step of the Company's own,<br />and on the Seat as Applied=False Invalid for a step of a Seat's.<br />Either way the document is held and the running revision stays. |  | MaxLength: 1024 <br />MinLength: 1 <br />Required: \{\} <br /> |
| `valueFrom` _[SecretValueSource](#secretvaluesource)_ | valueFrom is the Secret key holding the file's content. |  | Required: \{\} <br /> |


#### SandboxPlacement

_Underlying type:_ _string_

SandboxPlacement is where a seat's executor run happens: the cell of the
box its coding CLI's own run is placed in. It maps onto Crewlet's run_in and
default_run_in (Direct is `direct`, E2B is `e2b`). Crewlet's `container`
cell is not offered: it starts a container per box, and an engine pod has
no container runtime.

_Validation:_
- Enum: [Direct E2B]

_Appears in:_
- [LLMProviderSpec](#llmproviderspec)
- [SandboxSettings](#sandboxsettings)

| Field | Description |
| --- | --- |
| `Direct` | SandboxPlacementDirect runs the CLI as a process tree of the engine<br />pod that holds the seat, a data pod or a seat pod, in a box of its own<br />on the pod's sandboxes volume, with its HOME, XDG and temporary<br />directories inside the box and an allowlisted environment. That<br />isolates the run's state, as Crewlet puts it, but not the host: the<br />CLI runs as the engine's user, with the pod's network, CPU and memory,<br />and reads what the engine reads, the keyring in its crewlet.yaml and<br />the store among it, and on a data pod the data volume. A box is seeded<br />with its provider's login, a credential bundle's included, and calls<br />the seat's tools back on the pod's own listener, on loopback, a data<br />pod's or a seat pod's, with or without a public address. A run dies<br />with its pod: a restart or a rolling update ends the runs in flight<br />on it, and Crewlet carries each run's round on in a fresh run, at<br />most twice a round.<br /> |
| `E2B` | SandboxPlacementE2B runs the CLI in the Company's E2B sandbox, a<br />machine of its own per run, which calls the seat's tools back at the<br />Company's public address and is given only the variables that sign<br />its CLI in.<br /> |


#### SandboxSettings



SandboxSettings is where a company's agent seats' executors run. It maps
onto Crewlet's providers.sandbox.

Every agent seat's executor is its coding CLI's own run in a box, placed
by the provider it launches on (its runIn) or by defaultRunIn. Crewlet
refuses a company with an agent seat and a model provider that configures
none, which the operator reports on the Company (SandboxRequired). Direct
needs nothing more: it runs on the engine pods, which keep its boxes on
their sandboxes volume. E2B needs e2b. Crewlet's `container` cell is not
offered, as an engine pod has no container runtime.



_Appears in:_
- [CompanySpec](#companyspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `defaultRunIn` _[SandboxPlacement](#sandboxplacement)_ | defaultRunIn is where a seat's executor run happens when the provider<br />it launches on names no runIn: Direct, on the engine pod that holds<br />the seat, or E2B, in the Company's E2B sandbox. Crewlet's<br />`default_run_in`. |  | Enum: [Direct E2B] <br />Required: \{\} <br /> |
| `e2b` _[E2BSandbox](#e2bsandbox)_ | e2b is the remote sandbox service, required where a run is placed in<br />E2B: by defaultRunIn, or by the runIn of a provider a seat's executor<br />can launch on (SandboxPlacementNotOffered otherwise). |  | Optional: \{\} <br /> |
| `defaultTimeoutSeconds` _integer_ | defaultTimeoutSeconds is how long a box outlives an engine that<br />stopped renewing it, in either cell. It never stops a running job:<br />the engine renews a box while its run works. An engine pod gone for<br />this long has the Direct runs it launched, which were its processes<br />and died with it, found lost (launch_node_gone), and the pod that holds<br />each run's seat next carries its round on in a fresh run. Unset takes<br />Crewlet's default of 900.<br />Crewlet's `default_timeout_seconds`. |  | Minimum: 1 <br />Optional: \{\} <br /> |
| `defaultPauseTTLSeconds` _integer_ | defaultPauseTTLSeconds is how long a box waiting on a person's<br />answer stays paused before it is reclaimed. Unset takes Crewlet's<br />default of 1800; 0 never pauses. Crewlet's<br />`default_pause_ttl_seconds`. |  | Minimum: 0 <br />Optional: \{\} <br /> |
| `defaultMaxTurns` _integer_ | defaultMaxTurns caps the agentic rounds of one executor run on seats<br />that name none. It is the only bound on a seat's turn: an executor run<br />is never stopped on a clock. Unset takes Crewlet's default of 96; 0 is<br />uncapped. Crewlet's `default_max_turns`. |  | Minimum: 0 <br />Optional: \{\} <br /> |
| `commitAttribution` _boolean_ | commitAttribution credits Crewlet on every commit an executor run<br />makes as itself: `Co-authored-by: Crewlet <noreply@crewlet.ai>`, and<br />`Crewlet-Run:` naming the run's turn. Git adds it, through a hook<br />the run's box is given, and a person's commit the run amends,<br />cherry-picks or rebases keeps no credit. Unset takes Crewlet's<br />default, on; false credits nothing. Crewlet's `commit_attribution`. |  | Optional: \{\} <br /> |
| `setup` _[SandboxSetupStep](#sandboxsetupstep) array_ | setup is applied to every executor box before each seat's own steps.<br />Crewlet's `setup`. |  | MaxItems: 16 <br />Optional: \{\} <br /> |


#### SandboxSetupStep



SandboxSetupStep is one provisioning step applied to a seat's executor box
before its coding CLI starts. It maps onto a Crewlet sandbox setup step,
which Crewlet refuses when it does nothing (no files, commands, env or
brief): that is almost always an unfinished edit, which would otherwise
apply cleanly for ever and look like it was working.



_Appears in:_
- [SandboxSettings](#sandboxsettings)
- [SeatSandbox](#seatsandbox)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `name` _string_ | name identifies the step in logs and failure messages, so Crewlet<br />refuses one of white space alone, and so does the API. |  | MaxLength: 63 <br />MinLength: 1 <br />Required: \{\} <br /> |
| `files` _[SandboxFile](#sandboxfile) array_ | files are written into the box before the commands run. Crewlet's<br />`files`, a credential position. |  | MaxItems: 16 <br />Optional: \{\} <br /> |
| `commands` _string array_ | commands are shell commands run in order; one that exits non-zero<br />fails the box. Crewlet's `commands`. Crewlet resolves nothing in a<br />command: the box's shell expands $NAME and $\{NAME\} from the box's own<br />environment (its HOME and PATH among it) and the run's, never from the<br />engine's. The run's is the steps' env, the Seat's sandbox env, and<br />what Crewlet adds: the agent's handle and, when it has one, its email,<br />and the variables that sign the executor's CLI in to the provider it<br />runs on (docs/guides/credentials.md says which, and when the seat's<br />own env leaves them out). The API refuses $\{NAME\} (NAME an identifier)<br />all the same, as the operator refuses every $\{NAME\} it did not write<br />in a string it renders: write a box variable as $NAME. Parameter<br />expansions such as $\{1:-x\} are allowed. |  | MaxItems: 32 <br />items:MaxLength: 4096 <br />items:MinLength: 1 <br />Optional: \{\} <br /> |
| `env` _[SecretEnvVar](#secretenvvar) array_ | env is merged into the environment of the commands and of the run.<br />Crewlet's `env`, a credential position. |  | MaxItems: 32 <br />Optional: \{\} <br /> |
| `optionalKeys` _string array_ | optionalKeys names variables of env, and paths of files, whose value<br />may go missing. A seat's executor run starts without a value that does<br />not resolve, a Secret that does not exist, holds no such key or holds<br />an empty value, whether or not it is listed here: the run is the<br />seat's turn itself, and refusing it would fail every message the seat<br />could answer meanwhile. Unlisted, the engine logs each such value as a<br />gap of the run (sandbox_env_unresolved), and the operator reports an<br />empty one on the object that gives it; listed, the variable is left<br />out of the run and the file is not written, quietly, as an absence<br />that is expected. A missing Secret or key under one is then no failure<br />of the object's references and holds nothing back. Under the Enforce<br />policy the operator also takes the value it pushed for it out of the<br />engine's secret store, and has the engine read the store again whether<br />or not the document can be applied, so no run starts with a deleted<br />Secret's value, but in a revision the engine runs that reads the key as<br />required (one from before the key was listed) or whose reading the<br />operator does not know (another document somebody else activated),<br />which keeps the value until the next document runs, and that one is<br />activated once with it and at once again without it; a Secret key that<br />is also read where it is required holds the document while it is<br />missing, and keeps the value it had in a revision the engine runs that<br />requires it too until the document applies. A later step's variable of<br />the same name wins over this one's, and the Seat's spec.sandbox.env<br />over every step's, and the list beside the value that wins is the one<br />that counts for it; a file is the step's own. Crewlet's<br />`optional_keys`. |  | MaxItems: 48 <br />items:MaxLength: 1024 <br />items:MinLength: 1 <br />Optional: \{\} <br /> |
| `brief` _string_ | brief tells the executor's CLI what this step made true about its<br />box. |  | MaxLength: 2048 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `timeoutSeconds` _integer_ | timeoutSeconds caps each command of the step. |  | Minimum: 1 <br />Optional: \{\} <br /> |


#### Schedule



Schedule is recurring work a seat or a unit owns, fired on a cron schedule:
the CronJob of a company.

The Schedule's metadata.name is the schedule's name in the engine, which
is half of the identity the engine claims each fire under, so that a fire
runs once however often the engine evaluates its minute. Two Schedules of
one seat or unit therefore never share a name, and a fire is never run
twice.

A fire that comes due while its seat is paused is skipped, not queued.





| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `apiVersion` _string_ | `crewlet.ai/v1alpha1` | | |
| `kind` _string_ | `Schedule` | | |
| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.37/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. |  | Optional: \{\} <br /> |
| `spec` _[ScheduleSpec](#schedulespec)_ | spec is the schedule's desired state. |  | Required: \{\} <br /> |
| `status` _[ScheduleStatus](#schedulestatus)_ | status is the schedule's observed state. |  | MinProperties: 1 <br />Optional: \{\} <br /> |


#### ScheduleFanOut

_Underlying type:_ _string_

ScheduleFanOut is who runs a schedule that targets a unit. It maps onto
Crewlet's schedule `target` (Each is `each`, Lead is `lead`).

_Validation:_
- Enum: [Each Lead]

_Appears in:_
- [ScheduleTarget](#scheduletarget)

| Field | Description |
| --- | --- |
| `Each` | ScheduleFanOutEach runs one task per agent seat directly in the unit:<br />never the seats of the units below it, and never a Human seat. Each<br />seat runs its own turn, so a slow one never holds up the others.<br /> |
| `Lead` | ScheduleFanOutLead runs one task as the unit's lead: its leadRef, or,<br />unset, the lead it inherits from the units above it. It follows a<br />change of lead without a change to the Schedule.<br /> |


#### ScheduleSpec



ScheduleSpec is recurring work a seat or a unit owns: a task the engine
hands its runner on a cron schedule, as a CronJob runs a Job. It renders to
one entry of a Crewlet role's or unit's `schedules`, whose `name` is the
Schedule's metadata.name.



_Appears in:_
- [Schedule](#schedule)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `companyRef` _[CompanyReference](#companyreference)_ | companyRef names the Company this schedule belongs to. Immutable. |  | Required: \{\} <br /> |
| `target` _[ScheduleTarget](#scheduletarget)_ | target is the seat or the unit whose schedule this is. |  | MinProperties: 1 <br />Required: \{\} <br /> |
| `schedule` _string_ | schedule is when the task fires: a standard cron expression of five<br />fields (minute, hour, day of month, month, day of week), such as<br />"30 9 * * 1-5", evaluated in timeZone. When both the day of month and<br />the day of week are restricted, a day matches if either does. The<br />engine's dry run checks each field's values. Crewlet's `cron`. |  | MaxLength: 256 <br />MinLength: 9 <br />Required: \{\} <br /> |
| `timeZone` _string_ | timeZone is the IANA time zone the schedule is evaluated in, such as<br />Asia/Tokyo. Unset is the Company's spec.timeZone, which is UTC when<br />that is unset too. The engine refuses a zone it cannot load, and<br />Local, which would be whatever zone the engine's host is set to.<br />Crewlet's `timezone`. |  | MaxLength: 64 <br />MinLength: 1 <br />Pattern: `^[A-Za-z][A-Za-z0-9_+-]*(/[A-Za-z0-9_+-]+)*$` <br />Optional: \{\} <br /> |
| `prompt` _string_ | prompt is the task the runner is handed each time the schedule fires,<br />such as "Post your standup: what shipped yesterday, what is next,<br />what blocks you." Crewlet's `task`. |  | MaxLength: 8192 <br />MinLength: 1 <br />Required: \{\} <br /> |
| `suspend` _boolean_ | suspend keeps the schedule in the company without firing it. Unset<br />is false. Crewlet's `enabled`, inverted. |  | Optional: \{\} <br /> |
| `timeoutSeconds` _integer_ | timeoutSeconds caps one scheduled turn's wall-clock time, the seat's<br />executor run included: a run still working when it passes is ended,<br />and the turn starts no further round and ends failed. Unset is the<br />engine's default, 1800 seconds, which leaves a slow ritual room for its<br />box's start, its setup, its run and a review sent back once. A<br />schedule that fires more often than its turns take queues its fires<br />behind the turn, never merging them, so give one that fires every few<br />minutes a timeoutSeconds below its period. Crewlet's<br />`timeout_seconds`. |  | Minimum: 1 <br />Optional: \{\} <br /> |
| `catchUp` _boolean_ | catchUp says whether an engine that starts after missing a fire runs<br />the most recent missed one, when it is recent enough (half the<br />schedule's period, within the engine's catch-up bounds); older misses<br />are never run. Unset is true. Crewlet's `catchup`. |  | Optional: \{\} <br /> |


#### ScheduleStatus



ScheduleStatus is what the operator observed about a Schedule.

_Validation:_
- MinProperties: 1

_Appears in:_
- [Schedule](#schedule)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.37/#condition-v1-meta) array_ | conditions are Accepted (the Company exists), ResolvedRefs (the seat<br />or unit it targets exists, and a seat is an Agent) and Applied (the<br />schedule is in the revision the engine runs). |  | MaxItems: 8 <br />Optional: \{\} <br /> |
| `observedGeneration` _integer_ | observedGeneration is the metadata.generation this status describes. |  | Minimum: 1 <br />Optional: \{\} <br /> |


#### ScheduleTarget



ScheduleTarget is whose recurring work a schedule is: one seat's, or a
unit's. It decides which entry of the company document the schedule is
rendered into: the seat's role, or the unit's.

_Validation:_
- MinProperties: 1

_Appears in:_
- [ScheduleSpec](#schedulespec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `seatRef` _[LocalObjectReference](#localobjectreference)_ | seatRef names the Seat, in this namespace, whose schedule this is; it<br />always runs as that seat. The Seat must be an Agent: the engine runs<br />no turn for a person. Rendered into the seat's role `schedules`. |  | Optional: \{\} <br /> |
| `unitRef` _[LocalObjectReference](#localobjectreference)_ | unitRef names the Unit, in this namespace, whose schedule this is;<br />fanOut says who in it runs it. A unit's schedule is not inherited by<br />the units below it. Rendered into the unit's `schedules`. |  | Optional: \{\} <br /> |
| `fanOut` _[ScheduleFanOut](#schedulefanout)_ | fanOut is who in the unit runs it. Unset is Each. Crewlet's `target`.<br />The engine refuses a schedule that could never run while it is not<br />suspended: Each on a unit with no agent seat directly in it, and Lead<br />on a unit whose lead is a Human seat. |  | Enum: [Each Lead] <br />Optional: \{\} <br /> |


#### Seat



Seat is one seat of a company's org chart: an AI agent the engine runs, or a
person agents work with.

spec.paused pauses an agent seat while keeping it in the chart; Company's
spec.suspend stops the whole engine instead.

Unless spec.handle is set, the Seat's metadata.name is its handle and must
follow the handle's rules: lowercase letters, digits and '-', starting with
a letter or digit, at most 63 characters. The handle cannot change.





| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `apiVersion` _string_ | `crewlet.ai/v1alpha1` | | |
| `kind` _string_ | `Seat` | | |
| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.37/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. |  | Optional: \{\} <br /> |
| `spec` _[SeatSpec](#seatspec)_ | spec is the seat's desired state. |  | Required: \{\} <br /> |
| `status` _[SeatStatus](#seatstatus)_ | status is the seat's observed state. |  | MinProperties: 1 <br />Optional: \{\} <br /> |


#### SeatContact



SeatContact is how agents reach a person: their accounts on the company's
surfaces, which tie what the person does there to their seat. It maps onto
Crewlet's role `contact`, one field for each of its keys but one (below).

Crewlet refuses two seats that claim one account, so a Seat claiming an
account another Seat of the company already claims is reported as a
Conflict. Each field is compared as Crewlet compares it: githubLogin,
gitlabUsername and mattermostUsername without case, as GitHub, GitLab and
Mattermost compare them; slackUserID and atlassianAccount exactly.

_Validation:_
- MinProperties: 1

_Appears in:_
- [SeatSpec](#seatspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `slackUserID` _string_ | slackUserID is the person's Slack member id, such as U0123ABCD.<br />Crewlet's `slack_user_id`. |  | MaxLength: 64 <br />MinLength: 1 <br />Pattern: `^[A-Z0-9]+$` <br />Optional: \{\} <br /> |
| `mattermostUsername` _string_ | mattermostUsername is the person's username on the company's<br />Mattermost, such as jane.doe, written without the @: the name an<br />agent mentions them by and opens a direct message with, and the<br />sender an inbound post is attributed by. Crewlet's<br />`mattermost_user_id`, which holds the username despite its name, and<br />never the 26-character user id. Mattermost's own rule for a username<br />holds it: lowercase letters, digits, '.', '-' and '_', at most 64<br />characters, and none of the names Mattermost reserves (all, channel,<br />matterbot, system) nor here: a mention of all, channel or here<br />notifies the whole channel rather than the person. |  | MaxLength: 64 <br />MinLength: 1 <br />Pattern: `^[a-z0-9._-]+$` <br />Optional: \{\} <br /> |
| `atlassianAccount` _string_ | atlassianAccount is the person's identity on the company's Jira and<br />Confluence, one value for both: their account id on Atlassian Cloud,<br />such as 557058:f58131cb-b67d-43c7-b30d-6b58d40bd077 and never their<br />email address, and their username on a Data Center instance, such as<br />jane.doe. Webhooks name the person by it, so it attributes what they do<br />there to their seat, and agents assign and mention them by it.<br />Crewlet's `atlassian_account_id`, which holds the username on Data<br />Center despite its name. Any value up to 255 characters without<br />whitespace is taken, since a Data Center username may hold almost any<br />character. Where the company reaches Jira or Confluence on Atlassian<br />Cloud, a value outside the form of an account id (letters, digits,<br />'_', '\|', ':' and '-', at most 128 characters) is applied and reported<br />on the Seat as ResolvedRefs=False with the reason NotAnAccountID. |  | MaxLength: 255 <br />MinLength: 1 <br />Pattern: `^\S+$` <br />Optional: \{\} <br /> |
| `githubLogin` _string_ | githubLogin is the person's GitHub login. Crewlet's `github_login`. |  | MaxLength: 39 <br />MinLength: 1 <br />Pattern: `^[A-Za-z0-9-]+$` <br />Optional: \{\} <br /> |
| `gitlabUsername` _string_ | gitlabUsername is the person's GitLab username, written without the<br />@: assignments, review requests, mentions, and the sender an inbound<br />webhook is attributed by. Crewlet's `gitlab_username`. GitLab's own<br />rule for a username's form holds it: letters, digits, '_', '-' and<br />'.', at most 255 characters, not starting with '-' and not ending<br />with '.'. |  | MaxLength: 255 <br />MinLength: 1 <br />Pattern: `^([A-Za-z0-9_.][A-Za-z0-9_.-]*[A-Za-z0-9_-]\|[A-Za-z0-9_])$` <br />Optional: \{\} <br /> |


#### SeatCredentialField

_Underlying type:_ _string_

SeatCredentialField is which of an Atlassian account's two seat credentials
a server reads. It maps onto Crewlet's seat_credentials[].field (Token is
`TOKEN`, Email `EMAIL`).

_Validation:_
- Enum: [Token Email]

_Appears in:_
- [MCPSeatCredential](#mcpseatcredential)

| Field | Description |
| --- | --- |
| `Token` |  |
| `Email` |  |


#### SeatCredentialKind

_Underlying type:_ _string_

SeatCredentialKind is an integration whose per-seat credential a tool
server can read. It maps onto Crewlet's seat_credentials[].kind (Atlassian
is `atlassian`, Datadog `datadog`, GitHub `github`, GitLab `gitlab`,
Mattermost `mattermost`, Slack `slack`).

_Validation:_
- Enum: [Atlassian Datadog GitHub GitLab Mattermost Slack]

_Appears in:_
- [MCPSeatCredential](#mcpseatcredential)

| Field | Description |
| --- | --- |
| `Atlassian` |  |
| `Datadog` |  |
| `GitHub` |  |
| `GitLab` |  |
| `Mattermost` |  |
| `Slack` |  |


#### SeatCredentialSource



SeatCredentialSource says where one of a seat's own credentials comes from:
a Secret key, or the engine, which provisions it (see
ProvisionedCredential).

_Validation:_
- MinProperties: 1

_Appears in:_
- [SeatEnvVar](#seatenvvar)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `secretKeyRef` _[SecretKeyReference](#secretkeyreference)_ | secretKeyRef selects the Secret key that holds the value. |  | Optional: \{\} <br /> |
| `provisioned` _[ProvisionedCredential](#provisionedcredential)_ | provisioned is a credential the engine mints for the seat's account<br />at a vendor, under that vendor's Integration with provisioning Engine. |  | Optional: \{\} <br /> |


#### SeatEnvVar



SeatEnvVar is a named credential of a seat delivered as an environment
variable: from a Secret, or provisioned by the engine.



_Appears in:_
- [SeatSandbox](#seatsandbox)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `name` _string_ | name is the variable's name. |  | MaxLength: 128 <br />MinLength: 1 <br />Pattern: `^[A-Za-z_][A-Za-z0-9_]*$` <br />Required: \{\} <br /> |
| `valueFrom` _[SeatCredentialSource](#seatcredentialsource)_ | valueFrom is where the value comes from. |  | MinProperties: 1 <br />Required: \{\} <br /> |


#### SeatIntegrations



SeatIntegrations is a seat's own identity and access on the company's
integrations, one block per vendor: whether the seat is on it, what it may
do there in the vendor's own terms, and, where the vendor has one, the scope
it may do it in. A vendor without a block is off for the seat. The
credential the engine mints for a seat's account is sealed under a name the
engine gives it for the seat, and the engine hands it to the vendor's tool
server itself, so spec.mcp holds none for these vendors.

_Validation:_
- MinProperties: 1

_Appears in:_
- [SeatSpec](#seatspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `slack` _[SlackSeatIntegration](#slackseatintegration)_ | slack is the seat's own Slack app. |  | Optional: \{\} <br /> |
| `github` _[GitHubSeatIntegration](#githubseatintegration)_ | github is the seat's identity and access on GitHub. |  | Optional: \{\} <br /> |
| `gitlab` _[GitLabSeatIntegration](#gitlabseatintegration)_ | gitlab is the seat's account and access on GitLab. |  | Optional: \{\} <br /> |
| `mattermost` _[MattermostSeatIntegration](#mattermostseatintegration)_ | mattermost is the seat's own Mattermost bot. |  | Optional: \{\} <br /> |
| `jira` _[JiraSeatIntegration](#jiraseatintegration)_ | jira is the seat's access on Jira. |  | Optional: \{\} <br /> |
| `confluence` _[ConfluenceSeatIntegration](#confluenceseatintegration)_ | confluence is the seat's access on Confluence. |  | Optional: \{\} <br /> |
| `datadog` _[DatadogSeatIntegration](#datadogseatintegration)_ | datadog is the seat's service account on Datadog. |  | Optional: \{\} <br /> |


#### SeatIntegrationsStatus



SeatIntegrationsStatus is the addresses a seat's vendor apps must use.

_Validation:_
- MinProperties: 1

_Appears in:_
- [SeatStatus](#seatstatus)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `slack` _[SlackSeatStatus](#slackseatstatus)_ | slack is the Slack side of the seat. |  | MinProperties: 1 <br />Optional: \{\} <br /> |
| `github` _[GitHubSeatStatus](#githubseatstatus)_ | github is the GitHub side of the seat. |  | MinProperties: 1 <br />Optional: \{\} <br /> |


#### SeatKind

_Underlying type:_ _string_

SeatKind is whether a seat is an AI agent or a person. It maps onto
Crewlet's role `kind` (Agent is `agent`, Human is `human`).

_Validation:_
- Enum: [Agent Human]

_Appears in:_
- [SeatSpec](#seatspec)

| Field | Description |
| --- | --- |
| `Agent` | SeatKindAgent is an AI agent: the engine runs it, with its own inbox,<br />models and tools.<br /> |
| `Human` | SeatKindHuman is a person: part of the chart (a lead, an escalation<br />target, a colleague to mention) whom the engine never runs.<br /> |


#### SeatLLM



SeatLLM is the model providers a seat runs on, one fallback chain per phase
of its work: when every key of the first provider is cooling down, the next
is tried. It maps onto Crewlet's per-phase `llm` mapping. A phase left unset
uses the default chain; a seat with no default chain runs on the first
provider of the Company's spec.llm.order alone, with no fallback.

_Validation:_
- MinProperties: 1

_Appears in:_
- [SeatSpec](#seatspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `default` _[LLMProviderReference](#llmproviderreference) array_ | default is the chain of every phase not set below, and of the seat's<br />executor, which does its work. Crewlet runs the executor as the<br />agentic run of the chain's first member that drives ClaudeCode or<br />OpenCode and is not sitting out its spent plan on the node, in that<br />member's cell (its runIn, else the Company's spec.sandbox.defaultRunIn),<br />and a launch falls back along the chain to the next such member. A<br />member of any other CLI never runs the executor and still serves every<br />phase below that is unset. Crewlet refuses a chain with no ClaudeCode<br />or OpenCode member, which the operator refuses as NoExecutorCLI, and<br />applies one that mixes them with an advisory that its executor never<br />falls back to the others. Crewlet's `default`. |  | MaxItems: 8 <br />MinItems: 1 <br />Optional: \{\} <br /> |
| `review` _[LLMProviderReference](#llmproviderreference) array_ | review is the chain of the reviewer that judges the executor's work.<br />Crewlet's `review`. |  | MaxItems: 8 <br />MinItems: 1 <br />Optional: \{\} <br /> |
| `subagent` _[LLMProviderReference](#llmproviderreference) array_ | subagent is the chain of the short-lived workers the seat delegates<br />to. Crewlet's `subagent`. |  | MaxItems: 8 <br />MinItems: 1 <br />Optional: \{\} <br /> |
| `auxiliary` _[LLMProviderReference](#llmproviderreference) array_ | auxiliary is the chain of the cheap model used for reflection and<br />summaries. Crewlet's `auxiliary`. |  | MaxItems: 8 <br />MinItems: 1 <br />Optional: \{\} <br /> |
| `judge` _[LLMProviderReference](#llmproviderreference) array_ | judge is the chain of the model that decides whether a turn that ran<br />out of rounds may have more. Crewlet's `judge`. |  | MaxItems: 8 <br />MinItems: 1 <br />Optional: \{\} <br /> |


#### SeatPauseStatus



SeatPauseStatus is a seat's pause, as the engine reports it.

_Validation:_
- MinProperties: 1

_Appears in:_
- [SeatStatus](#seatstatus)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `pausedBy` _string_ | pausedBy is who paused the seat, as Crewlet records the author of a<br />write: the seat of the person who paused it, or token:<id> for a<br />token no seat is bound to. A pause the operator took reads<br />token:operator. |  | MaxLength: 256 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `pausedAt` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.37/#time-v1-meta)_ | pausedAt is when the seat was paused, to the second. |  | Optional: \{\} <br /> |
| `reason` _string_ | reason is why, in the pauser's words. |  | MaxLength: 500 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `stopRunning` _boolean_ | stopRunning is whether the pause also ended the turn the seat was on. |  | Optional: \{\} <br /> |


#### SeatPlacement



SeatPlacement is where a seat runs.



_Appears in:_
- [SeatSpec](#seatspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `pool` _string_ | pool is the pool of pods that runs the seat: data, the company's data<br />pods, or the name of one of the Company's spec.topology.seatPools.<br />The seat is pinned to the pool with Crewlet's role.placement, which<br />the engine never widens: while the pool runs no pod, the seat runs<br />nowhere and its messages wait for one. |  | MaxLength: 20 <br />MinLength: 1 <br />Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$` <br />Required: \{\} <br /> |


#### SeatPlacementStatus



SeatPlacementStatus is where the engine runs a seat.

_Validation:_
- MinProperties: 1

_Appears in:_
- [SeatStatus](#seatstatus)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `pool` _string_ | pool is the pool of pods that runs the seat: spec.placement.pool, or<br />the Company's spec.topology.defaultSeatPool. The seat is rendered with<br />role.placement.labels \{crewlet.ai/pool: <pool>\}, which only the pool's<br />pods carry, or, in a PerSeat pool, \{crewlet.ai/seat: <handle>\}, which<br />only the seat's own pods carry. |  | MaxLength: 20 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `workload` _string_ | workload is the name of the StatefulSet whose pods may run the seat:<br />the data pods', the Shared pool's, or the seat's own in a PerSeat<br />pool. |  | MaxLength: 63 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `node` _string_ | node is the engine node, a pod's name, that holds the seat's lease<br />and runs it, as the engine's GET /fleet last reported. Unset while no<br />node holds it. |  | MaxLength: 64 <br />MinLength: 1 <br />Optional: \{\} <br /> |


#### SeatPool



SeatPool is a set of stateless pods that run seats: they hold no data, join
the company's event stream through the data pods, and keep a scratch store
they delete at every start. A seat runs in it when its Seat's
spec.placement.pool names it, or when it is the Company's defaultSeatPool
and the Seat names no pool. The class's spec.seatPools.policy must be
Allowed.

The operator runs a Shared pool as the StatefulSet
<company>-seats-<name>-<hash>, and each seat of a PerSeat pool as
<company>-seat-<handle>-<hash> (the hash keeps the name the Company's own
in a namespace another Company shares), started only
once the data pods are ready and rolled only after them. The pods serve
their probes alone, on the engine's port: a pod is ready once its engine
has joined the company's fleet and may claim seats, and a rollout replaces
the next pod only then.



_Appears in:_
- [CompanyTopology](#companytopology)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `name` _string_ | name identifies the pool: a DNS label of at most 20 characters, other<br />than data, which is the data pods' pool. It names the pool's pods and<br />is the value of the crewlet.ai/pool label a Shared pool's seats are<br />pinned to. |  | MaxLength: 20 <br />MinLength: 1 <br />Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$` <br />Required: \{\} <br /> |
| `mode` _[SeatPoolMode](#seatpoolmode)_ | mode is how the pool runs its seats. | Shared | Enum: [Shared PerSeat] <br />Optional: \{\} <br /> |
| `replicas` _integer_ | replicas is, for a Shared pool, how many pods it runs, 0 to 100: at 0<br />its seats run nowhere, and their messages wait for a pod. For a<br />PerSeat pool it is how many pods it runs for each of its seats, 1 or<br />2. | 1 | Maximum: 100 <br />Minimum: 0 <br />Optional: \{\} <br /> |
| `maxConcurrentTurns` _integer_ | maxConcurrentTurns is how many turn segments one of the pool's pods<br />runs at once in the engine (a seat's onboarding pass, the launch of its<br />executor, the collection of its run and the review): Crewlet's<br />node.max_concurrent. An executor run is not one: its turn gives the<br />place back while the run works, and a seat runs one at a time, so the<br />seats a pod holds bound the Direct runs it has running, beside those<br />parked on a person's question, whose processes are stopped. Unset<br />takes the class's seatPools.defaults. |  | Minimum: 1 <br />Optional: \{\} <br /> |
| `terminationGracePeriodSeconds` _integer_ | terminationGracePeriodSeconds is how long one of the pool's pods may<br />take to stop, finishing the turn segments the engine runs in its own<br />process (a seat's launch, the collection of its run, the review, a<br />delegated worker): the engine puts no bound of its own on that drain,<br />so it must cover the longest of them. A seat's executor run is not<br />waited for: a Direct one on the pod ends with it, and its box with the<br />pod's sandboxes volume, and Crewlet carries its round on in a fresh<br />run, once a pod of the same name is back or once the pod has been gone<br />for spec.sandbox.defaultTimeoutSeconds (launch_node_gone); an E2B one<br />carries on in its sandbox. Unset takes the class's seatPools.defaults,<br />else 300. |  | Maximum: 3600 <br />Minimum: 30 <br />Optional: \{\} <br /> |


#### SeatPoolDefaults



SeatPoolDefaults sizes the pods of a seat pool that does not size its own,
and the compute of every seat pod, which the class alone sets: a
Company's pools choose how many pods they run, within maxPods, and the
class what each of them may take, as it does for the data pods.

_Validation:_
- MinProperties: 1

_Appears in:_
- [SeatPoolSettings](#seatpoolsettings)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `maxConcurrentTurns` _integer_ | maxConcurrentTurns is how many turn segments one seat pod runs at once<br />in the engine (a seat's onboarding pass, the launch of its executor,<br />the collection of its run and the review): Crewlet's<br />node.max_concurrent. Unset takes the engine's default, 32. A seat runs<br />one turn at a time, so a pod never runs more at once than it holds<br />seats; and an executor run is not a segment, as its turn gives the<br />place back while the run works, so the seats a pod holds bound the<br />Direct runs it has running too, beside those parked on a person's<br />question, whose processes are stopped. |  | Minimum: 1 <br />Optional: \{\} <br /> |
| `resources` _[ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.37/#resourcerequirements-v1-core)_ | resources are the compute resources of every seat pod's engine<br />container, sized as data.resources says of a data pod's: the engine,<br />its providers' CLI processes, a Direct executor run for each agent<br />seat the pod holds that runs Direct, and the stopped processes of each<br />Direct run parked on a person's question. Unset sets none. |  | Optional: \{\} <br /> |
| `terminationGracePeriodSeconds` _integer_ | terminationGracePeriodSeconds is how long a seat pod may take to stop.<br />A seat pod finishes the turn segments it runs in its own process<br />before it exits, with no bound of its own, so unset is five minutes,<br />as for a data pod, rather than the Kubernetes default of thirty<br />seconds. A seat's executor run is not waited for: a Direct one on the<br />pod ends with it, its box with the pod's sandboxes volume, and Crewlet<br />carries its round on in a fresh run, and an E2B one carries on in its<br />sandbox. |  | Maximum: 3600 <br />Minimum: 30 <br />Optional: \{\} <br /> |
| `scratchSizeLimit` _[Quantity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.37/#quantity-resource-api)_ | scratchSizeLimit caps the emptyDir a seat pod keeps its scratch store<br />in, and its /tmp and HOME: a store the engine deletes at every start,<br />its native library (about 20 MB, extracted at every start), and what<br />the processes it runs write outside a box, as data.scratchSizeLimit<br />says of a data pod, the stdio tool servers' packages and files and<br />what a seat's Direct executor run writes to /tmp or the engine's home<br />outright among them. A pod that writes more is evicted, with every<br />run and turn on it. Unset is 10Gi. |  | Optional: \{\} <br /> |
| `sandboxSizeLimit` _[Quantity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.37/#quantity-resource-api)_ | sandboxSizeLimit caps the emptyDir every seat pod keeps its sandboxes<br />in, at /var/lib/crewlet-sandboxes, apart from its scratch volume: the<br />boxes Crewlet makes on the pod itself for the executor runs it places<br />there, as data.sandboxSizeLimit says of a data pod: one for each seat<br />the pod holds whose run is running, and one for each run parked on a<br />person's question. A pod whose boxes write more is evicted, with<br />every run and turn on it. Unset is 20Gi. It bounds the boxes alone:<br />what a run writes outside its box counts against scratchSizeLimit. |  | Optional: \{\} <br /> |


#### SeatPoolMode

_Underlying type:_ _string_

SeatPoolMode is how a seat pool runs the seats placed in it.

_Validation:_
- Enum: [Shared PerSeat]

_Appears in:_
- [SeatPool](#seatpool)
- [SeatPoolStatus](#seatpoolstatus)

| Field | Description |
| --- | --- |
| `Shared` | SeatPoolShared runs replicas pods that share the pool's seats between<br />them: each takes an even share, and a pod that stops hands its seats<br />to the others.<br /> |
| `PerSeat` | SeatPoolPerSeat runs replicas pods for each seat placed in the pool,<br />each holding that seat alone. It needs the class's<br />seatPools.allowPerSeat.<br /> |


#### SeatPoolPolicy

_Underlying type:_ _string_

SeatPoolPolicy is whether a class's companies may run seats on pods of
their own, outside the data pods.

_Validation:_
- Enum: [Forbidden Allowed]

_Appears in:_
- [SeatPoolSettings](#seatpoolsettings)

| Field | Description |
| --- | --- |
| `Forbidden` | SeatPoolsForbidden runs every seat on the data pods. A Company of the<br />class may declare no spec.topology.seatPools.<br /> |
| `Allowed` | SeatPoolsAllowed lets a Company declare seat pools, and opens the<br />leaf listener its seat pods join the company's event stream through<br />on every data pod of the class, from the data pod's first start, so<br />that a company adding its first pool restarts nothing.<br /> |


#### SeatPoolSettings



SeatPoolSettings is whether, and how far, a class's companies may run seats
on stateless pods of their own (a Company's spec.topology.seatPools). A seat
pod holds no data: it joins the company's event stream as a NATS leaf of the
data pods, keeps a scratch store it deletes at every start, and runs the
seats placed in its pool.

_Validation:_
- MinProperties: 1

_Appears in:_
- [EngineClassSpec](#engineclassspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `policy` _[SeatPoolPolicy](#seatpoolpolicy)_ | policy is whether the class's companies may declare seat pools.<br />Changing it restarts every data pod of the class, which opens or<br />closes the leaf listener. | Forbidden | Enum: [Forbidden Allowed] <br />Optional: \{\} <br /> |
| `allowPerSeat` _boolean_ | allowPerSeat lets a Company declare a PerSeat pool, which runs one<br />pod (or two, a warm standby) for each seat placed in it. Each costs a<br />pod, and every pod's work grows with the number of seats of the<br />company, so it is off by default and meant for the few seats that<br />need a pod to themselves. It isolates a seat's compute and its<br />failures, not its credentials: every pod of a company can read the<br />company's whole secret store. |  | Optional: \{\} <br /> |
| `maxPods` _integer_ | maxPods is the most seat pods a Company of the class may run, all of<br />its pools together: each Shared pool's replicas, and each PerSeat<br />pool's replicas for every seat placed in it. The data pods are not<br />counted. Required with policy Allowed: a class's companies size their<br />own pools, and only this bounds how many seat pods a company of the<br />class runs. |  | Minimum: 1 <br />Optional: \{\} <br /> |
| `defaults` _[SeatPoolDefaults](#seatpooldefaults)_ | defaults size the pods of a pool that does not size its own. |  | MinProperties: 1 <br />Optional: \{\} <br /> |


#### SeatPoolStatus



SeatPoolStatus is the state of one seat pool's pods.



_Appears in:_
- [TopologyStatus](#topologystatus)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `name` _string_ | name is the pool's name. |  | MaxLength: 20 <br />MinLength: 1 <br />Required: \{\} <br /> |
| `mode` _[SeatPoolMode](#seatpoolmode)_ | mode is how the pool runs its seats. |  | Enum: [Shared PerSeat] <br />Optional: \{\} <br /> |
| `replicas` _integer_ | replicas is the number of the pool's pods, every seat's together for<br />a PerSeat pool. |  | Minimum: 0 <br />Optional: \{\} <br /> |
| `readyReplicas` _integer_ | readyReplicas is the number of the pool's pods that are ready. |  | Minimum: 0 <br />Optional: \{\} <br /> |
| `updatedReplicas` _integer_ | updatedReplicas is the number of the pool's pods that run the<br />current pod template. |  | Minimum: 0 <br />Optional: \{\} <br /> |
| `seats` _integer_ | seats is the number of agent seats placed in the pool. |  | Minimum: 0 <br />Optional: \{\} <br /> |


#### SeatSandbox



SeatSandbox is what a seat's executor box reads beyond the Company's
spec.sandbox: its own provisioning and environment, the tool servers it is
given, and the bounds of one run. It maps onto Crewlet's role `sandbox`.
Nothing here places the box or picks its CLI: every agent seat's executor
is its coding CLI's own run, placed by the provider it launches on, so a
seat with no spec.sandbox runs on the Company's settings alone. An empty
one says nothing, and the API refuses it.

_Validation:_
- MinProperties: 1

_Appears in:_
- [SeatSpec](#seatspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `pauseTTLSeconds` _integer_ | pauseTTLSeconds is how long the seat's box stays paused while its run<br />waits on a person. Unset takes the Company's default; 0 never pauses.<br />Crewlet's `pause_ttl_seconds`. |  | Minimum: 0 <br />Optional: \{\} <br /> |
| `maxTurns` _integer_ | maxTurns caps the agentic rounds of one of the seat's executor runs,<br />the only bound on its turn. Unset takes the Company's<br />spec.sandbox.defaultMaxTurns, else Crewlet's default of 96; 0 is<br />uncapped. Crewlet's `max_turns`. |  | Minimum: 0 <br />Optional: \{\} <br /> |
| `mcpServerRefs` _[LocalObjectReference](#localobjectreference) array_ | mcpServerRefs name the MCPServers the seat's executor box is given,<br />beside its tool bridge, which every executor box is given. Crewlet's<br />mcp.servers. |  | MaxItems: 16 <br />Optional: \{\} <br /> |
| `env` _[SeatEnvVar](#seatenvvar) array_ | env is the environment of the seat's executor runs, for the external<br />tokens its work needs: from Secrets, or provisioned by the engine,<br />such as the GitLab token a provisioning Integration mints for the<br />seat's account, which the engine gives its gitlab tool server too, so<br />both are one token. A run gets<br />its provider's whole env beneath this, so a variable named here wins<br />over the provider's of that name. A ClaudeCode sign-in here<br />(CLAUDE_CODE_OAUTH_TOKEN, ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN or a<br />CLAUDE_CODE_USE_* toggle) keeps the provider's own sign-in out of the<br />box, its token or key and every sign-in in its env, a gateway's<br />bearer token or a cloud switch, while the rest of its env, such as a<br />gateway's address, still reaches the run: a seat meant to bypass the<br />gateway names ANTHROPIC_BASE_URL here itself. A run that goes without<br />the value is given the provider's sign-in as one with no sign-in here<br />is. Crewlet's `env`, a credential position. |  | MaxItems: 32 <br />Optional: \{\} <br /> |
| `optionalKeys` _string array_ | optionalKeys names variables of env whose value may go missing. An<br />executor run starts without a value that does not resolve, a Secret<br />that does not exist, holds no such key or holds an empty value, or a<br />provisioned value nothing has minted yet, whether or not it is listed<br />here: the run is the seat's turn itself, and refusing it would fail<br />every message the seat could answer meanwhile. Unlisted, the engine<br />logs each such value as a gap of the run (sandbox_env_unresolved), and<br />the operator reports an empty one on the Seat; listed, the variable is<br />left out quietly, as an absence that is expected, but for a value an<br />Integration mints for the seat, which is logged as awaited whatever<br />this says. A missing Secret or key under a listed variable is then no<br />failure of the Seat's references and holds nothing back. Under the<br />Enforce policy the operator also takes the value it pushed for it out<br />of the engine's secret store, and has the engine read the store again<br />whether or not the document can be applied, so no run starts with a<br />deleted Secret's value, but in a revision the engine runs that reads<br />the key as required (one from before the key was listed) or whose<br />reading the operator does not know (another document somebody else<br />activated), which keeps the value until the next document runs, and<br />that one is activated once with it and at once again without it; a<br />Secret key that is also read where it is required holds the document<br />while it is missing, and keeps the value it had in a revision the<br />engine runs that requires it too until the document applies. env wins<br />over a setup step's variable of the same name, and so does this list<br />over the step's optionalKeys for it. Crewlet's `optional_keys`. |  | MaxItems: 32 <br />items:MaxLength: 128 <br />items:MinLength: 1 <br />items:Pattern: `^[A-Za-z_][A-Za-z0-9_]*$` <br />Optional: \{\} <br /> |
| `setup` _[SandboxSetupStep](#sandboxsetupstep) array_ | setup is the seat's own provisioning of its executor box, applied<br />after the Company's. Crewlet's `setup`. |  | MaxItems: 16 <br />Optional: \{\} <br /> |


#### SeatSpec



SeatSpec is one seat of a company: an AI agent or a person. It renders to
one entry of Crewlet's roles, nested under its unit's.



_Appears in:_
- [Seat](#seat)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `companyRef` _[CompanyReference](#companyreference)_ | companyRef names the Company this seat belongs to. Immutable. |  | Required: \{\} <br /> |
| `handle` _string_ | handle is the seat's canonical slug. Unset is the Seat's<br />metadata.name. Crewlet derives the seat's identity, and with it the<br />seat's memory, from the company name and the handle, so the handle<br />cannot be changed; a Seat deleted and created again with the same<br />handle gets its memory back. Crewlet's `handle`. |  | MaxLength: 63 <br />MinLength: 1 <br />Pattern: `^[a-z0-9][a-z0-9-]*$` <br />Optional: \{\} <br /> |
| `kind` _[SeatKind](#seatkind)_ | kind is whether the seat is an AI agent or a person. Crewlet's `kind`. | Agent | Enum: [Agent Human] <br />Optional: \{\} <br /> |
| `displayName` _string_ | displayName is the seat's name as people read it, such as "Ana<br />(Platform Engineer)". Unset is the handle. Crewlet's `name`. It is for<br />reading only: one seat names another, a unit its lead and a seat what<br />it manages, by the handle, so two Seats may share a displayName. |  | MaxLength: 256 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `email` _string_ | email is the seat's email address. Crewlet's `email`. Each seat has its<br />own: the engine finds a seat by its address, compared lower-cased and<br />with any plus tag dropped, so a Seat whose address another Seat's<br />matches that way is reported as a Conflict. |  | MaxLength: 254 <br />MinLength: 3 <br />Pattern: `^[^@\s]+@[^@\s]+$` <br />Optional: \{\} <br /> |
| `unitRef` _[LocalObjectReference](#localobjectreference)_ | unitRef names the Unit, in this namespace, the seat belongs to. Unset<br />is a seat outside every unit, such as a chief executive. |  | Optional: \{\} <br /> |
| `goal` _string_ | goal is what the seat is for; it reaches the seat's prompt. Crewlet's<br />`goal`. |  | MaxLength: 2048 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `backstory` _string_ | backstory is who the seat is; it reaches the seat's prompt. Crewlet's<br />`backstory`. |  | MaxLength: 8192 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `responsibilities` _string array_ | responsibilities are what the seat owns. Crewlet's<br />`responsibilities`. |  | MaxItems: 32 <br />items:MaxLength: 1024 <br />items:MinLength: 1 <br />Optional: \{\} <br /> |
| `behavioralGuidelines` _string array_ | behavioralGuidelines are how the seat should work. Crewlet's<br />`behavioral_guidelines`. |  | MaxItems: 32 <br />items:MaxLength: 1024 <br />items:MinLength: 1 <br />Optional: \{\} <br /> |
| `manages` _[ManagedReference](#managedreference) array_ | manages names the seats and units this seat manages; a unit stands<br />for every seat in it and below it. Crewlet's `manages`, which names a<br />Seat by its handle and a Unit by its metadata.name, the Unit's key; a<br />key that is also a seat's handle reads as the seat, so a Unit named so<br />is refused here as a Conflict. |  | MaxItems: 64 <br />Optional: \{\} <br /> |
| `workers` _string array_ | workers narrows which of the company's delegate templates (the<br />workers block of the Company's engineConfig) the seat may use, by the<br />templates' names: a lowercase letter or digit, then lowercase letters,<br />digits, '_' and '-'. Unset is every one. Crewlet's `workers`. |  | MaxItems: 32 <br />items:MaxLength: 128 <br />items:MinLength: 1 <br />items:Pattern: `^[a-z0-9][a-z0-9_-]*$` <br />Optional: \{\} <br /> |
| `tokenBudget` _[TokenBudget](#tokenbudget)_ | tokenBudget caps the tokens this seat may spend per window, on top of<br />the Company's caps. Crewlet refuses a window below<br />turn_engine.executor_min_budget_tokens (25000 unless the Company's<br />spec.engineConfig sets turn_engine) on an Agent seat: an executor<br />launch needs that much of the window left, so the seat would never<br />launch one. The refusal comes from the engine's dry run, Invalid on<br />the Seat. Crewlet's `token_budget`. |  | MinProperties: 1 <br />Optional: \{\} <br /> |
| `llm` _[SeatLLM](#seatllm)_ | llm is the model providers the seat runs on. |  | MinProperties: 1 <br />Optional: \{\} <br /> |
| `learningEnabled` _boolean_ | learningEnabled overrides the company's learning setting for this<br />seat: false stops reflection after the seat's turns. Unset inherits.<br />Crewlet's `learning_enabled`. |  | Optional: \{\} <br /> |
| `mcp` _[MCPCredentials](#mcpcredentials) array_ | mcp are the seat's own tool-server credentials, which make it act as<br />itself on each server, and its own settings, such as the channel cache<br />of slack-mcp-server, which no other seat may share. They are merged<br />over its unit's, per variable. One entry per server, keyed by its<br />name. A credential of a vendor the engine provisions for the company<br />(GitLab or Mattermost under provisioning Engine, Datadog, an Atlassian<br />organization) is never given here: the engine hands the seat's own to<br />that vendor's server itself, and refuses one given here, which the<br />engine's dry run reports as Invalid on the Seat. A credential given<br />here is the seat's alone: Crewlet refuses a Secret key another seat or<br />an Integration names too. Crewlet's `mcp_env`, a credential position. |  | MaxItems: 16 <br />Optional: \{\} <br /> |
| `sandbox` _[SeatSandbox](#seatsandbox)_ | sandbox is the seat's own settings for its executor's box, which runs<br />whether or not it is set. Unset takes the Company's spec.sandbox alone.<br />Agent seats only. Crewlet's `sandbox`. |  | MinProperties: 1 <br />Optional: \{\} <br /> |
| `placement` _[SeatPlacement](#seatplacement)_ | placement is where the seat runs. Unset runs it in the Company's<br />spec.topology.defaultSeatPool. |  | Optional: \{\} <br /> |
| `paused` _boolean_ | paused says whether the seat may take work. True pauses it: it starts<br />no new turn, the mail it is sent waits on its inbox in order, and its<br />schedules' fires are skipped rather than queued; the turn it is on<br />finishes first unless stopRunning is set. False resumes it, and what<br />waited is delivered first. Unset leaves the seat's pause to the people<br />who run the company in the engine's dashboard: the operator reports a<br />pause they take, and never lifts it.<br />A pause is not part of the company document. Crewlet keeps it in its<br />coordination store, changed through its operator catalogue's<br />pause_seat and resume_seat tools, which the operator calls under the<br />Company's Enforce policy whenever the seat's pause differs from this<br />field; under Observe and Seed it only reports the difference. |  | Optional: \{\} <br /> |
| `pauseReason` _string_ | pauseReason is why the seat is paused, shown on the seat and in its<br />feed in the engine. Only with paused true. The engine keeps the<br />reason a pause was taken with, so a reason changed while the seat<br />stays paused shows from the seat's next pause on. Crewlet's pause<br />`reason`. |  | MaxLength: 500 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `stopRunning` _boolean_ | stopRunning ends the seat's running work when it is paused, rather<br />than letting it finish: the turn it is on at its next round, and its<br />executor run, launching or running, at once, its tool bridge closed,<br />what it spent charged and its box reclaimed. What was stopped is not<br />run again, and the engine records the stop as the operator's. A run<br />parked on a person's question stays parked behind the pause. Only with<br />paused true. Setting it on a seat already paused stops its running<br />work then; unsetting it changes nothing, since a stopped turn stays<br />stopped. Crewlet's pause `stop_running`. |  | Optional: \{\} <br /> |
| `integrations` _[SeatIntegrations](#seatintegrations)_ | integrations is the seat's own identity on the company's<br />integrations. |  | MinProperties: 1 <br />Optional: \{\} <br /> |
| `project` _string_ | project is the tracker project a seat outside every unit owns, by its<br />key; a seat in a unit takes its unit's. Crewlet requires a container<br />key to be an upper-case letter followed by 1 to 9 upper-case letters or<br />digits, such as LEAD. Crewlet's `project`. |  | MaxLength: 10 <br />MinLength: 2 <br />Pattern: `^[A-Z][A-Z0-9]\{1,9\}$` <br />Optional: \{\} <br /> |
| `space` _string_ | space is the knowledge container a seat outside every unit owns, by<br />its key, which follows the same rule as project; a seat in a unit<br />takes its unit's. Crewlet's `space`. |  | MaxLength: 10 <br />MinLength: 2 <br />Pattern: `^[A-Z][A-Z0-9]\{1,9\}$` <br />Optional: \{\} <br /> |
| `contact` _[SeatContact](#seatcontact)_ | contact is how agents reach the person in a Human seat on a vendor's<br />chat surface or tool, and how what the person does there reaches the<br />engine as theirs. It applies to Human seats only, and is optional: a<br />person who works only through the engine's dashboard has no account to<br />name, and signs in on the seat through the engine's own identity<br />directory. On a company that talks on Slack or Mattermost (an<br />Integration of either, or a seat's Slack app) the engine warns of a<br />Human seat with no account there, a slackUserID or a<br />mattermostUsername, since nothing addressed to it there reaches<br />anybody; a GitHub, GitLab or Atlassian account does not count, and the<br />operator records the warning as an EngineWarnings event on the<br />Company. On Chatlet, which a company with neither talks on, the person<br />reads the rooms on the dashboard as their seat, and nothing is warned. |  | MinProperties: 1 <br />Optional: \{\} <br /> |
| `availability` _string_ | availability tells colleagues of a Human seat when to expect an<br />answer, such as "CET business hours". Crewlet's `availability`. |  | MaxLength: 256 <br />MinLength: 1 <br />Optional: \{\} <br /> |


#### SeatStatus



SeatStatus is what the operator observed about a Seat.

_Validation:_
- MinProperties: 1

_Appears in:_
- [Seat](#seat)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.37/#condition-v1-meta) array_ | conditions are Accepted (the Company exists, and no other Seat has the<br />handle, the email or a contact account; Conflict names the other),<br />ResolvedRefs (the unit, the providers, the tool servers and every<br />Secret key exist), Applied (the seat is in the revision the engine<br />runs), and on an Agent seat Ready and, once the engine runs it, Paused<br />(whether the engine holds it paused, and whether that is what<br />spec.paused asks). Ready is True, LeaseHeld, while an engine node holds<br />the seat's lease and runs it, naming the provider its executor runs on<br />and where; False while none does (Unplaced, or PoolNotFound), and<br />False whoever holds it while its executor can run no turn as its spec<br />places it: NotExposed or SandboxLoginNotPortable. |  | MaxItems: 8 <br />Optional: \{\} <br /> |
| `observedGeneration` _integer_ | observedGeneration is the metadata.generation this status describes. |  | Minimum: 1 <br />Optional: \{\} <br /> |
| `handle` _string_ | handle is the seat's handle: spec.handle, or the metadata.name. |  | MaxLength: 63 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `seatID` _string_ | seatID is the seat's identity in the engine, derived from the company<br />name and the handle, so that callers need not derive it themselves.<br />Unset for a Human seat, which the engine does not run and gives no<br />identity, and for a seat whose handle another Seat derives too. |  | MaxLength: 36 <br />MinLength: 36 <br />Optional: \{\} <br /> |
| `placement` _[SeatPlacementStatus](#seatplacementstatus)_ | placement is where the engine runs the seat. Unset for a Human seat,<br />which the engine does not run. |  | MinProperties: 1 <br />Optional: \{\} <br /> |
| `integrations` _[SeatIntegrationsStatus](#seatintegrationsstatus)_ | integrations is the addresses the seat's vendor apps must use. Unset<br />for a Human seat, which has no vendor apps of its own. |  | MinProperties: 1 <br />Optional: \{\} <br /> |
| `pause` _[SeatPauseStatus](#seatpausestatus)_ | pause is the seat's pause while the engine holds it paused, whoever<br />paused it: the operator, for spec.paused, or a person in the engine's<br />dashboard. Unset while the seat takes work. |  | MinProperties: 1 <br />Optional: \{\} <br /> |


#### SecondFactor

_Underlying type:_ _string_

SecondFactor is whether a person signing in to a company's dashboard with a
password must also prove a second factor. It maps onto Crewlet's
api.auth.totp (Required is `required`, Optional is `optional`).

_Validation:_
- Enum: [Required Optional]

_Appears in:_
- [SignInSettings](#signinsettings)

| Field | Description |
| --- | --- |
| `Required` | SecondFactorRequired has everyone who signs in with a password also<br />give a code from an authenticator app, or one of their recovery<br />codes, and has a person without one set it up at their first sign-in,<br />before anything else. It is Crewlet's default.<br /> |
| `Optional` | SecondFactorOptional lets a person sign in with a password alone. A<br />person may still set up an authenticator app, and is then asked for<br />its code like everyone under Required; nobody is made to.<br /> |


#### SecretEnvVar



SecretEnvVar is a named credential delivered as an environment variable,
such as a sandbox setup step's token or a coding CLI's model key. Crewlet
treats every value in the positions that use this type as a credential, so
a literal value is not accepted: the value always comes from a Secret.



_Appears in:_
- [LLMProviderSpec](#llmproviderspec)
- [SandboxSetupStep](#sandboxsetupstep)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `name` _string_ | name is the variable's name. |  | MaxLength: 128 <br />MinLength: 1 <br />Pattern: `^[A-Za-z_][A-Za-z0-9_]*$` <br />Required: \{\} <br /> |
| `valueFrom` _[SecretValueSource](#secretvaluesource)_ | valueFrom is the Secret key the value is read from. |  | Required: \{\} <br /> |


#### SecretKeyReference



SecretKeyReference selects one key of a Secret in the referring object's
namespace. The operator reads the value when it renders the company and
pushes it into the engine's encrypted secret store; the value itself never
appears in the company document, in a pod template or in any status.



_Appears in:_
- [AtlassianIntegration](#atlassianintegration)
- [CLIAgentAuth](#cliagentauth)
- [ConfluenceIntegration](#confluenceintegration)
- [DatadogIntegration](#datadogintegration)
- [E2BSandbox](#e2bsandbox)
- [EmbeddingSettings](#embeddingsettings)
- [GitHubIntegration](#githubintegration)
- [GitLabEngineProvisioning](#gitlabengineprovisioning)
- [GitLabIntegration](#gitlabintegration)
- [JiraIntegration](#jiraintegration)
- [MattermostEngineProvisioning](#mattermostengineprovisioning)
- [SeatCredentialSource](#seatcredentialsource)
- [SecretValueSource](#secretvaluesource)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `name` _string_ | name is the metadata.name of the Secret. |  | MaxLength: 253 <br />MinLength: 1 <br />Required: \{\} <br /> |
| `key` _string_ | key is the key within the Secret's data. |  | MaxLength: 253 <br />MinLength: 1 <br />Pattern: `^[-._a-zA-Z0-9]+$` <br />Required: \{\} <br /> |


#### SecretReference



SecretReference names a whole Secret in the referring object's namespace.
It is used where one credential is several values that are always issued
together (a Slack app's bot token and signing secret, for example); the
field that holds the reference documents the keys the Secret must carry.



_Appears in:_
- [CompanyObjects](#companyobjects)
- [CompanyStatus](#companystatus)
- [GitHubApp](#githubapp)
- [SlackSeatIntegration](#slackseatintegration)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `name` _string_ | name is the metadata.name of the Secret. |  | MaxLength: 253 <br />MinLength: 1 <br />Required: \{\} <br /> |


#### SecretValueSource



SecretValueSource says where a credential's value comes from. It has one
member today; it is a struct so that a second source can be added without
reshaping every list that carries credentials.



_Appears in:_
- [EnvVar](#envvar)
- [MCPCredentialValue](#mcpcredentialvalue)
- [MCPEnvVar](#mcpenvvar)
- [MCPHeader](#mcpheader)
- [MattermostSeatIntegration](#mattermostseatintegration)
- [SandboxFile](#sandboxfile)
- [SecretEnvVar](#secretenvvar)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `secretKeyRef` _[SecretKeyReference](#secretkeyreference)_ | secretKeyRef selects the Secret key that holds the value. |  | Required: \{\} <br /> |


#### SignInSettings



SignInSettings is how people prove who they are when they sign in to the
dashboards of a class's companies.

It is the class's, not the Company's, because it weakens how people prove
who they are, which is the platform's decision: a tenant could otherwise
lower it for every person of its company, and the people who sign in are
often not the people who write the Company. A platform offers it the way it
offers exposure.trustedProxies, on a class it writes for the companies that
may run with it (a test rig, a demo tier).

_Validation:_
- MinProperties: 1

_Appears in:_
- [EngineClassSpec](#engineclassspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `secondFactor` _[SecondFactor](#secondfactor)_ | secondFactor is whether a person who signs in with a password must<br />also give a code from an authenticator app (Required), or may sign<br />in with the password alone (Optional). Crewlet's api.auth.totp.<br />Optional is refused by Crewlet on an address a browser reaches over<br />the network unless acceptInsecure acknowledges it, and the engine<br />judges that by where it is told people reach it, the Company's<br />status.endpoints.dashboardBaseURL: a host of localhost (in any case)<br />or a loopback IP, such as the http://localhost:8080 of a company<br />reached through kubectl port-forward, needs no acknowledgement, and<br />any other host does. A company of the class whose address needs one<br />it does not have keeps its engine's pods as they are, with<br />RuntimeReady=False InsecureSignInNotAcknowledged, rather than start<br />an engine that refuses to boot. The engine reads it only at start, so<br />a change to Optional or back restarts each company's data pod. | Required | Enum: [Required Optional] <br />Optional: \{\} <br /> |
| `acceptInsecure` _boolean_ | acceptInsecure acknowledges that a company of the class lets people<br />sign in with a password alone on an address a browser reaches over<br />the network: it is what lets secondFactor Optional run there, and<br />applies to secondFactor Optional only. It lifts nothing else, plain<br />http on such an address included, which the engine warns of either<br />way. While it is set the engine logs a config_advisory line at WARN<br />at every start, saying the insecure sign-in settings are allowed at<br />its address, for as long as the class sets it. Crewlet's<br />api.auth.accept_insecure. |  | Optional: \{\} <br /> |


#### SlackIntegration



SlackIntegration turns Slack on for a company. It maps onto Crewlet's
integrations.slack. Slack has no company-wide credential: every agent seat
that speaks on Slack has its own app, in its Seat's spec.integrations.slack.



_Appears in:_
- [IntegrationSpec](#integrationspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `typingStatus` _[WorkingStatus](#workingstatus)_ | typingStatus is when a seat shows that it is working. Unset takes<br />Crewlet's default, Always. Crewlet's `typing_status`. |  | Enum: [Always Addressed] <br />Optional: \{\} <br /> |
| `statusPhrases` _[StatusPhrases](#statusphrases)_ | statusPhrases replaces the words the working indicator shows.<br />Crewlet's `status_phrases`. |  | MinProperties: 1 <br />Optional: \{\} <br /> |


#### SlackSeatIntegration



SlackSeatIntegration is a seat's own Slack app, so the seat posts as itself.
It maps onto Crewlet's role integrations.slack and needs the company's Slack
Integration. Slack gives a bot no role: what the app may do is the bot token
scopes of its manifest, and where it may do it is the channels it is
invited to, so the block holds no access of its own.



_Appears in:_
- [SeatIntegrations](#seatintegrations)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `enabled` _boolean_ | enabled is whether the seat is on Slack. False keeps the block, and<br />the engine revokes the app's bot token rather than deleting the app;<br />turning it back on needs a person to approve the install again.<br />Crewlet's `enabled`. |  | Required: \{\} <br /> |
| `credentialsSecretRef` _[SecretReference](#secretreference)_ | credentialsSecretRef is a Secret holding the app's credentials under<br />the keys botToken (the bot token) and signingSecret (which verifies<br />the app's webhooks). Crewlet's `bot_token` and `signing_secret`, both<br />credential positions. Rewriting the Secret rotates them without a<br />restart. The Secret is the seat's alone: Crewlet refuses one another<br />seat or an Integration names too. |  | Required: \{\} <br /> |


#### SlackSeatStatus



SlackSeatStatus is the Slack side of a seat, as the operator computed it.

_Validation:_
- MinProperties: 1

_Appears in:_
- [SeatIntegrationsStatus](#seatintegrationsstatus)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `requestURL` _string_ | requestURL is the URL the seat's Slack app must deliver events to: its<br />Event Subscriptions request URL, <publicBaseURL>/webhooks/slack/<handle>,<br />where publicBaseURL is the Company's status.endpoints.publicBaseURL.<br />It is set whenever the Company has a Slack Integration and a public<br />base URL, whether or not this Seat sets spec.integrations.slack: a<br />platform that creates the seat's Slack app needs the URL for the app's<br />manifest before the app, and so its credentials, exist. Derived from<br />the handle, which never changes, it never changes for a seat either. |  | MaxLength: 2048 <br />MinLength: 1 <br />Optional: \{\} <br /> |


#### StatusPhrases



StatusPhrases replaces the words a seat's working indicator shows. Each line
completes the sentence "<seat> is …", and one line is picked per phase.
Each list maps onto the same-named list of Crewlet's status_phrases.

_Validation:_
- MinProperties: 1

_Appears in:_
- [SlackIntegration](#slackintegration)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `onboarding` _string array_ | onboarding is shown during a seat's first-turn onboarding pass. |  | MaxItems: 32 <br />items:MaxLength: 256 <br />items:MinLength: 1 <br />Optional: \{\} <br /> |
| `execute` _string array_ | execute is shown while the seat works. |  | MaxItems: 32 <br />items:MaxLength: 256 <br />items:MinLength: 1 <br />Optional: \{\} <br /> |
| `review` _string array_ | review is shown while the reviewer judges the seat's work. |  | MaxItems: 32 <br />items:MaxLength: 256 <br />items:MinLength: 1 <br />Optional: \{\} <br /> |
| `default` _string array_ | default is shown in any phase without lines of its own. |  | MaxItems: 32 <br />items:MaxLength: 256 <br />items:MinLength: 1 <br />Optional: \{\} <br /> |


#### StreamMode

_Underlying type:_ _string_

StreamMode is where a company's event stream runs.

_Validation:_
- Enum: [Embedded]

_Appears in:_
- [StreamSettings](#streamsettings)

| Field | Description |
| --- | --- |
| `Embedded` | StreamModeEmbedded runs NATS JetStream inside the engine process, with<br />its data on the data volume. An external NATS cluster is not offered in<br />v1alpha1.<br /> |


#### StreamSettings



StreamSettings is how a company's event stream runs.

_Validation:_
- MinProperties: 1

_Appears in:_
- [EngineClassSpec](#engineclassspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `mode` _[StreamMode](#streammode)_ | mode is where the stream runs. Embedded is the only mode in v1alpha1. | Embedded | Enum: [Embedded] <br />Optional: \{\} <br /> |


#### TelemetrySettings



TelemetrySettings sends the engine's traces and metrics to an OpenTelemetry
collector. The engine reads its exporter configuration from the standard
OTEL_* environment variables, which the operator sets from these fields;
with an endpoint set, Crewlet exports metrics as well as traces, and the
two cannot be turned off separately (OTEL_ names are the operator's, so
OTEL_METRICS_EXPORTER cannot be set in env). While a Company has a public
address (status.endpoints.publicBaseURL), the operator also wires Crewlet's
sandbox telemetry receiver there (CREWLET_SANDBOX_OTEL_RECEIVER_URL): a
seat's executor run in E2B exports to the engine's public listener with a
token signed for its one run, and the engine forwards it to this collector
with the headers below, which never enter the box. A seat's Direct run
exports the same way to its own engine pod's listener on loopback, with or
without a public address. Without one, no E2B box exports anything.



_Appears in:_
- [EngineClassSpec](#engineclassspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `otlpEndpoint` _string_ | otlpEndpoint is the collector's OTLP/HTTP endpoint<br />(OTEL_EXPORTER_OTLP_ENDPOINT). |  | MaxLength: 2048 <br />MinLength: 1 <br />Required: \{\} <br /> |
| `headersSecretRef` _[NamespacedSecretKeyReference](#namespacedsecretkeyreference)_ | headersSecretRef is a Secret key holding the headers sent to the<br />collector, in the OTEL_EXPORTER_OTLP_HEADERS format<br />(key1=value1,key2=value2), usually to authenticate. The operator copies<br />the value into a Secret it owns in each Company's namespace and<br />references it from the pod; the value never appears in the pod<br />template. It is in the engine's environment, which code the tenant<br />runs in the pod can read, so it reaches every tenant of the class: use<br />a credential that may only write telemetry, scoped per tenant where<br />the collector allows it. |  | Optional: \{\} <br /> |


#### TokenBudget



TokenBudget caps how many LLM tokens may be spent per calendar window on the
company's clock (spec.timeZone of the Company). Every window is optional and
independent; an absent window is uncapped. It maps onto Crewlet's
token_budget block.

_Validation:_
- MinProperties: 1

_Appears in:_
- [CompanyAssistant](#companyassistant)
- [CompanySpec](#companyspec)
- [SeatSpec](#seatspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `day` _integer_ | day is the most tokens one local day, midnight to midnight, may spend. |  | Minimum: 1 <br />Optional: \{\} <br /> |
| `week` _integer_ | week is the most tokens one ISO week, starting on Monday, may spend. |  | Minimum: 1 <br />Optional: \{\} <br /> |
| `month` _integer_ | month is the most tokens one calendar month may spend. |  | Minimum: 1 <br />Optional: \{\} <br /> |


#### TopologyStatus



TopologyStatus is the state of a company's pods.

_Validation:_
- MinProperties: 1

_Appears in:_
- [CompanyStatus](#companystatus)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `data` _[DataTopologyStatus](#datatopologystatus)_ | data is the state of the data pods. |  | MinProperties: 1 <br />Optional: \{\} <br /> |
| `seatPools` _[SeatPoolStatus](#seatpoolstatus) array_ | seatPools is the state of each seat pool's pods. |  | MaxItems: 8 <br />Optional: \{\} <br /> |


#### TrackerBackend

_Underlying type:_ _string_

TrackerBackend is which work tracker a company runs. It maps onto Crewlet's
tracker.backend (Worklet is `worklet`, Jira is `jira`, None is `none`).

_Validation:_
- Enum: [Worklet Jira None]

_Appears in:_
- [TrackerSettings](#trackersettings)

| Field | Description |
| --- | --- |
| `Worklet` | TrackerWorklet is Worklet, the engine's own tracker.<br /> |
| `Jira` | TrackerJira is Jira, connected by the company's Jira Integration.<br /> |
| `None` | TrackerNone is a company with no tracker.<br /> |


#### TrackerSettings



TrackerSettings is which work tracker a company runs. It maps onto
Crewlet's tracker block.

_Validation:_
- MinProperties: 1

_Appears in:_
- [CompanySpec](#companyspec)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `backend` _[TrackerBackend](#trackerbackend)_ | backend is which tracker the company runs. | Worklet | Enum: [Worklet Jira None] <br />Optional: \{\} <br /> |
| `worklet` _[WorkletSettings](#workletsettings)_ | worklet is the policy of Worklet, for backend Worklet. |  | MinProperties: 1 <br />Optional: \{\} <br /> |


#### UnconfirmedRevision



UnconfirmedRevision is a write of the company document whose activation the
engine could not confirm.



_Appears in:_
- [ConfigStatus](#configstatus)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `revisionID` _string_ | revisionID is the revision the engine stored for the write. |  | MaxLength: 128 <br />MinLength: 1 <br />Required: \{\} <br /> |
| `baseRevisionID` _string_ | baseRevisionID is the revision the write was built on, which its<br />activation was conditioned on. Empty for a write into an engine that<br />ran no document, conditioned on there being none. |  | MaxLength: 128 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `appliedHash` _string_ | appliedHash is the appliedHash of the write: the rendered document's<br />and its values' hash as they were when it was written, which<br />status.config.appliedHash records once the engine is seen running the<br />revision. |  | MaxLength: 128 <br />MinLength: 1 <br />Required: \{\} <br /> |
| `writtenAt` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.37/#time-v1-meta)_ | writtenAt is when the operator wrote it. A write the engine is seen<br />running is recorded as applied when the operator found it, since<br />nothing says when its activation landed; a seed taken from overtaken,<br />which nothing waits on, as applied when it was written. |  | Required: \{\} <br /> |
| `objects` _[AppliedObjectCounts](#appliedobjectcounts)_ | objects counts the objects the revision was rendered from, which<br />status.config.objects records once the engine is seen running it. |  | MinProperties: 1 <br />Optional: \{\} <br /> |
| `replaced` _[ReplacedRevision](#replacedrevision)_ | replaced says what the write replaced where that was more than the<br />operator's own document, which ConfigApplied and a Warning event report<br />once the engine is seen running the revision, as they report a write the<br />engine confirmed: Unsealed, a revision the engine stores without a seal,<br />which the write replaces reading nothing from it; Drifted, a revision<br />the operator did not write whose document differed from the rendered<br />one, at driftedAt. Unset for any other base, and for a reload: its base<br />is a write of the operator's, and where that write is recorded here too,<br />the revision found running reports what that write replaced, once,<br />whichever of the two it is. |  | Enum: [Unsealed Drifted] <br />Optional: \{\} <br /> |
| `driftedAt` _string_ | driftedAt names where the Drifted revision the write replaced differed<br />from the rendered document, as ConfigApplied names it: up to five<br />places, and how many more there were. |  | MaxLength: 32768 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `documentSHA256` _string_ | documentSHA256 is set for a reload: the SHA-256, in hex, of the<br />document of the revision it activates again, as the engine answered<br />it. The engine activates again whichever revision is active when the<br />request lands, so the revision it stored is the operator's only where<br />its document is that one; one found running another document was a<br />reload of a revision somebody activated in between, and goes. |  | MaxLength: 64 <br />MinLength: 64 <br />Pattern: `^[0-9a-f]\{64\}$` <br />Optional: \{\} <br /> |


#### Unit



Unit is one node of a company's org chart. Units nest through
spec.parentRef; Seats join one through spec.unitRef.

The Unit's metadata.name is the unit's stable id in Crewlet, which has its
own rules: it must start with a lowercase letter and be at most 64
characters, and may hold lowercase letters, digits and '-'. (Crewlet also
admits '_' in a unit id, which no Kubernetes name can hold.)





| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `apiVersion` _string_ | `crewlet.ai/v1alpha1` | | |
| `kind` _string_ | `Unit` | | |
| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.37/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. |  | Optional: \{\} <br /> |
| `spec` _[UnitSpec](#unitspec)_ | spec is the unit's desired state. |  | Required: \{\} <br /> |
| `status` _[UnitStatus](#unitstatus)_ | status is the unit's observed state. |  | MinProperties: 1 <br />Optional: \{\} <br /> |


#### UnitSpec



UnitSpec is one node of a company's org chart: a division, a team, a squad.
It renders to one entry of Crewlet's units, nested under its parent's.



_Appears in:_
- [Unit](#unit)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `companyRef` _[CompanyReference](#companyreference)_ | companyRef names the Company this unit belongs to. Immutable. |  | Required: \{\} <br /> |
| `displayName` _string_ | displayName is the unit's name as people read it, in prompts and on<br />boards. Unset is the Unit's metadata.name. The metadata.name itself is<br />the unit's stable id, which survives a rename. Crewlet's `name`; the<br />metadata.name is Crewlet's `id`, the key a seat's manages entry names<br />the unit by. The displayName is for reading only: nothing refers to a<br />unit by it, so two Units may share one. |  | MaxLength: 256 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `type` _[UnitType](#unittype)_ | type is an informational label. Crewlet's `type`. |  | Enum: [Division Department Group Team Squad Pod Guild Chapter Unit] <br />Optional: \{\} <br /> |
| `parentRef` _[LocalObjectReference](#localobjectreference)_ | parentRef names the Unit this one belongs to. Unset makes it a<br />top-level unit. A parent that does not exist, or a chain of parents<br />that leads back to this unit, is reported on this Unit. |  | Optional: \{\} <br /> |
| `leadRef` _[LocalObjectReference](#localobjectreference)_ | leadRef names the Seat that leads the unit. Unset inherits the<br />parent's lead. Crewlet's `lead`. |  | Optional: \{\} <br /> |
| `purpose` _string_ | purpose is what the unit is for. Crewlet's `purpose`. |  | MaxLength: 2048 <br />MinLength: 1 <br />Optional: \{\} <br /> |
| `goals` _string array_ | goals are what the unit is working toward. Crewlet's `goals`. |  | MaxItems: 32 <br />items:MaxLength: 1024 <br />items:MinLength: 1 <br />Optional: \{\} <br /> |
| `channel` _string_ | channel is the unit's channel on the company's chat surface, by name,<br />such as platform; child units without one inherit it. On Chatlet, the<br />engine's own chat and the surface of a company that declares no<br />Mattermost or Slack Integration, each channel a unit names is a room<br />whose members follow the org chart. Crewlet takes lowercase letters,<br />digits, - and _, starting with a letter or a digit, up to 64<br />characters: the name itself, never #platform or a vendor's channel id.<br />On Chatlet a room belongs to one unit, so Crewlet refuses a second unit<br />naming the same channel; a child unit that should share its parent's<br />room names none. Crewlet's `channel`. |  | MaxLength: 64 <br />MinLength: 1 <br />Pattern: `^[a-z0-9][a-z0-9_-]\{0,63\}$` <br />Optional: \{\} <br /> |
| `knowledge` _string array_ | knowledge are free-text references to knowledge the unit relies on.<br />They are not a read scope. Crewlet's `knowledge`. |  | MaxItems: 32 <br />items:MaxLength: 1024 <br />items:MinLength: 1 <br />Optional: \{\} <br /> |
| `project` _string_ | project is the tracker project the unit files work in, by its key.<br />Crewlet requires a container key to be an upper-case letter followed<br />by 1 to 9 upper-case letters or digits, such as PLAT. Crewlet's<br />`project`. |  | MaxLength: 10 <br />MinLength: 2 <br />Pattern: `^[A-Z][A-Z0-9]\{1,9\}$` <br />Optional: \{\} <br /> |
| `space` _string_ | space is the knowledge container the unit writes pages in, by its<br />key, which follows the same rule as project. Crewlet's `space`. |  | MaxLength: 10 <br />MinLength: 2 <br />Pattern: `^[A-Z][A-Z0-9]\{1,9\}$` <br />Optional: \{\} <br /> |
| `mcp` _[MCPCredentials](#mcpcredentials) array_ | mcp are tool-server credentials and settings every agent seat<br />directly in this unit inherits; a seat's own values win per variable.<br />One entry per server, keyed by its name. Crewlet's `mcp_env`, a<br />credential position. A value one seat must not share, such as<br />slack-mcp-server's channel cache or a seat's own credential, belongs<br />on the Seat. |  | MaxItems: 16 <br />Optional: \{\} <br /> |


#### UnitStatus



UnitStatus is what the operator observed about a Unit.

_Validation:_
- MinProperties: 1

_Appears in:_
- [Unit](#unit)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.37/#condition-v1-meta) array_ | conditions are Accepted (the Company exists), ResolvedRefs (the<br />parent, the lead, the tool servers and every Secret key exist, and the<br />parents form no cycle) and Applied (the unit is in the revision the<br />engine runs). |  | MaxItems: 8 <br />Optional: \{\} <br /> |
| `observedGeneration` _integer_ | observedGeneration is the metadata.generation this status describes. |  | Minimum: 1 <br />Optional: \{\} <br /> |
| `depth` _integer_ | depth is the unit's distance from the top of the chart: 0 for a<br />top-level unit. |  | Minimum: 0 <br />Optional: \{\} <br /> |
| `seats` _integer_ | seats is the number of Seats directly in the unit. |  | Minimum: 0 <br />Optional: \{\} <br /> |


#### UnitType

_Underlying type:_ _string_

UnitType is an informational label for a unit; nothing in the engine
behaves differently for one. It maps onto Crewlet's well-known unit types
(Division is `division`, Team is `team`, and so on).

_Validation:_
- Enum: [Division Department Group Team Squad Pod Guild Chapter Unit]

_Appears in:_
- [UnitSpec](#unitspec)

| Field | Description |
| --- | --- |
| `Division` |  |
| `Department` |  |
| `Group` |  |
| `Team` |  |
| `Squad` |  |
| `Pod` |  |
| `Guild` |  |
| `Chapter` |  |
| `Unit` |  |


#### WebhookExposure



WebhookExposure is how vendors' webhooks, and the calls coding runs make
back to the engine, reach a company's engine: the tool bridge calls and the
traces of a seat's executor run in E2B, and Ask Crewlet's deep
work's calls, a seat's Direct run dialling its own engine pod on loopback
instead. Whatever the mode, they
reach the engine's public listener (Crewlet's api.public), a port of its
own that serves only the routes outside parties call without an operator
credential (/webhooks/, /otlp/{token}, /mcp/{token}) and answers every
other path as one nothing serves; the admin API, the dashboard and the
probes are on the API port, which this never reaches.

_Validation:_
- MinProperties: 1

_Appears in:_
- [ExposureSettings](#exposuresettings)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `mode` _[WebhookExposureMode](#webhookexposuremode)_ | mode is how webhooks reach the engine. | None | Enum: [Gateway Ingress External None] <br />Optional: \{\} <br /> |
| `gateway` _[GatewayExposure](#gatewayexposure)_ | gateway is the Gateways to attach to, for mode Gateway. |  | Optional: \{\} <br /> |
| `ingress` _[IngressExposure](#ingressexposure)_ | ingress is the Ingress settings, for mode Ingress. |  | Optional: \{\} <br /> |
| `external` _[ExternalExposure](#externalexposure)_ | external is where the forwarder runs, for mode External. |  | MinProperties: 1 <br />Optional: \{\} <br /> |
| `hostname` _string_ | hostname is the public host name of each company, as a template:<br />\{\{namespace\}\}, \{\{name\}\} and \{\{uid\}\} are replaced by the Company's<br />namespace, name and UID. The result is the company's public base URL,<br />https://<hostname>, which every vendor is told to deliver to. Prefer<br />\{\{uid\}\}: the host name is public, and a UID says nothing about the<br />tenant where a name can; and a UID is never reused, so a vendor still<br />configured for a deleted company can never reach a company created<br />later under the same name. The template must contain \{\{uid\}\}, or<br />\{\{name\}\} and \{\{namespace\}\} joined by a '.', which neither can hold, so<br />that no two companies share a host name: with a '-' between them,<br />team-a/b-web and team-a-b/web would. |  | MaxLength: 253 <br />MinLength: 1 <br />Optional: \{\} <br /> |


#### WebhookExposureMode

_Underlying type:_ _string_

WebhookExposureMode is how vendors' webhooks reach a company's engine.

_Validation:_
- Enum: [Gateway Ingress External None]

_Appears in:_
- [WebhookExposure](#webhookexposure)

| Field | Description |
| --- | --- |
| `Gateway` | WebhookExposureGateway routes the public hostname to the engine's<br />public listener with an HTTPRoute.<br /> |
| `Ingress` | WebhookExposureIngress does the same with an Ingress.<br /> |
| `External` | WebhookExposureExternal creates nothing public: something outside the<br />operator (a relay, an API gateway) forwards to the public port of the<br />engine's Service, and each Company states the address it is reached<br />on in spec.exposure.publicBaseURL.<br /> |
| `None` | WebhookExposureNone exposes nothing; integrations that need inbound<br />delivery report that they are not exposed.<br /> |


#### WorkingStatus

_Underlying type:_ _string_

WorkingStatus is when a seat shows that it is working on a chat message. It
maps onto Crewlet's typing_status (Always is `always`, Addressed is
`addressed`).

_Validation:_
- Enum: [Always Addressed]

_Appears in:_
- [ChatletSettings](#chatletsettings)
- [MattermostIntegration](#mattermostintegration)
- [SlackIntegration](#slackintegration)

| Field | Description |
| --- | --- |
| `Always` | WorkingStatusAlways shows it on every turn a chat message started.<br /> |
| `Addressed` | WorkingStatusAddressed shows it only when a person is plausibly<br />waiting on the seat: a direct message, a mention of it by name, and<br />on Slack or Mattermost a thread it is in because it was named there,<br />on Chatlet a reply in a thread it started or a person's message in a<br />unit's room that reached nobody else and so falls to it as the unit's<br />lead. Never a message it reached through a room-wide address, or only<br />by having spoken in the thread before.<br /> |


#### WorkletSettings



WorkletSettings is the policy of Worklet. It maps onto Crewlet's
tracker.worklet.

_Validation:_
- MinProperties: 1

_Appears in:_
- [TrackerSettings](#trackersettings)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `inboxRetentionDays` _integer_ | inboxRetentionDays is how long a person's inbox keeps a row; the<br />history the row points at is kept regardless. Unset takes Crewlet's<br />default of 365. Crewlet's `inbox_retention_days`. |  | Maximum: 3650 <br />Minimum: 30 <br />Optional: \{\} <br /> |