Operator guide for Valet Dedicated 0.10.1

Prepare

Gather what the installation needs before you install it. This page ends with the valet-dedicated tool on your machine and verified.

What you need

ItemWhat you need
AWS accountOne account for the installation, in a region with Fargate, RDS for PostgreSQL 17, EFS, and ACM
Release accessValet's grant to the account
VPCAn existing VPC that meets the requirements below
DNSAn apex domain with a public Route 53 hosted zone in the account
Sign-inYour identity provider, such as Okta, and a WorkOS administrator
AnthropicAn Anthropic API key
ToolsTerraform 1.11 or later, the AWS CLI v2, openssl, jq, and sha256sum (Linux) or shasum (macOS)

1. Send Valet your account ID

Send Valet the 12-digit ID of the installation account. Valet grants the account read access to the release bucket.

You see the grant work when the download in step 6 succeeds. Until then the download fails with an access error.

2. Prepare the VPC

The installation runs in a VPC you already have. The VPC needs:

  • Private subnets in at least two availability zones.
  • Outbound internet access from those subnets, such as a NAT gateway. The platform calls Anthropic, WorkOS, and the integrations you enable. See the outbound endpoints and the service quotas to check first.
  • DNS resolution and DNS hostnames turned on.
  • CIDRs inside 10.0.0.0/8, 172.16.0.0/12, and 192.168.0.0/16. The module refuses a VPC with a CIDR outside them and names the CIDRs it found.

Note the VPC ID and the private subnet IDs. The install passes them to the module as vpc_id and private_subnet_ids.

If another account owns the VPC and shares the subnets with the installation account through AWS RAM:

  1. Turn on sharing with AWS Organizations in the organization's management account (aws ram enable-sharing-with-aws-organization). Without it, RAM refuses to share a subnet.
  2. Share the private subnets with the installation account.
  3. Set vpc_owner_account_id to the owner's 12-digit account ID.

Route 53 does not let the installation account create a private zone on a VPC it does not own. So the module creates its two private zones, the apex and the service discovery namespace, on a small empty VPC of its own, named <name>-zone-anchor. It authorizes the shared VPC for both and prints private_zone_association_command as an output: two commands, one per line. Ask the VPC owner to run both with credentials for their account, after the apply and before valet-dedicated upgrade. The installation's names resolve inside the VPC only after both succeed. Keep the anchor VPC: a private zone always needs one VPC.

Optionally, name separate private subnets for agent runtimes and builders with workload_subnet_ids. They also need two zones and outbound access.

3. Create the DNS zone

Pick an apex, such as valet.example.com. The API is api.<apex>, the dashboard is dashboard.<apex>, and sites and apps live under *.<apex>.

  1. Create a public hosted zone for the apex in the installation account.
  2. Delegate the zone from the parent domain with NS records that hold the name servers Route 53 assigned.

AWS Certificate Manager validates the installation's certificates through this zone. Validation does not finish until the delegation works.

By default the module finds the zone by the apex. If you create the zone in the same Terraform run, pass public_zone_id and set public_zone_lookup to false. Both are in the reference.

The module also creates a private zone for the apex, attached to the VPC. It answers api., dashboard., gateway., and the wildcard.

4. Set up sign-in

People sign in through your identity provider, by way of WorkOS. Valet creates the installation's WorkOS environment and configures it. You connect your identity provider to it.

  1. Send Valet:

    • your apex;
    • the email domains your people sign in with; and
    • the name and email of your WorkOS administrator.
  2. Valet sends you:

    • an Admin Portal link;
    • the environment's client ID; and
    • its AuthKit domain.

    Valet also invites your WorkOS administrator to the environment.

  3. Open the Admin Portal link as your identity provider's administrator. Follow its steps to connect your identity provider. The link expires soon after Valet creates it. Ask Valet for a new one if it has.

  4. In the Admin Portal, verify each email domain with the DNS TXT record the portal gives you.

  5. Your WorkOS administrator signs in to the WorkOS dashboard and creates an API key for the environment.

Only people your identity provider admits can sign in. Password, magic link, and social sign-in are off.

How WorkOS works explains who runs each part.

Valet creates and administers the installation's WorkOS environment. The installation refuses impersonated sessions, so no one at Valet can sign in as one of your people. valet-dedicated check reports "impersonation is off" when the running dashboard enforces this.

The install passes the client ID and AuthKit domain to the module as the workos input. The first upgrade takes the API key from VALET_DEDICATED_WORKOS_API_KEY or a prompt and stores it in Secrets Manager. The module never holds the key, and Valet never sees it.

5. Get an Anthropic API key

Agents call Anthropic's models with this key. Have it ready. The first upgrade takes it from VALET_DEDICATED_ANTHROPIC_API_KEY or a prompt and stores it as the setting inference.anthropic_api_key.

6. Download valet-dedicated

You download the tool once, from the release bucket. Later versions come with valet-dedicated releases fetch. Use the AWS credentials of the installation account. The bucket is in us-east-1.

First obtain release-signing-public-key.pem from Valet through your agreed onboarding channel. Confirm the key with your Valet contact. Keep it outside the download directory. Do not take the trust key from the release bucket.

  1. Set the variables. Replace <release> with the version Valet told you to install. Set OS to darwin or linux, and ARCH to arm64 or amd64, to match your machine. Keep this shell open: Install uses VERSION too.

    VERSION=<release>
    OS=darwin
    ARCH=arm64
    FILE=valet-dedicated-$OS-$ARCH.tar.gz
    BUCKET=s3://valet-dedicated-releases/releases/$VERSION
  2. Download the manifest, its signature, and the tool.

    aws s3 cp $BUCKET/manifest.json . --region us-east-1
    aws s3 cp $BUCKET/manifest.json.sig . --region us-east-1
    aws s3 cp $BUCKET/$FILE . --region us-east-1
  3. Verify the manifest with the public key you obtained from Valet.

    openssl dgst -sha256 -verify /trusted/path/release-signing-public-key.pem \
      -signature manifest.json.sig manifest.json

    Continue only when it prints Verified OK and exits successfully. A missing or invalid signature stops installation. Download again; if it fails again, contact support@valet.dev. Do not unpack or run the tool.

  4. Read the SHA-256 the authenticated manifest records for the file.

    jq -r --arg f "$FILE" '.files[$f].sha256' manifest.json
  5. Compute the SHA-256 of what you downloaded.

    On Linux:

    sha256sum $FILE

    On macOS:

    shasum -a 256 $FILE
  6. Compare the two values. They must match. If they differ, delete the download and start again.

  7. Unpack the tool and make it runnable.

    tar -xzf $FILE valet-dedicated
    chmod +x valet-dedicated
  8. Print the version.

    ./valet-dedicated --version

You see valet-dedicated and the version. Put the file on your PATH, or call it by its path.

7. Create the Terraform role

Terraform needs an AWS role that can create and destroy the installation. The release ships the least-privilege policies for it, in the module's iam/ directory. Install fetches the module in its first step, so create the role then, before you run terraform apply. The role needs no administrator access.

  1. Fetch the release as Install shows. The policies are in vendor/valet-dedicated/iam/.

  2. Replace the placeholder INSTALLATION with the name you give the module, and ACCOUNT with the installation account's ID. Use the same name in the root.

    NAME=valet ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
    sed -e "s/INSTALLATION/$NAME/g" -e "s/ACCOUNT/$ACCOUNT/g" \
      vendor/valet-dedicated/iam/terraform-policy.json > policy-1.json
    sed -e "s/INSTALLATION/$NAME/g" -e "s/ACCOUNT/$ACCOUNT/g" \
      vendor/valet-dedicated/iam/terraform-policy-data.json > policy-2.json
  3. Create the two policies, and a role that trusts the identity that runs Terraform. Attach both policies to the role. One policy exceeds IAM's size limit, so there are two.

    aws iam create-policy --policy-name "$NAME-terraform-1" --policy-document file://policy-1.json
    aws iam create-policy --policy-name "$NAME-terraform-2" --policy-document file://policy-2.json
    aws iam create-role --role-name "$NAME-terraform" --assume-role-policy-document file://trust.json
    aws iam attach-role-policy --role-name "$NAME-terraform" --policy-arn arn:aws:iam::<account>:policy/$NAME-terraform-1
    aws iam attach-role-policy --role-name "$NAME-terraform" --policy-arn arn:aws:iam::<account>:policy/$NAME-terraform-2

    trust.json is a trust policy that names the user or role that runs Terraform.

  4. Run terraform apply and terraform destroy as that role. Set it in the AWS provider with assume_role, or use its credentials.

Add the permissions your Terraform state backend needs to the role. The module's iam/README.md lists what the policies leave out and why some statements name every resource of a kind.

8. Check your work

valet-dedicated check reads the installation's descriptor, so it runs only after the install. It cannot test an account before then. Verify these by hand instead:

  1. aws sts get-caller-identity names the installation account.
  2. aws ec2 describe-subnets --subnet-ids <ids> lists your private subnets in two or more zones.
  3. dig NS <apex> returns the Route 53 name servers.
  4. terraform version prints 1.11 or later.

Install runs check once the services are up.