How to run vect as a shared server
By the end of this guide a single vect serve process holds your project’s runs, authenticates every caller, denies anything your policy doesn’t allow, and starts applies by itself when CI publishes a new bundle. Your teammates and CI use the same vect commands they use today, pointed at the server.
You need the vect binary and a Temporal dev server, as in First steps, part 3. The example project is docs/site/examples/howto/serve/shared/ in the vect repository: one stack with one terraform_data executor, so nothing needs an account. Run IDs, digests, and timestamps in the output will differ from yours.
For why a run is the same thing CLI-direct and served, read How runs work; for loops, How change flows.
1. Start from a CLI-direct project
The folder holds main.hcl, a stack, a root, and two server configurations. local.server.vect is the CLI-direct one from First steps: no listen, no authentication, because the caller is the server.
server {
name = "local"
default_workspace = "dev"
}
defaults {
opentofu_version = "1.10.6"
}
workspace "dev" {
account = "howto"
temporal {
endpoint = "localhost:7233"
namespace = "default"
}
key_provider "local_file" {
path = ".vect/keys/dev.key"
}
execution {
default_task_queue = "vect"
}
}With temporal server start-dev running in another terminal:
export VECT_CONFIG=local.server.vect
vect apply…
stack.app.terraform.note: applied will run
apply of workspace "dev": succeeded (run 01a1e7da-6b51-758d-82f8-057ae6ee96e4)
stack.app.terraform.note applied (run) will run
deployment pointer 1 appended2. Add a server block with listen
shared.server.vect is the same file with three changes: listen in the server block, an authenticator, and a policy (below). Without TLS, listen must be a loopback address. This is checked before anything listens. For example, with listen = ":18482" in a copy of the file named bad1.server.vect, vect serve stops with:
Error: Insecure listen address
on bad1.server.vect line 3, in server:
3: listen = ":18482"
":18482" is not a loopback address; without a tls block only loopback addresses are accepted.For a non-loopback address, add a tls { cert_file, key_file } block to server. Leave listen out and vect serve exits 1 with vect: server.listen is not set.
drain_timeout (default 15m) is how long a stopping server lets running activities finish. The example sets it to 5m.3. Add an authenticator and a policy
A served runner authenticates every request and authorizes it against policy rules. The first matching rule decides, and a request no rule matches is denied.
# Your identity provider. vect contacts it on the first request, not at start.
authenticator "oidc" "sso" {
issuer = "https://idp.example.com"
audience = "vect"
}
# Everything not allowed here is denied. Anyone who authenticates may read;
# only the CI identity may publish bundles and start runs. A bundle belongs to
# no workspace, so bundle.upload is checked against an empty workspace name,
# which only a glob such as "*" matches.
policy {
rule {
effect = "allow"
actions = ["inventory.read", "workspace.read_outputs"]
workspaces = ["dev"]
}
rule {
effect = "allow"
actions = ["bundle.upload", "run.plan", "run.apply"]
workspaces = ["*"]
principal = { subject = "ci@example.com" }
}
}issuer is a placeholder here. vect serve does not contact the issuer at start, but a real token is only accepted when the issuer is reachable from the server. The transcripts below that need a valid token come from a throwaway local OIDC issuer, a small helper in the repository’s docs tooling that signs any token it is asked for. It stands in for your identity provider only so that these pages can be checked. To follow those steps yourself you need an issuer of your own (or aws_web_identity, see the reference).
Policy mistakes are diagnostics with a source position, and the message lists the valid action names. With run.apply misspelled as run.aply in the second rule of a copy named bad2.server.vect:
Error: Invalid policy rule
on bad2.server.vect line 46, in policy:
46: rule {
Rule 2: action "run.aply" matches no action; use one of bundle.upload, run.plan, run.apply,
run.destroy, run.cancel, approval.approve:destroy, approval.approve:state_move,
…Check a rule without an identity provider
CLI-direct commands act as the built-in local principal, which is allowed everything unless a rule says otherwise. That lets you test a rule offline. Append a rule to a copy of local.server.vect:
cp local.server.vect deny.server.vect
cat >> deny.server.vect <<'EOF'
policy {
rule {
effect = "deny"
actions = ["run.apply"]
workspaces = ["*"]
principal = { subject = "local" }
}
}
EOFThe engine’s own lines are left out of the outputs below.
VECT_CONFIG=deny.server.vect vect apply
VECT_CONFIG=deny.server.vect vect planvect: permission_denied: permission denied: run.apply on "*"
…
plan of workspace "dev": succeeded (run 01a1e7da-76e6-7874-a322-3fe603e8070d)
stack.app.terraform.note no-op inputs unchangedThe apply exits 1; the plan, which no rule mentions, still runs. A network caller never gets this free pass: the local principal exists only on the in-process connection.
4. Start the server and point commands at it
Sections 4 and 5 need a real OIDC issuer (or aws_web_identity) to follow past the refusals. Each token you present must be a signed JWT whose aud equals the audience (vect), whose sub equals the rule’s principal.subject (ci@example.com for CI, bob@example.com for the read-only user), and whose lifetime (exp minus iat) is at most max_token_lifetime (default 15m; a longer-lived token is rejected). Ask your identity provider for such a token and write it to a file; that file is what bob.token and ci.token mean below. Put the files outside the project folder (the commands below use your home folder), or list them in .vectignore, so a bundle doesn’t pack them. From vect 0.1.2, a bundle also leaves out the token files vect knows of (--token-file, VECT_TOKEN_FILE, AWS_WEB_IDENTITY_TOKEN_FILE, and the client_auth token files in the server configuration), and vect validate and vect bundle warn about other files with credential-looking names. See Token and credential files.
In the transcripts below, issuer in shared.server.vect points at the throwaway local issuer instead of https://idp.example.com, and the tokens come from it. Everything else is as shown.
Stop any CLI-direct command first; for local stores, use one mode per workspace at a time (the caution in How runs work). Then, from the project folder:
VECT_CONFIG=shared.server.vect vect servevect: serving on 127.0.0.1:8443The same process also runs a worker for each served workspace and starts a loop for each loop block.
In another terminal, tell the client where the server is. VECT_CONFIG stays set because the client reads default_workspace from it:
export VECT_CONFIG=shared.server.vect
export VECT_API_URL=http://127.0.0.1:8443The server is refusing unauthenticated callers already. Without a token, and with a token the issuer doesn’t vouch for:
vect runs
echo "not-a-token" > ~/bad.token
vect runs --token-file ~/bad.tokenvect: unauthenticated: authentication failed: the request carries no bearer token
vect: unauthenticated: authentication failed: authenticator oidc/sso rejected the credentials: the issuer's keys are unavailableBoth exit 1. The second message is what you see while the issuer can’t be reached; with a reachable issuer it names the reason the token failed instead. Neither ever quotes the token.
With a valid token for bob@example.com, who only matches the read rule:
export VECT_TOKEN_FILE=$HOME/bob.token
vect runs
vect applyRUN KIND STATE SCOPE STARTED FINISHED METADATA
01a1e7da-76e6-7874-a322-3fe603e8070d plan succeeded full 2026-11-17T04:53:36Z 2026-11-17T04:53:36Z -
01a1e7da-6b51-758d-82f8-057ae6ee96e4 apply succeeded full 2026-11-17T04:53:33Z 2026-11-17T04:53:35Z -
vect: permission_denied: permission denied: bundle.upload on "*"The runs from steps 1 and 3 are there because CLI-direct and the server share .vect/data. Bob can read and can’t start a run.
run.apply, inventory.read, approval.approve:*, …) and workspace, checked on the server for each call, and the person who starts an apply need not be able to approve its destroys.5. Let loops start the applies
The loop block at the end of shared.server.vect makes the server start runs on its own:
loop "dev" "all" {
scopes = ["stack.app"]
lineage = "howto@main"
full_run_every = "24h"
}CI triggers it by publishing a bundle on the loop’s lineage. As the ci@example.com principal:
export VECT_TOKEN_FILE=$HOME/ci.token
vect bundle --lineage howto@main --source-position 1source digest: sha256:fad3b451ef8d738b9d480fb3f683175814e434ed3aa72a3ac272a943d751be0c
bundle digest: sha256:0e69c6da08096c41c31c27ce7165252114fab92ebda90bdabeca016a01d36264
publication: pub_000004A moment later the loop has seen the publication and started a run:
vect runsRUN KIND STATE SCOPE STARTED FINISHED METADATA
01a1e7da-7c00-79df-bb02-ae5eda2270b5 apply succeeded 1 target 2026-11-17T04:53:37Z 2026-11-17T04:53:37Z -
01a1e7da-76e6-7874-a322-3fe603e8070d plan succeeded full 2026-11-17T04:53:36Z 2026-11-17T04:53:36Z -
01a1e7da-6b51-758d-82f8-057ae6ee96e4 apply succeeded full 2026-11-17T04:53:33Z 2026-11-17T04:53:35Z -Nobody ran vect apply; the loop saw the publication and applied it. Edit the note in stacks/app/main.hcl (the default of text), publish again with --source-position 2, and the next run shows the change:
vect bundle --lineage howto@main --source-position 2 >/dev/nullvect runsRUN KIND STATE SCOPE STARTED FINISHED METADATA
01a1e7da-8192-7ee4-b582-39985d13b6b2 apply succeeded 1 target 2026-11-17T04:53:39Z 2026-11-17T04:53:39Z -
01a1e7da-7c00-79df-bb02-ae5eda2270b5 apply succeeded 1 target 2026-11-17T04:53:37Z 2026-11-17T04:53:37Z -
01a1e7da-76e6-7874-a322-3fe603e8070d plan succeeded full 2026-11-17T04:53:36Z 2026-11-17T04:53:36Z -
01a1e7da-6b51-758d-82f8-057ae6ee96e4 apply succeeded full 2026-11-17T04:53:33Z 2026-11-17T04:53:35Z -vect runs 01a1e7da-8192-7ee4-b582-39985d13b6b2run 01a1e7da-8192-7ee4-b582-39985d13b6b2: apply of workspace "dev": succeeded
scope: 1 target
…
stack.app.terraform.note applied will updateThe source position orders publications: a bundle older than what the loop has accepted is recorded as superseded and never runs. In CI, use the commit’s position in the branch.
To watch what’s happening, vect runs lists runs and vect logs --run <run-id> prints or tails one. vect runs blocked lists which changes block which others. The CAUSE column is one of failure, queued, approval, or version_lock:
vect runs blockedBLOCKER BLOCKED CAUSE NODE SINCE ENDEDAn empty table means nothing is blocked; add --all to include relations that have ended, or --change <id> for one change record. All of these need inventory.read.
6. Stop and restart safely
Stop the server with Ctrl-C or SIGTERM. Its workers get up to drain_timeout to let running activities finish, and it exits 0. Runs and loops live in Temporal and the stores, not in the process, so:
vect runsvect: unavailable: dial tcp 127.0.0.1:8443: connect: connection refusedwhile it is down (exit 1), and after VECT_CONFIG=shared.server.vect vect serve again, vect serve prints vect: serving on … and vect runs lists the same runs as before. Only one runner holds a loop’s lease, so don’t start two servers on the same scope.
Things to know
bundle.upload on "*"for a caller you thought was allowed. A bundle isn’t tied to a workspace, sobundle.uploadis authorized against an empty workspace name (API-AUTHZ-7). The"*"in the message is the policy target, not the workspace. A rule that grants it must useworkspaces = ["*"], which matches the empty name;["dev"]does not.- Loops reject destructive approvals by default. A loop’s runs have no one to ask, so with the default
unattended_approvals = "reject"a change that would destroy or replace something is rejected instead of applied. See How runs work. workspace.read_outputsandinventory.readare separate.vect outputneeds the first;runs,logs,inventory, andruns blockedneed the second.- Approvals on a server wait for someone with
approval.approve:<kind>. The reader’s side of that is in How runs work. Answering a run’s requests (--run) has a known limitation: issue #92. fleet_viewsandworkspace.serve = falseloops are accepted by the loader and have no effect in this version.
See also
- Server configuration reference: every block used here (
server,authenticator,policy,loop). - Command-line reference:
serve, the server flags, and exit codes. - How runs work and How change flows.
- API and CLI spec for the authentication and authorization requirements (
API-AUTHN-*,API-AUTHZ-*).