Operator guide for Valet Dedicated 0.10.1

Install

Install builds the infrastructure with Terraform, then deploys the release with valet-dedicated. Finish Prepare first.

1. Fetch the release

Every command on this page uses VERSION, the release you install, which you set in Prepare. In a new shell, set it again:

VERSION=<release>

Fetch the module and the tool for your release into a directory that does not exist yet.

./valet-dedicated releases fetch "$VERSION" --dir vendor/valet-dedicated

You see the version, the module path with the source to use, and the binary path. The module lands in vendor/valet-dedicated. The binary lands beside it as vendor/valet-dedicated-<release>. Fetch verifies both against the manifest and writes nothing if a check fails.

Use that binary from here on, so the tool and the module match:

export VD=./vendor/valet-dedicated-$VERSION

2. Write the root

Create a Terraform root next to vendor/. The module takes two AWS providers, one for the platform and one for agent workloads. They must reach the same account. Pass the same provider twice.

terraform {
  required_version = ">= 1.11"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 6.0"
    }
    random = {
      source  = "hashicorp/random"
      version = "~> 3.7"
    }
  }
}

provider "aws" {
  region = "us-east-2"
}

provider "aws" {
  alias  = "workloads"
  region = "us-east-2"
}

module "valet" {
  source = "./vendor/valet-dedicated"

  providers = {
    aws           = aws
    aws.workloads = aws.workloads
  }

  name               = "valet"
  home_org           = "mycompany"
  vpc_id             = "vpc-0a1b2c3d4e5f67890"
  private_subnet_ids = ["subnet-0aaa", "subnet-0bbb"]
  apex               = "valet.mycompany.com"
  workos = {
    client_id      = "client_01ABC"
    authkit_domain = "example.authkit.app"
  }
}

Replace each value. Keep Terraform's state in a bucket you own. The module repository's examples/single-state shows a backend block.

Two inputs need care:

  • name prefixes every resource, so it must be unique in the account.
  • home_org names the org that everyone joins at first sign-in. For the apex valet.mycompany.com, use mycompany. Set it once. Changing it later makes the next sign-in create a new, empty org.

The reference lists every input.

3. Apply the module

  1. Initialize Terraform.

    terraform init
  2. Read the plan.

    terraform plan
  3. Apply it.

    terraform apply

The apply creates the database, buckets, secrets, clusters, load balancer, certificate, DNS, and the deployment role. It takes a while, mostly for the database and the certificate.

You see the outputs api_url, dashboard_url, descriptor_parameter, deployment_role_arn, and private_zone_id. No service runs yet.

The module writes the database password. It writes no other secret value.

4. Reach the installation

The platform's hosts are served on an internal load balancer inside your VPC. upgrade, check, status, settings, users, and orgs call the API host, and so does the dashboard. Run the commands from a machine with network access to the VPC, such as a host in the VPC or a machine on your VPN. Open the dashboard from such a machine too.

Names under the apex resolve through the private zone. A machine outside the VPC resolves them only if its resolver forwards the apex to the VPC resolver. A Route 53 Resolver inbound endpoint and a forwarding rule do that. The module does not create them.

The tool also calls AWS directly. It needs your AWS credentials, and it reads the installation in the account and region they name.

5. Run the first upgrade

upgrade deploys the release. It fills the empty secrets, copies the images into your account, migrates the database, starts the services, and waits until they answer. Use the release's version as the tag.

$VD upgrade "$VERSION"

upgrade uses direct Anthropic by default and needs two keys before copying an image:

  1. The WorkOS API key, from VALET_DEDICATED_WORKOS_API_KEY.
  2. The Anthropic API key, from VALET_DEDICATED_ANTHROPIC_API_KEY.

Set both variables, or run upgrade on a terminal. It asks for each key that the variables leave out, without echoing it. The direct Anthropic route requires its key, so on a first install upgrade stops before it copies an image when it has no key. With --yes, or without a terminal, it does not prompt.

export VALET_DEDICATED_WORKOS_API_KEY=...
export VALET_DEDICATED_ANTHROPIC_API_KEY=...
$VD upgrade "$VERSION"

upgrade stores the Anthropic key as the setting inference.anthropic_api_key. Later upgrades do not ask for it again.

To offer OpenAI models too, also export VALET_DEDICATED_OPENAI_API_KEY. It is optional, and upgrade never asks for it. You can set it later with settings set inference.openai_api_key.

You see one status line per step. At the end it prints the key of a deployment record, which it also wrote to the records bucket.

A rerun at the same tag changes nothing. If upgrade fails, fix the cause and run it again.

Use Amazon Bedrock

Bedrock is available from release 0.9.0. Complete these steps before the first upgrade:

  1. Open Amazon Bedrock in your AWS account and the installation's region. Open the model catalog and enable the Anthropic models you will use. Complete Anthropic's first-use form and any Marketplace subscription the console requires. Verify access to Sonnet 4.5 and Haiku 4.5 too; Valet uses them for merge, analysis, naming, and design-system calls.
  2. Find each model's global inference profile in the Bedrock console. Copy its profile ARN and every destination foundation-model ARN into bedrock_model_arns. Include region-less foundation-model ARNs for global profiles. Use exact ARNs, with no wildcards. The reference explains the grant.
  3. Set bedrock_vpc_endpoint = true if calls should enter Bedrock through an interface endpoint in the installation's private subnets.
  4. Apply the module with your existing Terraform workflow.
  5. Supply the WorkOS key and select Bedrock for the first upgrade:
export VALET_DEDICATED_WORKOS_API_KEY=...
$VD upgrade "$VERSION" --bedrock

--bedrock writes inference.anthropic_provider = bedrock to settings_bootstrap. It does not ask for an Anthropic key. The API, worker, and inference tasks sign calls with their own task roles. Later upgrades retain the selection without the flag. A stored provider setting wins over bootstrap; use settings set to change a running installation's provider.

Global profiles can process requests outside the installation's region. The endpoint keeps the connection private; it does not constrain the profile's destination regions. Confirm those regions meet your requirements. See Amazon Bedrock for region selection, switching providers, and feature differences.

Back up the key ring

The encryption_keys secret encrypts every credential Valet stores. If you lose it, you lose those credentials, and Valet cannot recover it. Terraform and AWS Backup do not copy it. After the first upgrade fills it, copy it to a store you control. Replace <name> with your installation name.

aws secretsmanager get-secret-value \
  --secret-id <name>/encryption_keys \
  --query SecretString --output text

Put the output straight into your own secret store or vault. Do not write it to a file in your working directory. Protect the copy like a root credential: limit who can read it, and log each read.

6. Check the installation

$VD check --wait 15m

check prints a check mark or a cross for each item, with the fix for each cross. With --wait, it reruns every 15 seconds until every item passes or the time ends. It exits 1 when any item fails.

You see a check mark on every line. Fix each cross and run check again.

7. Sign in

  1. Open https://dashboard.<apex> from a machine that reaches the VPC.
  2. Sign in through WorkOS.

The first person to sign in creates the home org and becomes its Admin. Everyone after joins it as a Developer. The home organization starts with a secrets policy blocking findings at high or above; Admins change or remove it with valet policies.

8. Become superuser

The superuser role administers the platform. Sign in once, then grant yourself the role with the operator tool:

$VD users set-role you@mycompany.com superuser --reason "installer"

The operator token authorizes this, so it needs no signed-in superuser. The person must have signed in once. The command refuses a change that would leave the installation with no superuser.

Next

  1. Connect your people.
  2. Read Limits and known gaps.
  3. Read Upgrade before the next release.