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
| Item | What you need |
|---|---|
| AWS account | One account for the installation, in a region with Fargate, RDS for PostgreSQL 17, EFS, and ACM |
| Release access | Valet's grant to the account |
| VPC | An existing VPC that meets the requirements below |
| DNS | An apex domain with a public Route 53 hosted zone in the account |
| Sign-in | Your identity provider, such as Okta, and a WorkOS administrator |
| Anthropic | An Anthropic API key |
| Tools | Terraform 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, and192.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:
- 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. - Share the private subnets with the installation account.
- Set
vpc_owner_account_idto 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>.
- Create a public hosted zone for the apex in the installation account.
- 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.
Send Valet:
- your apex;
- the email domains your people sign in with; and
- the name and email of your WorkOS administrator.
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.
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.
In the Admin Portal, verify each email domain with the DNS TXT record the portal gives you.
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.
Set the variables. Replace
<release>with the version Valet told you to install. SetOStodarwinorlinux, andARCHtoarm64oramd64, to match your machine. Keep this shell open: Install usesVERSIONtoo.VERSION=<release> OS=darwin ARCH=arm64 FILE=valet-dedicated-$OS-$ARCH.tar.gz BUCKET=s3://valet-dedicated-releases/releases/$VERSIONDownload 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-1Verify 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.jsonContinue only when it prints
Verified OKand 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.Read the SHA-256 the authenticated manifest records for the file.
jq -r --arg f "$FILE" '.files[$f].sha256' manifest.jsonCompute the SHA-256 of what you downloaded.
On Linux:
sha256sum $FILEOn macOS:
shasum -a 256 $FILECompare the two values. They must match. If they differ, delete the download and start again.
Unpack the tool and make it runnable.
tar -xzf $FILE valet-dedicated chmod +x valet-dedicatedPrint 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.
Fetch the release as Install shows. The policies are in
vendor/valet-dedicated/iam/.Replace the placeholder
INSTALLATIONwith thenameyou give the module, andACCOUNTwith 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.jsonCreate 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-2trust.jsonis a trust policy that names the user or role that runs Terraform.Run
terraform applyandterraform destroyas that role. Set it in the AWS provider withassume_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:
aws sts get-caller-identitynames the installation account.aws ec2 describe-subnets --subnet-ids <ids>lists your private subnets in two or more zones.dig NS <apex>returns the Route 53 name servers.terraform versionprints 1.11 or later.
Install runs check once the services are up.