Server configuration reference
The server configuration is the one file that tells a vect serve process, a vect worker, or a CLI-direct command what it is: where it listens, which workspaces it acts on, where their stores live, who may call it, and where it sends events. This page lists every block and attribute the loader accepts. The normative text is the server configuration spec (requirement IDs CONF-*). For what the stores hold, see Inventory, bundles, and storage; for approvals and task queues, see Runs.
All examples are in docs/site/examples/reference/server-config/config/ in the vect repository. Run them from that folder with VECT_CONFIG=<file> vect runs --workspace <name>: validate does not read the server configuration, but any command that connects to the API does, and it prints every diagnostic before doing anything else.
File
- Location.
--config <file>or theVECT_CONFIGenvironment variable (the flag wins). With neither, vect uses built-in defaults: noserverblock, no workspaces,aferostores under.vect/data.vect serveandvect workerrefuse to start without a file. - Relative paths in the file (
data_dir,path,cert_file,key_file,token_file) resolve against the current working directory, not the file’s folder. - Syntax. One HCL file of literals. The only function is
env("NAME"), which reads an environment variable at startup; an unset or empty variable is a diagnostic. Any other expression, reference, or function is a diagnostic. - Durations are strings in Go
time.ParseDurationsyntax plus adunit of 24 hours:"90s","30m","7d". They must be positive. - Top-level blocks are exactly
server,store_naming,defaults,workspace,loop,external_workspace,authenticator,client_auth,policy, andevent_sink. Anything else is a diagnostic with a source range.server,store_naming,defaults,client_auth, andpolicyappear at most once; the others at most once per label set. - Errors. An invalid file stops
vect servebefore it listens, and stops a CLI-direct command with exit code1. Every diagnostic is printed in one pass. For example,invalid-config/bad.server.vectnext to the examples:
$ VECT_CONFIG=bad.server.vect vect runs --workspace dev
Error: Unsupported block type
on bad.server.vect line 10, in store_namin:
10: store_namin {
Blocks of type "store_namin" are not expected here. Did you mean "store_naming"?
Error: Missing temporal block
on bad.server.vect line 6, in workspace "dev":
6: workspace "dev" {
A temporal block is required.
Error: Insecure listen address
on bad.server.vect line 3, in server:
3: listen = ":8443"
":8443" is not a loopback address; without a tls block only loopback addresses are accepted.
An unreadable file prints Error: Cannot read server configuration and exits 1.
The smallest useful file, defaults.server.vect, holds only the engine version default. A file need not contain a server or workspace block for offline commands such as vect bundle:
defaults {
opentofu_version = "1.10.6"
}server
The runner’s own settings. Optional for CLI-direct commands, required by vect serve. At most one.
| Attribute | Type | Default | Description |
|---|---|---|---|
name | string | required | Names this runner. Loops act as the principal runner:<name>. Must not be empty. |
listen | string | none | Address of the API listener, such as 127.0.0.1:8443. vect serve requires it. Without a tls block only loopback addresses (localhost, 127.0.0.1, [::1]) are accepted; :8443 is every interface and is rejected. |
default_workspace | string | none | The workspace commands use when --workspace and VECT_WORKSPACE are not given. Must name a declared workspace block. |
data_dir | string | .vect/data | Directory for afero stores. Workspace stores default to <data_dir>/<workspace>; the bundle store to <data_dir>/bundles. Bundling keeps verified engine and provider downloads in <data_dir>/downloads. |
drain_timeout | duration | 15m | How long vect serve and vect worker let running activities finish on shutdown before cancelling them. |
engine_stop_grace | duration | 30s | How long a stopped terraform engine has to exit after SIGINT before its process group is killed. It never outlasts the shutdown drain. A lost lease kills the engine at once, whatever this is. See Cancelling a run. |
fleet_views | list of string | none | Accepted by the loader. It has no effect in this version. |
Blocks:
tls { cert_file, key_file }: both strings, both required. Enables HTTPS onlisten(TLS 1.2 or later) and allows non-loopback addresses.bundles { backend, region, path, name }: the one server-wide bundle store. See Store blocks for the attributes;backendiss3orafero, andnameis required fors3. Without the block the bundle store isaferounder<data_dir>/bundles.
Spec: CONF-SRV-1, CONF-SRV-4, CONF-SRV-5, EXEC-TF-14. See also local.server.vect:
server {
name = "local"
listen = "127.0.0.1:8443"
default_workspace = "dev"
data_dir = ".vect/data"
drain_timeout = "5m"
}defaults
Engine versions for opentofu and terraform roots that carry no required_version constraint. At most one block.
| Attribute | Type | Default | Description |
|---|---|---|---|
opentofu_version | string | none | Exact OpenTofu version, such as "1.10.6". |
terraform_version | string | none | Exact Terraform version, such as "1.9.8". |
Constraints such as "~> 1.10" are rejected: the value must be MAJOR.MINOR.PATCH, optionally with a pre-release suffix. Without the default for a root’s engine, an unconstrained root is a diagnostic at bundle time (Cannot resolve the opentofu version). Spec: CONF-SRV-3.
workspace
workspace "<name>" is one workspace this server acts on. The label is the workspace name. Zero or more blocks, each label once.
| Attribute | Type | Default | Description |
|---|---|---|---|
account | string | required | Account identifier, non-empty. Reserved for store naming; accepted and checked, with no other effect in this version. |
serve | bool | true | true: this server serves the workspace’s API. false: this server does not serve it, and the workspace’s API is at endpoint. Loops for such a workspace are not started in this version. |
endpoint | string | none | The workspace’s API URL. Required when serve = false. |
approval_timeout | duration | 30m | How long a run waits for an approval. |
plan_approvals | bool | true | Whether runs honor plan approvals. |
unattended_approvals | string | reject | What happens to an approval nobody can answer: reject or approve. |
saved_plans | string | replan | replan or reuse. |
plan_ttl | duration | 7d | How long a saved plan file stays valid. |
Blocks:
temporal { endpoint, namespace }: required, both strings required. The workspace’s Temporal service. A missing block isMissing temporal block.key_provider "<type>": at most one. See below.execution { ... }: see below.stores { ... }: see Store blocks.retention { versions, max_age, grace }: see below.
The server configuration of the runner that executes a run governs that run’s execution and approval settings, including for a serve = false workspace. Two workspaces may not map a capability to the same task queue (Shared task queue diagnostic); the same default_task_queue in two workspaces is not checked. See Runs for approvals. Spec: CONF-WS-1 to CONF-WS-8.
key_provider
Selects how the workspace’s value store keys are held. The label is the type.
| Type | Attribute | Type | Description |
|---|---|---|---|
aws_kms | key_id | string, required | KMS key ID, ARN, or alias. Uses the ambient AWS credentials and the values store’s region. |
local_file | path | string, required | Key file on the local filesystem. For afero stores. |
Without a key_provider block, a workspace with an afero values store keeps a key file at <values path>/keys; a workspace with an s3 values store must have one, or its first request fails with a workspace with an s3 value store needs a key_provider. Spec: CONF-WS-4.
execution
Routes nodes to task queues and sizes the worker’s slots. Optional; default_task_queue is required inside it.
| Attribute | Type | Default | Description |
|---|---|---|---|
default_task_queue | string | required | Task queue for nodes that require no capability. |
slots | map of string to number | 10 per queue | Concurrent activities per task queue, per worker process. Values must be positive. |
executor_slots | map of string to number | no limit | Concurrent activities per executor type (terraform, …), per worker process. Values must be positive. |
capability "<name>" { task_queue = "..." } maps an execution capability to a task queue; task_queue is required, and the block may repeat once per name. See Runs. Spec: CONF-WS-5.
execution {
default_task_queue = "vect"
slots = { "vect" = 20, "vect-vpc" = 4 }
executor_slots = { terraform = 4 }
capability "vpc" {
task_queue = "vect-vpc"
}
}retention
What garbage collection keeps. All attributes optional.
| Attribute | Type | Default | Description |
|---|---|---|---|
versions | number | 10 | Record versions kept per instance. |
max_age | duration | 30d | Age beyond which versions may be dropped. |
grace | duration | 7d | Delay before unreferenced objects are deleted. |
See Retention and garbage collection. Spec: CONF-WS-6.
The workspace block of local.server.vect, with its execution block (shown above) trimmed and every other optional setting at its default:
workspace "dev" {
account = "local"
temporal {
endpoint = "localhost:7233"
namespace = "default"
}
key_provider "local_file" {
path = ".vect/keys/dev.key"
}
execution {
…
}
approval_timeout = "30m"
plan_approvals = true
unattended_approvals = "reject"
saved_plans = "replan"
plan_ttl = "7d"
retention {
versions = 10
max_age = "30d"
grace = "7d"
}
}Store blocks
A workspace’s stores block holds one optional block per kind: state, inventory, values, and cas. A missing stores block, or a missing kind, is afero under <data_dir>/<workspace>: for local use and tests. The server.bundles block takes the same attributes.
| Attribute | Type | Default | Description |
|---|---|---|---|
backend | string | required | See the table below. |
region | string | ambient AWS region | AWS backends only. Rejected on afero. |
path | string | <data_dir>/<workspace> | afero only. Rejected on AWS backends. |
name | string | none | Bucket (s3) or table (dynamodb) name. |
| Block | Backends | Holds |
|---|---|---|
state | s3, afero | Engine state files for terraform executors. |
inventory | dynamodb, afero | Records, deployment pointers, leases, documents. |
values | s3, afero | Encrypted values. |
cas | s3, afero | The workspace’s encrypted objects. |
server.bundles | s3, afero | Bundle units, assemblies, manifests. |
name is required at runtime for s3 and dynamodb. Store naming from store_naming has not landed, so the loader accepts an AWS store without name, but the store cannot be opened (from the invalid-config/ folder):
$ VECT_CONFIG=noname.server.vect vect runs --workspace prod
vect: internal: workspace "prod" inventory: a dynamodb store needs a name
server.bundles is the exception: its name is checked at load time and an s3 bundle store without one is a diagnostic (server.bundles needs a name with the s3 backend). AWS stores use the ambient AWS credentials and are only contacted when first used, so a file such as aws.server.vect loads without network access:
workspace "prod" {
…
stores {
state {
backend = "s3"
region = "us-east-1"
name = "vect-prod-state"
}
inventory {
backend = "dynamodb"
region = "us-east-1"
name = "vect-prod-inventory"
}
values {
backend = "s3"
region = "us-east-1"
name = "vect-prod-values"
}
cas {
backend = "s3"
region = "us-east-1"
name = "vect-prod-cas"
}
}
}Spec: CONF-WS-7, CONF-SRV-4.
store_naming
store_naming {
template = "vect-{workspace}-{account}-{kind}"
}One required attribute, template (string). It is decoded, but in this version it is neither validated nor applied: set name on each AWS store instead (see above). At most one block. Spec: CONF-STORE-1, CONF-STORE-2.
loop
loop "<workspace>" "<name>" starts a loop on this runner. The first label must be a workspace block in the same file; the pair of labels is unique.
| Attribute | Type | Default | Description |
|---|---|---|---|
scopes | list of string | required | Non-empty list of address prefixes the loop owns, in --target syntax: a stack (stack.ctl, stack.a.stack.b) or an executor block (stack.ctl.terraform.pet, terraform.pet). Anything else, such as stack.ctl.x, is Invalid loop scope. Loops of one workspace may not overlap. |
lineage | string | required | <repository>@<branch>: the publications that trigger the loop. |
full_run_every | duration | 24h | Interval between full runs. |
facts_poll_every | duration | 1m | How often facts are polled. |
catch_up_wait | duration | 1h | How long the loop waits for an upstream to catch up. |
lease_wait | duration | 30m | How long the loop waits for a lease. |
allow_unordered_bundles | bool | false | Permits publications that are not in order. |
Spec: CONF-LOOP-1. For the loop model, see the fleet scheduling spec.
external_workspace
external_workspace "<name>" maps a workspace not configured on this server to its API.
| Attribute | Type | Default | Description |
|---|---|---|---|
endpoint | string | required | API URL. |
An optional nested client_auth block overrides the server’s for calls to this workspace. Spec: CONF-LOOP-2.
A workspace with serve = false, a loop, and an external_workspace together (loops.server.vect):
workspace "edge" {
serve = false
endpoint = "https://edge.internal.example"
account = "123456789012"
temporal {
endpoint = "localhost:7233"
namespace = "edge"
}
execution {
default_task_queue = "vect-edge"
}
}
loop "prod" "ctl" {
scopes = ["stack.ctl"]
lineage = "example/infra@main"
full_run_every = "24h"
facts_poll_every = "1m"
catch_up_wait = "1h"
lease_wait = "30m"
allow_unordered_bundles = false
}
external_workspace "fleet" {
endpoint = "https://fleet-ctl.internal.example"
client_auth {
token_file = "/var/run/vect/fleet-token"
}
}A request for a workspace with serve = false to the runner fails with workspace "edge" is not served by this runner.
authenticator
authenticator "<type>" "<name>" enables one network authenticator. A server can have several; a request is accepted by the first one, in file order, that accepts its credentials. local cannot be configured: it exists only on the in-memory loopback.
| Type | Required attributes | Description |
|---|---|---|
aws_web_identity | role_arn | Trusts AWS web identity tokens for the role. |
oidc | issuer, audience | Trusts tokens from an OIDC issuer. |
Both types take an optional max_token_lifetime (duration, default 15m). Supplying an attribute the type does not take is a diagnostic. Spec: CONF-AUTH-1, CONF-AUTH-2; see Authentication in the API spec.
client_auth
The credential this runner presents when it calls other workspaces. At most one top-level block; each external_workspace may contain its own. Exactly one of:
| Form | Description |
|---|---|
token_file = "<path>" | A file holding the bearer token. |
aws_web_identity { role_arn = "<arn>" } | AWS web identity, assuming the role. |
Zero or two is A client_auth block needs exactly one of token_file or aws_web_identity. Without any client_auth, the runner uses the token file named by AWS_WEB_IDENTITY_TOKEN_FILE. Spec: CONF-AUTH-4.
policy
Ordered rule blocks for the built-in static authorizer, which denies by default. At most one policy block.
| Attribute | Type | Default | Description |
|---|---|---|---|
effect | string | required | allow or deny. |
actions | list of string | required | Action globs, such as run.* or approval.approve:*. |
workspaces | list of string | required | Workspace name globs. |
targets | list of string | none | Address globs. |
principal | map of string to string | none | Attribute name to glob, such as { "claims.repository" = "example/infra" }. |
Globs use Go path.Match syntax with / an ordinary character; write a literal [ as \[. An invalid rule is reported as Invalid policy rule with its position. Spec: CONF-AUTH-3; see Authorization in the API spec. auth.server.vect:
authenticator "aws_web_identity" "ci" {
role_arn = "arn:aws:iam::123456789012:role/vect-api"
max_token_lifetime = "15m"
}
authenticator "oidc" "github" {
issuer = "https://token.actions.githubusercontent.com"
audience = "vect"
}
client_auth {
aws_web_identity {
role_arn = "arn:aws:iam::123456789012:role/vect-client"
}
}
policy {
rule {
effect = "allow"
actions = ["run.*", "approval.approve:*"]
workspaces = ["*-dev-*"]
principal = { "claims.repository" = "example/infra" }
}
rule {
effect = "deny"
actions = ["*"]
workspaces = ["*"]
}
}event_sink
event_sink "<type>" "<name>" delivers the event feed somewhere. Any number of blocks, each label pair once. A sink that cannot be built is logged and skipped; it never stops the server. Deliveries are not signed.
| Type | Attributes | Behavior |
|---|---|---|
webhook | url (required) | POSTs the event as JSON; any 2xx is delivered. url must be an absolute http or https URL. It may carry a secret, so it never appears in logs or errors. |
sns | topic_arn (required) | Publishes the same JSON, with the event name as the message attribute event. Must be an ARN. |
eventbridge | event_bus (default default), source (default vect) | Puts one entry per event: Source is source, DetailType the event name, Detail the JSON. |
All types take an optional events (list of string): the event names to deliver, default all. Event names are run.started, run.finished, run.failed, node.failed, node.stale, lock.created, lock.released, lock.expired, deploy.lock.exceeded, facts.fallback, loop.queue_blocked, spec.changed, change.failed, change.blocked, change.still_blocking, move.conflict, node.resolved, and workspace.retired; an unknown name is a diagnostic. Spec: CONF-SINK-1, CONF-SINK-2. sinks.server.vect:
event_sink "webhook" "chat" {
url = env("VECT_CHAT_WEBHOOK")
events = ["run.failed", "node.failed"]
}
event_sink "sns" "alerts" {
topic_arn = "arn:aws:sns:us-east-1:123456789012:vect-events"
}
event_sink "eventbridge" "bus" {
event_bus = "vect"
source = "vect.prod"
}With VECT_CHAT_WEBHOOK unset, the file does not load.