Skip to content
Run a server

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.

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

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

A default you can swap: 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.

shared.server.vect
# 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" }
  }
}
EOF

The engine’s own lines are left out of the outputs below.

VECT_CONFIG=deny.server.vect vect apply
VECT_CONFIG=deny.server.vect vect plan
vect: 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 unchanged

The 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 serve
vect: serving on 127.0.0.1:8443

The 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:8443

The 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.token
vect: unauthenticated: authentication failed: the request carries no bearer token
vect: unauthenticated: authentication failed: authenticator oidc/sso rejected the credentials: the issuer's keys are unavailable

Both 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 apply
RUN                                   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.

Coming from Terraform: there is no shared state backend to grant bucket access to. Access is by action (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:

shared.server.vect
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 1
source digest: sha256:fad3b451ef8d738b9d480fb3f683175814e434ed3aa72a3ac272a943d751be0c
bundle digest: sha256:0e69c6da08096c41c31c27ce7165252114fab92ebda90bdabeca016a01d36264
publication: pub_000004

A moment later the loop has seen the publication and started a run:

vect runs
RUN                                   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/null
vect runs
RUN                                   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-39985d13b6b2
run 01a1e7da-8192-7ee4-b582-39985d13b6b2: apply of workspace "dev": succeeded
scope: 1 target
…
  stack.app.terraform.note  applied  will update

The 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 blocked
BLOCKER  BLOCKED  CAUSE  NODE  SINCE  ENDED

An 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 runs
vect: unavailable: dial tcp 127.0.0.1:8443: connect: connection refused

while 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, so bundle.upload is 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 use workspaces = ["*"], 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_outputs and inventory.read are separate. vect output needs the first; runs, logs, inventory, and runs blocked need 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_views and workspace.serve = false loops are accepted by the loader and have no effect in this version.

See also