Skip to content
Server config

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 the VECT_CONFIG environment variable (the flag wins). With neither, vect uses built-in defaults: no server block, no workspaces, afero stores under .vect/data. vect serve and vect worker refuse 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.ParseDuration syntax plus a d unit 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, and event_sink. Anything else is a diagnostic with a source range. server, store_naming, defaults, client_auth, and policy appear at most once; the others at most once per label set.
  • Errors. An invalid file stops vect serve before it listens, and stops a CLI-direct command with exit code 1. Every diagnostic is printed in one pass. For example, invalid-config/bad.server.vect next 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.server.vect
defaults {
  opentofu_version = "1.10.6"
}

server

The runner’s own settings. Optional for CLI-direct commands, required by vect serve. At most one.

AttributeTypeDefaultDescription
namestringrequiredNames this runner. Loops act as the principal runner:<name>. Must not be empty.
listenstringnoneAddress 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_workspacestringnoneThe workspace commands use when --workspace and VECT_WORKSPACE are not given. Must name a declared workspace block.
data_dirstring.vect/dataDirectory 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_timeoutduration15mHow long vect serve and vect worker let running activities finish on shutdown before cancelling them.
engine_stop_graceduration30sHow 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_viewslist of stringnoneAccepted by the loader. It has no effect in this version.

Blocks:

  • tls { cert_file, key_file }: both strings, both required. Enables HTTPS on listen (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; backend is s3 or afero, and name is required for s3. Without the block the bundle store is afero under <data_dir>/bundles.

Spec: CONF-SRV-1, CONF-SRV-4, CONF-SRV-5, EXEC-TF-14. See also local.server.vect:

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.

AttributeTypeDefaultDescription
opentofu_versionstringnoneExact OpenTofu version, such as "1.10.6".
terraform_versionstringnoneExact 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.

AttributeTypeDefaultDescription
accountstringrequiredAccount identifier, non-empty. Reserved for store naming; accepted and checked, with no other effect in this version.
servebooltruetrue: 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.
endpointstringnoneThe workspace’s API URL. Required when serve = false.
approval_timeoutduration30mHow long a run waits for an approval.
plan_approvalsbooltrueWhether runs honor plan approvals.
unattended_approvalsstringrejectWhat happens to an approval nobody can answer: reject or approve.
saved_plansstringreplanreplan or reuse.
plan_ttlduration7dHow long a saved plan file stays valid.

Blocks:

  • temporal { endpoint, namespace }: required, both strings required. The workspace’s Temporal service. A missing block is Missing 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.

TypeAttributeTypeDescription
aws_kmskey_idstring, requiredKMS key ID, ARN, or alias. Uses the ambient AWS credentials and the values store’s region.
local_filepathstring, requiredKey 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.

AttributeTypeDefaultDescription
default_task_queuestringrequiredTask queue for nodes that require no capability.
slotsmap of string to number10 per queueConcurrent activities per task queue, per worker process. Values must be positive.
executor_slotsmap of string to numberno limitConcurrent 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.

AttributeTypeDefaultDescription
versionsnumber10Record versions kept per instance.
max_ageduration30dAge beyond which versions may be dropped.
graceduration7dDelay 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:

local.server.vect
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.

AttributeTypeDefaultDescription
backendstringrequiredSee the table below.
regionstringambient AWS regionAWS backends only. Rejected on afero.
pathstring<data_dir>/<workspace>afero only. Rejected on AWS backends.
namestringnoneBucket (s3) or table (dynamodb) name.
BlockBackendsHolds
states3, aferoEngine state files for terraform executors.
inventorydynamodb, aferoRecords, deployment pointers, leases, documents.
valuess3, aferoEncrypted values.
cass3, aferoThe workspace’s encrypted objects.
server.bundless3, aferoBundle 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:

aws.server.vect
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.

AttributeTypeDefaultDescription
scopeslist of stringrequiredNon-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.
lineagestringrequired<repository>@<branch>: the publications that trigger the loop.
full_run_everyduration24hInterval between full runs.
facts_poll_everyduration1mHow often facts are polled.
catch_up_waitduration1hHow long the loop waits for an upstream to catch up.
lease_waitduration30mHow long the loop waits for a lease.
allow_unordered_bundlesboolfalsePermits 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.

AttributeTypeDefaultDescription
endpointstringrequiredAPI 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):

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.

TypeRequired attributesDescription
aws_web_identityrole_arnTrusts AWS web identity tokens for the role.
oidcissuer, audienceTrusts 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:

FormDescription
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.

AttributeTypeDefaultDescription
effectstringrequiredallow or deny.
actionslist of stringrequiredAction globs, such as run.* or approval.approve:*.
workspaceslist of stringrequiredWorkspace name globs.
targetslist of stringnoneAddress globs.
principalmap of string to stringnoneAttribute 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:

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.

TypeAttributesBehavior
webhookurl (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.
snstopic_arn (required)Publishes the same JSON, with the event name as the message attribute event. Must be an ARN.
eventbridgeevent_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:

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.