Writing your first vect project, part 3
In this part we run what we built. We write a small server configuration, start a local Temporal server, and then plan, apply, and read back what happened. We pick up in the vect-tutorial folder from Part 2.
Where to get help: open an issue on the issue tracker.
Run every command from inside vect-tutorial.
Two things you haven’t met yet
Temporal is a workflow engine. When you run vect plan or vect apply, vect starts a Temporal workflow for the run, and each node in the graph becomes an activity in it. That gives you durable, observable runs: a run that is interrupted can be picked up again, and every run is recorded. You don’t write any Temporal code. You only need a Temporal server for vect to talk to, and for learning that’s one command.
Inventory is vect’s record of what it has applied. For every executor it keeps a versioned record, and for every successful run a deployment pointer that says which configuration was applied. Where you’d use terraform state list to see what a root manages, you use vect inventory to see what vect manages across all of your roots. It lives in .vect/data inside the project, which vect creates the first time it needs it.
Start a Temporal server
In a separate terminal, start the Temporal development server and leave it running:
temporal server start-devIt listens on localhost:7233, which is what we’ll point vect at. The rest of this tutorial uses your first terminal. (If you don’t have the temporal command, see Installation.)
Write a server configuration
vect needs to know which Temporal server to use and where to keep its data. That goes in a server configuration file. Create server.vect next to main.hcl:
server {
name = "tutorial"
default_workspace = "dev"
}
defaults {
opentofu_version = "1.10.6"
}
workspace "dev" {
account = "tutorial"
temporal {
endpoint = "localhost:7233"
namespace = "default"
}
key_provider "local_file" {
path = ".vect/keys/dev.key"
}
execution {
default_task_queue = "vect"
}
}Here is what each part does:
servernames this runner, anddefault_workspacesays which workspace commands act on when you don’t pass--workspace.defaults.opentofu_versionis the OpenTofu version vect uses for roots that don’t pin one withrequired_version. vect downloads that exact engine itself, so you don’t install it.workspace "dev"is the target we run in. A workspace is a named place with its own Temporal namespace, keys, and stores.accountis a label vect uses when naming stores; any string works for local use.temporalpoints at the development server: itsendpointandnamespace.key_provider "local_file"is where vect keeps the key that encrypts the values it stores. For local use it’s a file; it is created on first use.execution.default_task_queueis the Temporal task queue the work is scheduled on. A run in the same process picks it up, so any name will do.
temporal at the local dev server, but any Temporal service works. Set endpoint and namespace to your own (for example temporal.internal:7233 and vect-prod); both are required. Likewise key_provider "local_file" is the local-use choice. For anything shared, use key_provider "aws_kms" with a key_id instead. The key part is covered in The value store, and keys. See also workspace and key_provider in the server configuration reference.We left out the stores blocks on purpose. Without them, every store (state, Inventory, values, and so on) is a set of files under .vect/data in the current folder, which is exactly what you want for learning.
A default you can swap: storage here is local files, the default for every store. State, Inventory, values, and the content-addressed store each use the afero backend under <data_dir>/<workspace>, and data_dir defaults to .vect/data (set it in the server block). To move them to AWS, add a stores block to the workspace; state, values, and cas accept s3, and inventory accepts dynamodb:
workspace "dev" {
# ...
stores {
state {
backend = "s3"
name = "my-vect-state"
region = "us-east-1"
}
inventory {
backend = "dynamodb"
name = "my-vect-inventory"
region = "us-east-1"
}
}
}Any store you leave out stays local. vect needs a name (the bucket or table) for S3 and DynamoDB stores until automatic naming from a store_naming template lands. See Where things are stored and Store blocks.
server.vect, not server.hcl. vect loads every .hcl file in the folder as project configuration, so a server configuration named .hcl would be read as a project and rejected with an error such as "server" is not a vect block type. The .vect extension keeps the two apart. The syntax is still HCL.Now tell vect where the file is. It doesn’t search for it; commands read it from the --config flag or the VECT_CONFIG environment variable. Set the variable once for this terminal:
export VECT_CONFIG=server.vectThe path is relative, which is why you must run commands from inside vect-tutorial. If you open a new terminal, run the export again.
The project now looks like this:
vect-tutorial/
main.hcl
pet.facts.hcl
server.vect
roots/
greeting/
main.tf
pet/
main.tf
stacks/
greeting/
main.hcl
pet/
main.hclCheck that the project is still valid. The server configuration isn’t part of it:
vect validateSuccess!
(root) 0 blocks
stack.greeting 1 block
stack.pet 1 blockvect plan and vect apply here run CLI-direct: the command starts an in-process runner that does the work against the Temporal server and then exits. The same server.vect can instead be served by a long-running vect serve (which needs server.listen), and the CLI can then talk to it with --api-url. The commands you type don’t change. See CLI-direct and served runs and vect serve.Plan
vect planstack.pet.terraform.pet: running
stack.pet.terraform.pet: planned will run
stack.greeting.terraform.greeting: running
stack.greeting.terraform.greeting: deferred unknown inputs: inputs.name
stack.pet.terraform.pet |
stack.pet.terraform.pet | Initializing the backend...
stack.pet.terraform.pet |
stack.pet.terraform.pet | Successfully configured the backend "local"! OpenTofu will automatically
stack.pet.terraform.pet | use this backend unless the backend configuration changes.
stack.pet.terraform.pet |
stack.pet.terraform.pet | Initializing provider plugins...
stack.pet.terraform.pet | - Reusing previous version of hashicorp/random from the dependency lock file
stack.pet.terraform.pet | - Installing hashicorp/random v3.9.1...
stack.pet.terraform.pet | - Installed hashicorp/random v3.9.1 (unauthenticated)
stack.pet.terraform.pet |
stack.pet.terraform.pet | OpenTofu has been successfully initialized!
stack.pet.terraform.pet |
stack.pet.terraform.pet | OpenTofu used the selected providers to generate the following execution
stack.pet.terraform.pet | plan. Resource actions are indicated with the following symbols:
stack.pet.terraform.pet | + create
stack.pet.terraform.pet |
stack.pet.terraform.pet | OpenTofu will perform the following actions:
stack.pet.terraform.pet |
stack.pet.terraform.pet | # random_pet.this will be created
stack.pet.terraform.pet | + resource "random_pet" "this" {
stack.pet.terraform.pet | + id = (known after apply)
stack.pet.terraform.pet | + length = 2
stack.pet.terraform.pet | + separator = "-"
stack.pet.terraform.pet | }
stack.pet.terraform.pet |
stack.pet.terraform.pet | Plan: 1 to add, 0 to change, 0 to destroy.
stack.pet.terraform.pet |
stack.pet.terraform.pet | Changes to Outputs:
stack.pet.terraform.pet | + name = (known after apply)
plan of workspace "dev": succeeded (run 01a1e76b-fa5d-7334-b81b-c4392bb2c8b5)
stack.greeting.terraform.greeting defer unknown inputs: inputs.name
stack.pet.terraform.pet run will runThe first run takes longer: vect downloads OpenTofu and the random provider once, keeps the verified downloads under .vect/data/downloads for later bundles, and unpacks them under .vect/data/cache. Your output will differ in the run ID, and your versions may differ.
Nodes run concurrently, and vect’s status lines and the engine’s lines are written to different streams, so the order of lines on your screen may differ slightly from what’s shown here (and in later parts). The content is what matters.
Read it from the top. Lines that start with a node address and | are the engine’s own output, passed through, so you see what plain OpenTofu would have printed. The other lines are vect’s:
petwas planned andwill run: it has a resource to create.greetingwas deferred, with the reasonunknown inputs: inputs.name. Itsnameinput is the pet’s name, which doesn’t exist untilpetis applied, so vect can’t plan it yet. It will plan it during the apply, once the input is known.- The summary at the end is one line per node, and the run ID.
planchanges nothing.
pet is exactly what tofu plan would print in roots/pet. What’s new is that one command plans every root, and a root that depends on an unapplied one is deferred instead of failing. That’s the problem terraform_remote_state and hand-ordered pipelines solve badly: the second root can’t be planned until the first is applied, and vect knows that.Apply
vect applystack.pet.terraform.pet: running
stack.pet.terraform.pet: applied will run
stack.greeting.terraform.greeting: running
stack.greeting.terraform.greeting: applied will run
apply of workspace "dev": succeeded (run 01a1e76c-0749-7e4c-b7c7-dcc1e51e97ab)
stack.greeting.terraform.greeting applied (run) will run
stack.pet.terraform.pet applied (run) will run
deployment pointer 1 appended(From here on we leave out the engine’s own lines. You’ll see them all in your terminal.) Both nodes were applied, pet first and then greeting. The last line records a deployment pointer: the first entry in Inventory’s history of what’s been applied.
This apply didn’t ask for anything. vect asks for your approval only for changes that destroy or move something, and we only created things. You will see the prompt shortly.
Look at what happened
List the runs:
vect runsRUN KIND STATE SCOPE STARTED FINISHED METADATA
01a1e76c-0749-7e4c-b7c7-dcc1e51e97ab apply succeeded full 2026-11-17T02:52:59Z 2026-11-17T02:53:00Z -
01a1e76b-fa5d-7334-b81b-c4392bb2c8b5 plan succeeded full 2026-11-17T02:52:55Z 2026-11-17T02:52:58Z -The plan and the apply are separate runs. Times are UTC. Your run IDs will differ.
Print the logs of the apply, for one node. Pass the run ID from your own vect runs output:
vect logs --run 01a1e76c-0749-7e4c-b7c7-dcc1e51e97ab --node stack.greeting.terraform.greetingstack.greeting.terraform.greeting [plan #1] |
stack.greeting.terraform.greeting [plan #1] | Initializing the backend...
stack.greeting.terraform.greeting [plan #1] |
stack.greeting.terraform.greeting [plan #1] | Successfully configured the backend "local"! OpenTofu will automatically
stack.greeting.terraform.greeting [plan #1] | use this backend unless the backend configuration changes.
stack.greeting.terraform.greeting [plan #1] |
stack.greeting.terraform.greeting [plan #1] | Initializing provider plugins...
stack.greeting.terraform.greeting [plan #1] | - terraform.io/builtin/terraform is built in to OpenTofu
…That’s the engine’s output as recorded during the run, the plan first and then the apply, labelled with each step. We show the first eight lines of 46. Without --node you get every node.
Read the root outputs of the last applied deployment:
vect outputmessage = "Hello, huge-reindeer!"Your pet name will differ. This is the root output "message" from main.hcl, with the value that flowed from pet through to greeting.
See what vect manages:
vect inventoryADDRESS VERSION STATUS
stack.greeting.terraform.greeting 1 converged
stack.pet.terraform.pet 1 converged
POINTER BUNDLE SCOPE APPLIED METADATA
1 sha256:7b1dfbd51b5dd82a09547b02c7dd2a4ffb2afbedf01dcb1d786d9b6f5d16a6d0 full 2026-11-17T02:53:00ZEach executor instance has a record, now at version 1 and converged, and there is one deployment pointer, with a digest of the bundle that was applied.
A default you can swap: the bundle behind that digest is stored locally, under .vect/data/bundles. Bundles are shared by every workspace on the server, so their store is set once, in a bundles block inside server, not per workspace. It defaults to afero under <data_dir>/bundles (see The bundle store and server); for shared use, switch to S3:
server {
# ...
bundles {
backend = "s3"
name = "my-vect-bundles"
region = "us-east-1"
}
}Make a change that needs approval
Open roots/pet/main.tf and change the pet’s length from 2 to 3. A different length means a different resource, so the pet is replaced: destroyed and created again.
resource "random_pet" "this" {
length = 3
}Plan it:
vect planstack.pet.terraform.pet: running
stack.pet.terraform.pet: planned will update, destroying 1 resource (see approval requests)
stack.greeting.terraform.greeting: running
stack.greeting.terraform.greeting: deferred unknown inputs: inputs.name
plan of workspace "dev": succeeded (run 01a1e76c-0fd5-78a2-974e-fc07eb8eb7c1)
stack.greeting.terraform.greeting defer unknown inputs: inputs.name
stack.pet.terraform.pet update will update, destroying 1 resource (see approval requests)
approval requests:
apr_5c7f999480bbac6d13d7f878 destroy stack.pet.terraform.pet::random_pet.this destroy stack.pet.terraform.pet::random_pet.this(The engine’s lines say -/+ destroy and then create replacement.) The pet’s reason says will update, destroying 1 resource: the action is still update, but the plan destroys something along the way. The plan now ends with an approval requests: section. vect treats every destroy as something a human should look at, and a replacement contains a destroy. plan only lists the request; nothing waits.
Apply it. The apply stops at the prompt and waits for you:
vect applyAnswer y when it asks. Here is the run, with the engine’s lines left out:
stack.pet.terraform.pet: running
stack.pet.terraform.pet: awaiting_approval awaiting approval
approval request apr_5c7f999480bbac6d13d7f878 destroy stack.pet.terraform.pet::random_pet.this destroy stack.pet.terraform.pet::random_pet.this
approve destroy of stack.pet.terraform.pet::random_pet.this? [y/N] y
stack.pet.terraform.pet: running
stack.pet.terraform.pet: applied will update, destroying 1 resource (see approval requests)
stack.greeting.terraform.greeting: running
stack.greeting.terraform.greeting: applied will update
apply of workspace "dev": succeeded (run 01a1e1e8-4133-7436-aa31-1a36baeb3da2)
stack.greeting.terraform.greeting applied (update) will update
stack.pet.terraform.pet applied (update) will update, destroying 1 resource (see approval requests)
approval requests:
apr_5c7f999480bbac6d13d7f878 destroy stack.pet.terraform.pet::random_pet.this destroy stack.pet.terraform.pet::random_pet.this [approved by local]
deployment pointer 2 appendedThe approval is recorded with who gave it: approved by local. Check the new name:
vect outputmessage = "Hello, terminally-needed-worm!"Because greeting depends on pet, it was applied after the replacement and picked up the new name. You didn’t have to touch it.
Non-interactive shells and scripts
The prompt needs a terminal. In a script or CI job there’s no one to answer, so by default vect rejects the request and skips the node and everything that depends on it. To see it, put length back to 2 in roots/pet/main.tf, then run the apply with no terminal attached (here, by reading input from /dev/null):
vect apply < /dev/nullstack.pet.terraform.pet: running
stack.pet.terraform.pet: skipped approval rejected by unattended: destroy stack.pet.terraform.pet::random_pet.this
stack.greeting.terraform.greeting: skipped upstream stack.pet.terraform.pet skipped
apply of workspace "dev": failed (run 01a1e26b-4144-7f3a-88b1-ec273d5e88cd)
stack.greeting.terraform.greeting skipped upstream stack.pet.terraform.pet skipped
stack.pet.terraform.pet skipped approval rejected by unattended: destroy stack.pet.terraform.pet::random_pet.this
approval requests:
apr_d58adcabd68ece6b04f2138c destroy stack.pet.terraform.pet::random_pet.this destroy stack.pet.terraform.pet::random_pet.this [rejected by unattended]
node stack.pet.terraform.pet skipped: approval rejected by unattended: destroy stack.pet.terraform.pet::random_pet.this
deployment pointer 3 appendedThe pet and the greeting were skipped, the run is failed, and the exit status is 1. Nothing was destroyed. The message says why: approval rejected by unattended.
unattended_approvals on the workspace. Setting unattended_approvals = "approve" there makes terminal-less runs approve instead, which a shared server only allows to principals with the approval.auto_approve permission. See Approvals, workspace in the server configuration reference, and RUN-APPROVAL-9.For scripts that really should go ahead, pass --auto-approve:
vect apply --auto-approvestack.pet.terraform.pet: running
stack.pet.terraform.pet: applied will update, destroying 1 resource (see approval requests)
stack.greeting.terraform.greeting: running
stack.greeting.terraform.greeting: applied will update
apply of workspace "dev": succeeded (run 01a1e26b-562c-7027-ad1a-0b2b3bca34f5)
stack.greeting.terraform.greeting applied (update) will update
stack.pet.terraform.pet applied (update) will update, destroying 1 resource (see approval requests)
approval requests:
apr_d58adcabd68ece6b04f2138c destroy stack.pet.terraform.pet::random_pet.this destroy stack.pet.terraform.pet::random_pet.this [approved by auto-approve]
deployment pointer 4 appendedThe request is the same, and it’s recorded as approved by auto-approve. Use it deliberately. It approves every request in the run.
When something goes wrong
The Temporal server isn’t running. If you run a command while the dev server is stopped, you get an error like this:
vect: unavailable: dial Temporal for workspace "dev": failed reaching server: connection error: desc = "transport: Error while dialing: dial tcp …:7233: connect: connection refused" (after 4 attempts)The part to look for is dial tcp … :7233: connect: connection refused. The address before the port depends on your machine and may be 127.0.0.1 or [::1]. Start temporal server start-dev in another terminal and run the command again. vect tries the connection four times, a few seconds in all, before it gives up. Nothing was changed. If you stop the dev server to try this, start temporal server start-dev again before you continue; Part 4 assumes it’s running.
vect can’t find the server configuration. Run from the wrong folder, or in a new terminal where VECT_CONFIG isn’t set, and you’ll get one of these. From a folder without server.vect:
Error: Cannot read server configuration
open server.vect: no such file or directoryWith VECT_CONFIG unset:
vect: needs a workspace: use --workspace, VECT_WORKSPACE, or default_workspace (no server configuration was loaded, so default_workspace is not set: use --config or VECT_CONFIG)Go back into vect-tutorial and run export VECT_CONFIG=server.vect. You can also pass the file for one command with --config server.vect.
Your state carries over between parts. Parts 4 and 5 continue in this same vect-tutorial folder, and everything vect keeps is in .vect/data here, so what you applied in this part is still there. If you’d rather start over from an empty state at any point, run vect destroy, then:
rm -rf .vectWhat we’ve done
You wrote a server configuration, started Temporal, planned and applied two roots with one command each, read the runs, logs, outputs, and Inventory, answered an approval, and saw how scripts handle one. Part 4 adds shared values, data, and a secret.