Operator guide for Valet Dedicated 0.10.1

Reference

Every valet-dedicated command and every input of the Terraform module. Run valet-dedicated <command> --help for the tool's own text.

All commands take -h or --help. The root takes -v or --version. check, status, support bundle, upgrade, settings, users, orgs, and services use your AWS credentials and the installation's API. See check, status, support bundle, upgrade, settings, users, orgs, and oauth-clients use your AWS credentials and the installation's API. See Install.

Commands

valet-dedicated check

valet-dedicated check [--wait <duration>] [--output text|json]

Reads the installation's descriptor from Parameter Store in the account and region of your AWS credentials, assumes its deployment role, and prints one line per item: a check mark, or a cross with the fix.

FlagDescription
--wait <duration>Rerun every 15 seconds until every item passes or this long has passed, such as 15m. Prints the final result once.
--output text|jsonPrint lines (the default) or one JSON object.

The JSON object has this shape:

{
  "version": 1,
  "installation": "acme",
  "region": "us-east-2",
  "ok": false,
  "checks": [
    {"name": "service.api", "status": "pass", "message": "service api runs 1 on an upgrade revision"},
    {"name": "health.api", "status": "fail", "message": "GET https://api.example.com/health returned 503", "fix": "read the api service's logs, or run valet-dedicated upgrade <tag>"}
  ]
}

ok is true when every check passes. Each check has a stable name, a status of pass, warn, or fail, and a message. A failed check also has a fix. The names are dotted ids such as version, module, descriptor, role, secret.<name>, service.<name>, impersonation, certificates, certificates.quota (a warning), certificate.<org>, app_database (the app database is off), app_database.instance, api.identity, api.anthropic_key, api.openai_key, api.standby_pool, and health.<name>. A name never changes with the wording of its message. version changes only when a field is removed or changes meaning. Both formats use the same exit codes.

Exit codeMeaning
0Every item passed.
1An item failed.
2check could not run: a bad flag or argument, no usable AWS credentials, or an unreadable descriptor.

check warns when a newer release exists. An unreadable release index also produces a warning, so an offline installation can still pass. The index read uses the caller's release-bucket grant and has a five-second limit. It also warns, as certificates.quota, when 20 or more certificates are attached to the listener, five short of the default quota of 25. Ask AWS Support to raise the quota before you add orgs. Warnings do not change the exit code or make --wait retry.

valet-dedicated releases list

valet-dedicated releases list [--output text|json]

Reads releases/index.json with your AWS credentials. It needs GetObject, never permission to list the bucket. Text shows versions, publication dates, manifest digests, and manifest sizes, newest version first. JSON contains schema and releases; each release has version, published_at, and manifest with sha256 and size.

Exit 0 means success. Exit 1 means the index could not be read or printed. Exit 2 means invalid usage or unavailable AWS configuration or credentials.

valet-dedicated roll

valet-dedicated roll [--service <name> | --runtimes] [--yes] \
  [--batch-size 5] [--timeout 5m] [--output text|json]

Without --yes, prints the selection and changes nothing. The default selects every platform service. --service selects one descriptor service, such as api. A platform roll forces a new ECS deployment at its current task definition and count. It waits for the new deployments to complete, then checks API and dashboard health.

--runtimes selects running processes with runtime images and target state up. It replaces them through the operator API in batches of five. Replacements use the configured runtime image and keep the active release. --batch-size changes that limit; --timeout bounds each batch. Each process must return up with a different container before the next batch starts. Before restarting, it skips and reports processes that stopped, idled, lost their container, or gained a state reason. Skips appear in text and JSON and do not count as completed replacements. An error or timeout stops the roll. Idle processes stay idle.

An acting roll holds the same installation lock as upgrade. JSON contains plan, services, processes, skipped, completed, and an optional error. skipped contains each process's observed state before restart. completed names settled services or processes from completed batches. Exit 0 means success, 1 means an operation failed, and 2 means invalid usage or an installation the command could not open.

valet-dedicated audit list

valet-dedicated audit list [--since 24h] [--until <RFC3339>] \
  [--actor <email-or-id>] [--permission <permission>] \
  [--outcome allow|deny|would_deny|error] [--org <name>] \
  [--limit 100] [--page-token <token>] [--output text|json]

Reads stored events across the installation with the operator token. Without --org, results include events without an org. An ordinary platform operator's signed-in account cannot read this record; a superuser's account can. Org Admins read their own org in Team → Audit log in the dashboard.

--since is inclusive and accepts a positive duration ago or an RFC 3339 timestamp. --until is exclusive and accepts RFC 3339. Actor email or ID, permission, and outcome match exactly. Results are newest first; --limit is 1–1000 and defaults to 100. Reading writes no audit row.

Text displays time, actor, org ID, permission, target, and outcome. JSON emits one object per line with version: 1 and the stored columns: id, occurred_at, actor_kind, actor_id, actor_email, actor_arn, org_id, permission, target_kind, target_id, outcome, reason, source_ip, request_id, procedure, and detail. Unknown values remain null; detail is a JSON value. Timestamps use UTC RFC 3339.

When more events remain, text mode prints the next command hint to stderr. JSON mode appends a final {"next_page_token":"..."} line without event fields. Pass that token with --page-token and keep the filters unchanged. Use absolute RFC 3339 bounds when paging; a duration such as --since 24h resolves to a different timestamp on each invocation.

Exit 0 means success, including no matches. Exit 1 means an API or output failure. Exit 2 means invalid arguments or an installation the command cannot open. Cloud and Dedicated serve audit reads under the same authorization rules.

valet-dedicated support bundle

valet-dedicated support bundle --out <dir> [--since <duration>] [--force]

Writes what Valet support asks for into <dir>, which it creates. It sends nothing anywhere.

descriptor.json

Holds
The installation descriptor.

check.json

Holds
The result of check --output json.

deployments/

Holds
The last five deployment records upgrade wrote.

ecs.json

Holds
Each service's recent events and the stop reasons of its last ten stopped tasks.

logs/<service>.log

Holds
The last --since of each service's log, up to 5 MB.

settings.json

Holds
Every system setting. A secret shows set or unset.

manifest.json

Holds
Each file's size, sha256, and redaction count, the redaction rules, the tool version, and anything the tool could not read.

Before it writes a file, the command replaces values that look like secrets with [redacted]: bearer tokens, AWS access keys, JWTs, sk- and sk-ant- keys, WorkOS sk_ keys, PEM blocks, password=, secret=, and token= values, and passwords in URLs. It also replaces the operator token. Review the directory before you send it.

A call the deployment role may not make is reported in the bundle and in manifest.json, and the rest of the bundle is written.

FlagDescription
--out <dir>The directory to write. Required. The command refuses a directory that holds files.
--forceWrite into a directory that holds files. Files with other names stay.
--since <duration>How far back to read logs. Default 1h.

It exits 2 when it cannot open the installation or refuses the directory.

valet-dedicated upgrade

valet-dedicated upgrade <tag> [--plan] [--yes] [--bedrock] [--catalog-dir <dir>]

--plan verifies the release and prints image, task definition, service, migration, catalog, and snapshot changes. It takes no lock and writes nothing. Recheck the plan after another operator changes the installation.

Upgrade requires the descriptor's module version to match the target exactly. It refuses downgrades and releases that do not name the installed version in their predecessor list. A first install and a same-version retry are allowed. Old manifests and records without schema evidence are refused.

When the schema floor advances, upgrade creates a manual RDS snapshot and waits for available before migration. Its name is <name>-pre-<version>, with stable version dots replaced by hyphens. Other tags use letters, digits, and single hyphens with a digest suffix. Names stay within 255 characters; truncation also adds a digest suffix. A retry reuses an available snapshot. Failed creation records no snapshot name. The deployment record and status show the applied schema, available snapshot, and whether migration started. An unfinished migration permits a retry or a newer release that lists it as a predecessor. A preparation failure imposes no new target restriction.

Deploys the release <tag>. It takes the installation's lock, verifies the bundled catalog, and uploads missing snapshot objects to your catalog bucket. It stops on a digest mismatch before deploying services. It then copies the images by digest into the installation's repositories, fills empty secrets, runs migrate and the settings bootstrap, registers new task definitions, updates only the services that changed, and waits until they are stable and /health answers. It then reconciles catalog rows inside the VPC and writes a deployment record to the records bucket. It posts the outcome to the deploys feed when that webhook is set. A repeat uploads no catalog objects and makes no catalog changes when the rows already match.

--bedrock

Description
First install: bootstrap Bedrock task-role authentication instead of collecting an Anthropic API key. A stored provider setting takes precedence.

--yes

Description
Never prompt. Stop when a value only a person can enter is missing.

--catalog-dir <dir>

Description
Verify a local catalog.json against manifest.json and manifest.json.sig in the same directory. The manifest must match the embedded release key.

Before it copies an image, upgrade collects the keys the services need to start. It always fills the empty workos secret. Unless Bedrock is selected, when nothing has set inference.anthropic_api_key, writes that key into the settings_bootstrap secret. For each key it reads an environment variable, and then asks on a terminal, without echo. With --yes, or without a terminal, a missing key stops upgrade before it copies an image. upgrade also stores an optional OpenAI key as inference.openai_api_key when VALET_DEDICATED_OPENAI_API_KEY is set. It never asks for that key.

VALET_DEDICATED_WORKOS_API_KEY

Description
The WorkOS API key, for the workos secret.

VALET_DEDICATED_ANTHROPIC_API_KEY

Description
The Anthropic API key, for inference.anthropic_api_key.

VALET_DEDICATED_OPENAI_API_KEY

Description
Optional. The OpenAI API key, for inference.openai_api_key.

valet-dedicated settings set

valet-dedicated settings set <key> --reason <text> --stdin

Changes the system setting <key> through the installation's API. The value comes from stdin, never from an argument. The command trims one trailing newline.

FlagDescription
--stdinRead the value from stdin.
--reason <text>Why the value changes. Required. The installation stores it with the change.

Example:

printf '%s' "$ANTHROPIC_API_KEY" | valet-dedicated settings set \
  inference.anthropic_api_key --stdin --reason "initial key"

Set the optional OpenAI key the same way:

printf '%s' "$OPENAI_API_KEY" | valet-dedicated settings set \
  inference.openai_api_key --stdin --reason "enable OpenAI models"

valet-dedicated status

valet-dedicated status [--output text|json]

Prints what the installation runs: the release version, the module version, each service's running and desired count and task definition revision, the standby pool against its target, and the newest deployment record. It reads what check reads and judges none of it. --output json prints one object with version, installation, region, ok, release, module_version, services, standby_pool, last_deployment, and errors.

It exits 0 when it reads every part, 1 when a part is unreadable, and 2 when it cannot run.

valet-dedicated settings list, get, history, and unset

valet-dedicated settings list [--output text|json]
valet-dedicated settings get <name> [--output text|json]
valet-dedicated settings history <name> [--limit 20] [--output text|json]
valet-dedicated settings unset <name> --reason <text> [--yes] [--output text|json]

list and get print the effective value, the source (stored, env, or default), and the revision. history prints a setting's changes, newest first. A secret setting shows as set or not set in every output mode and never shows its value. With --output json, list, history, and the commands for people and caps print one JSON object per line, with snake_case keys. get and unset print one object.

unset removes the stored value, so the default applies. It asks you to confirm. --yes skips the question; with no terminal to answer on, pass --yes. All four exit 1 on a failure and 2 on a bad flag or an installation they cannot open.

valet-dedicated users list, suspend, and unsuspend

valet-dedicated users list [--output text|json]
valet-dedicated users suspend <email> --reason <text> [--yes] [--output text|json]
valet-dedicated users unsuspend <email> [--output text|json]

list prints the people who have signed in, with whether each is suspended. suspend blocks a person from the API and asks you to confirm; --yes skips the question. unsuspend restores access and asks nothing.

valet-dedicated services list, suspend, and resume

valet-dedicated services list [--org <org>] [--kind site|app|agent|skill] \
  [--output text|json]
valet-dedicated services suspend <org>/<name> --reason <text>
valet-dedicated services suspend --all [--org <org>] --reason <text> [--yes]
valet-dedicated services resume <org>/<name> [--reason <text>]
valet-dedicated services resume --all [--org <org>] [--reason <text>] [--yes]

list follows every page. It prints identity, kind, access, connectors, publisher, publication time, suspension time, and reason. JSON emits one service per line, with snake_case keys and null unknown timestamps.

suspend refuses traffic and publishing, then stops containers through the reconciler. resume restores the saved formation and desired state. Both bulk commands prompt unless --yes is set. Named commands do not prompt. Resume records operator requested resume unless --reason supplies another explanation. See Operations.

Exit 0 means success. Exit 1 means an API or output failure. Exit 2 means invalid usage or an installation the command cannot open.

valet-dedicated orgs caps and set-cap

valet-dedicated orgs caps <org> [--output text|json]
valet-dedicated orgs set-cap <org> <cap> <value> [--output text|json]

caps prints each cap that governs the org, its override, and the value in force. set-cap sets one override. A value of 0 clears it, so the default applies. The caps are agent-cap, site-cap, app-cap, skill-cap, resource-cap, app-resource-cap, site-mcp-rate-limit, and email-cap.

valet-dedicated oauth-clients set, list, and delete

valet-dedicated oauth-clients set <org> <provider> --client-id <id> [--stdin] [--output text|json]
valet-dedicated oauth-clients list [--org <org>] [--output text|json]
valet-dedicated oauth-clients delete <org> <provider> [--yes] [--output text|json]

Some providers, such as Google and Microsoft, bind a client ID and secret to one OAuth app, and an installation has no app of its own with them. The org registers an app with the provider, then you store its client ID and secret here. Every connector the org creates for that provider then uses the app.

set stores the app. The client ID comes from --client-id. The secret never comes from an argument or a flag. Pass --stdin and pipe it in, or run set in a terminal and type it at the prompt, which shows nothing. The command trims one trailing newline and never prints the secret.

printf '%s' "$CLIENT_SECRET" | valet-dedicated oauth-clients set acme google \
  --client-id 123.apps.googleusercontent.com --stdin

Replacing an app withdraws the grants of the connectors that use it. Their owners authorize again, and set prints how many. A provider that registers its own app with Valet refuses an org's app, and set prints the reason.

list prints each stored app: org, provider, client ID, and whether a secret is stored. It never prints a secret. Without --org, it covers every org.

delete removes the app and asks you to confirm; --yes skips the question. The grants of the connectors that use it are withdrawn. A provider that connects only through an org's own app loses the org's connectors instead.

On Dedicated, the platform's own Google and Microsoft apps do not list your installation's domain among their redirect URIs. Store an app with set for each Google or Microsoft connector you want your people to use. Until you do, those connectors cannot finish authorizing. A provider that registers its own app with Valet, such as Linear, needs none and refuses one.

Each write lands in the audit log with the org, the provider, and the client ID. Exit 0 means success, 1 means the API refused or could not be reached, and 2 means a bad flag or argument, or an installation the command cannot open.

valet-dedicated users set-role

valet-dedicated users set-role <email> <user|operator|superuser> --reason <text>

Sets the platform role of the person at <email>. The role replaces the one they hold. The person must have signed in once. The command refuses a change that would leave no superuser, and it recovers an installation that has none.

FlagDescription
--reason <text>Why the role changes. Required. The installation stores it with the change.

valet-dedicated releases egress

valet-dedicated releases egress <version> [--provider anthropic|bedrock] \
  [--openai] [--languages python,node,go] [--webfetch] \
  [--region <region>] [--account <id>] [--include <text>] \
  [--output text|json]
valet-dedicated releases egress --file <path> [flags]

Prints the outbound destinations of release <version> that apply to your choices, for your network team's firewall, proxy, and VPC endpoint rules. It reads the release's egress.json with your AWS credentials, then checks the manifest signature and the file's digest. Text shows HOST, PORT, PROCESSES, and PURPOSE, then a note that agents with WebFetch reach any public host and apps reach whatever their code calls. JSON contains schema and destinations, with the fields of egress.json.

Required destinations always appear. Slack, Telegram, Loops, Composio, Z.ai, and telemetry rows appear only when --include matches their host.

--provider <name>

Description
Claude provider: anthropic (default) or bedrock.

--openai

Description
Include the OpenAI rows.

--languages <list>

Description
Builder rows for python, node, and go.

--webfetch

Description
Include the public-internet runtime rows.

--region <region>

Description
Fill <region> in hosts.

--account <id>

Description
Fill <account> in hosts.

--include <text>

Description
Also list rows whose host contains the text. Repeatable.

--output <format>

Description
text (default) or json.

--file <path>

Description
Read a local egress.json instead; uses no network.

valet-dedicated releases fetch

valet-dedicated releases fetch <version> --dir <path>

Downloads release <version> from the distribution bucket with your AWS credentials. It verifies the module and this machine's binary against the manifest, unpacks the module into --dir, and writes the binary beside it as valet-dedicated-<version>. It prints the source to use.

--dir must not exist, must be empty, or must hold an earlier fetch, which fetch replaces.

FlagDescription
--dir <path>Directory for the unpacked module. Required.

Installation defaults

The Dedicated profile keeps two standby runtimes ready for work. Its capacity settings are:

runtime.standby_count

Dedicated default
2
Purpose
Standby runtimes ready for work.

org.default_agent_cap

Dedicated default
500
Purpose
Agents per organization.

org.default_app_cap

Dedicated default
500
Purpose
Apps per organization.

org.default_resource_cap

Dedicated default
500
Purpose
Resources per organization.

A stored setting overrides the profile, including a value equal to an older default. Per-organization cap overrides also keep their values. Cap changes apply after a settings reload. The standby pool follows its new target on the next convergence pass.

Pipe a replacement value into valet-dedicated settings set:

printf '%s' '4' | valet-dedicated settings set runtime.standby_count \
  --stdin --reason "increase standby pool"
printf '%s' '750' | valet-dedicated settings set org.default_agent_cap \
  --stdin --reason "increase agent cap"
printf '%s' '750' | valet-dedicated settings set org.default_app_cap \
  --stdin --reason "increase app cap"
printf '%s' '750' | valet-dedicated settings set org.default_resource_cap \
  --stdin --reason "increase resource cap"

Private destinations

network.private_destinations lets platform services reach listed private MCP servers and model gateways. The default is empty. Keep connector.public_addresses_only enabled, as the Dedicated profile does.

Supply a comma-separated list of IPs, CIDRs, exact host names, or *.suffix wildcards. A wildcard matches subdomains, never the apex. For example:

printf '%s' '10.20.0.0/16,fd00:1::/64,mcp.corp.example,*.tools.corp.example' |
  valet-dedicated settings set network.private_destinations \
    --stdin --reason "allow corporate MCP servers"

The API validates entries before saving. Loopback, link-local, metadata, unspecified, multicast, reserved, and transition addresses remain forbidden, even through a listed host name. A host entry permits only that name's resolved addresses. Other names at the same IP still need an entry.

Changes apply to new connection attempts after settings reload, without a restart. Existing pooled connections remain open. Clear the list with:

valet-dedicated settings unset network.private_destinations \
  --reason "remove private destination access"

You must provide a network route from the installation's VPC to the private destination, using VPC peering, Transit Gateway, or a VPN. Configure DNS and the destination's inbound rules for the platform services. The platform security group already permits outbound IPv4 traffic; no module input is needed for those destinations. IPv6 entries also need IPv6 addressing, routing, and platform egress configured in your network. This setting adds none of them. Only platform services dial these destinations. Runtime and builder workloads gain no network access from this setting.

Allowed private dials produce info logs with the host, matched entry, destination role, and resolved address. Refused addresses keep the connector.private_address problem code.

Model gateways

Point Valet at your own Anthropic- or OpenAI-compatible gateway, such as LiteLLM, Portkey, or an internal proxy, with two settings. Each is empty by default, which selects the vendor's public API.

inference.anthropic_base_url

Gateway URL
The gateway's root, for example https://litellm.corp.example. Valet adds /v1/messages.

inference.openai_base_url

Gateway URL
The gateway's OpenAI path, for example https://litellm.corp.example/v1.

The Anthropic setting also covers the platform's own Anthropic calls, such as agent naming and design-system briefs. A URL is absolute, with no user name, password, query, or fragment. Use https. Use http only for a gateway inside your VPC, and only when network.private_destinations already lists its host name or address. Set the private destination first.

printf '%s' 'litellm.corp.example' |
  valet-dedicated settings set network.private_destinations \
    --stdin --reason "allow the model gateway"
printf '%s' 'https://litellm.corp.example' |
  valet-dedicated settings set inference.anthropic_base_url \
    --stdin --reason "route Anthropic through LiteLLM"

A private gateway must be on network.private_destinations, with the routing and DNS that Private destinations lists. Loopback and metadata addresses are always refused. A public gateway needs no entry.

Both settings apply at restart: the api, worker, and inference services read them at boot. A change takes effect when those services next restart, for example during valet-dedicated upgrade. Valet still sends the provider key from inference.anthropic_api_key or inference.openai_api_key to the gateway, so set a key the gateway accepts. Without a key, the catalog offers no plan for that provider.

Outbound endpoints

Every release carries egress.json, the list of destinations the installation's processes contact. Its digest is in manifest.json, which manifest.json.sig signs. Fetch it from the release bucket beside the manifest, at releases/<version>/egress.json. Give the list to your network team to write firewall, proxy, and VPC endpoint rules.

Each row names the process that dials the host, whether the installation needs it, and the setting or feature that makes the process dial it. A host in angle brackets is a value the installation supplies, such as your region or a connector's URL. The Port column shows the default port. Telemetry uses its endpoint's configured port when it differs. Return traffic needs no rule.

The ecs-agent rows are the Fargate agent, which pulls images and secrets before a task starts. A required row is on for every installation. An optional row is on only when its setting or feature is. Platform services reach the internet through your NAT, and so do runtimes and builders. A runtime or builder cannot reach a VPC endpoint, because an endpoint has a private address that their security groups refuse. The "Security groups" section of the module's README.md lists every rule.

api.workos.com

Port
443
Process
api
Need
required
Enabled by
always
Purpose
Sign-in, the user directory, and token verification.

workoscdn.com

Port
443
Process
api
Need
optional
Enabled by
a person with a WorkOS profile picture
Purpose
Profile pictures. The api serves them to the dashboard.

api.anthropic.com

Port
443
Process
api, inference, worker
Need
optional
Enabled by
inference.anthropic_provider = anthropic and inference.anthropic_api_key, unless inference.anthropic_base_url is set
Purpose
Claude model calls and the platform's own Anthropic calls. inference.anthropic_base_url replaces this host.

<inference.anthropic_base_url>

Port
443
Process
api, inference, worker
Need
optional
Enabled by
inference.anthropic_base_url
Purpose
Your Anthropic-compatible model gateway. The host is the URL's host; a private host needs network.private_destinations.

bedrock-runtime.<region>.amazonaws.com

Port
443
Process
api, inference, worker
Need
optional
Enabled by
inference.anthropic_provider = bedrock
Purpose
Claude model calls through Amazon Bedrock. The region is inference.bedrock_region, or the task's region when empty. With bedrock_vpc_endpoint = true, the traffic stays on the module's VPC endpoint.

api.openai.com

Port
443
Process
inference
Need
optional
Enabled by
inference.openai_api_key
Purpose
OpenAI model calls. inference.openai_base_url replaces this host.

<inference.openai_base_url>

Port
443
Process
inference
Need
optional
Enabled by
inference.openai_base_url
Purpose
Your OpenAI-compatible model gateway. The host is the URL's host; a private host needs network.private_destinations.

api.z.ai

Port
443
Process
inference
Need
optional
Enabled by
inference.zai_api_key
Purpose
Z.ai model calls.

<telemetry.endpoint-host>

Port
443
Process
api, build, dashboard, inference, worker
Need
optional
Enabled by
telemetry
Purpose
Export metrics and traces over OTLP/HTTPS. Use the endpoint's configured port when it is not 443.

s3.<region>.amazonaws.com

Port
443
Process
api, build, builder, ecs-agent, worker
Need
required
Enabled by
always
Purpose
Uploads, build sources and caches, the catalog, and image layers.

ecs.<region>.amazonaws.com

Port
443
Process
api, build, worker
Need
required
Enabled by
always
Purpose
Start and stop runtime and builder tasks.

sts.<region>.amazonaws.com

Port
443
Process
api, build, worker
Need
required
Enabled by
always
Purpose
Assume the roles that start tasks and manage org domains.

logs.<region>.amazonaws.com

Port
443
Process
api, ecs-agent
Need
required
Enabled by
always
Purpose
Write the audit group and every task's logs.

secretsmanager.<region>.amazonaws.com

Port
443
Process
ecs-agent
Need
required
Enabled by
always
Purpose
Inject secrets when a task starts.

api.ecr.<region>.amazonaws.com

Port
443
Process
ecs-agent
Need
required
Enabled by
always
Purpose
Authorize image pulls from the installation's registry.

<account>.dkr.ecr.<region>.amazonaws.com

Port
443
Process
ecs-agent
Need
required
Enabled by
always
Purpose
Pull platform, runtime, and builder images.

acm.<region>.amazonaws.com

Port
443
Process
api, worker
Need
required
Enabled by
always
Purpose
Request and delete each org's certificate.

elasticloadbalancing.<region>.amazonaws.com

Port
443
Process
api, worker
Need
required
Enabled by
always
Purpose
Attach each org's certificate to the load balancer listener.

route53.amazonaws.com

Port
443
Process
api, worker
Need
required
Enabled by
always
Purpose
Write certificate validation records in the public zone.

registry.npmjs.org

Port
443
Process
builder
Need
optional
Enabled by
an app with a package.json
Purpose
Install Node dependencies during a build.

nodejs.org

Port
443
Process
builder
Need
optional
Enabled by
an app with a package.json
Purpose
Node.js releases, resolved by the node-engine buildpack.

artifacts.paketo.io

Port
443
Process
builder
Need
optional
Enabled by
an app with a package.json
Purpose
Node.js builds the node-engine buildpack downloads.

pypi.org

Port
443
Process
builder
Need
optional
Enabled by
an app with requirements
Purpose
Resolve Python dependencies during a build.

files.pythonhosted.org

Port
443
Process
builder
Need
optional
Enabled by
an app with requirements
Purpose
Download Python packages during a build.

proxy.golang.org

Port
443
Process
builder
Need
optional
Enabled by
an app with a go.mod
Purpose
Download Go modules during a build.

sum.golang.org

Port
443
Process
builder
Need
optional
Enabled by
an app with a go.mod
Purpose
Verify Go module checksums during a build.

<public-internet>

Port
443
Process
runtime
Need
optional
Enabled by
agent.webfetch_enabled
Purpose
The WebFetch tool, package installs, git clones, and any host an agent's commands reach. Private ranges are blocked.

<public-internet>

Port
80
Process
runtime
Need
optional
Enabled by
agent.webfetch_enabled
Purpose
Plain HTTP from the same tools. Private ranges are blocked.

<connector-host>

Port
443
Process
api, runtime
Need
optional
Enabled by
a connector on an agent
Purpose
Each connector's configured host: an MCP server, a SaaS API, or a command connector's vendor. Private hosts need network.private_destinations.

backend.composio.dev

Port
443
Process
api, worker
Need
optional
Enabled by
composio.api_key
Purpose
Egress to Composio's API for Composio connectors and triggers. The installation sends tool calls and account links there.

slack.com

Port
443
Process
api, worker
Need
optional
Enabled by
a Slack channel on an agent
Purpose
Slack API calls. Slack cannot send events to an internal load balancer.

files.slack.com

Port
443
Process
api, worker
Need
optional
Enabled by
a Slack channel on an agent
Purpose
Download files people attach in Slack.

api.telegram.org

Port
443
Process
api, worker
Need
optional
Enabled by
a Telegram channel on an agent
Purpose
Telegram Bot API calls. Telegram cannot send updates to an internal load balancer.

app.loops.so

Port
443
Process
api, worker
Need
optional
Enabled by
email.loops_enabled
Purpose
Transactional email through Loops. The Dedicated profile turns it off.

The installation never contacts code.storage, BetterStack, Sentry, or Stripe. It stores source on its own file system and sets none of their variables. Calls between the installation's own services stay inside your VPC. The valet-dedicated tool on your machine has its own traffic: the release bucket, your AWS account, and the Slack webhook for deploy messages if you set one.

Service quotas

The installation needs these AWS service quotas. Each default is AWS's at the time of writing; check your account's values in the Service Quotas console before you install. Ask AWS Support to raise a quota early, because a request takes days.

Certificates per Application Load Balancer listener

AWS default
25
What the installation uses
The apex certificate and one per org, so about 24 orgs. check warns at 20

ACM certificates per account

AWS default
2,500
What the installation uses
The apex certificate and one per org

Fargate On-Demand vCPU resource count

AWS default
6 in some new accounts
What the installation uses
2 vCPU for the five platform services at their default sizes, 0.25 vCPU for each runtime, and 2 vCPU for each running build. An upgrade briefly runs old and new tasks together

Outbound rules per security group

AWS default
60
What the installation uses
runtime uses 49 and builder uses 48: the public IPv4 prefix list counts its 47 entries

RDS DB instances per Region

AWS default
40
What the installation uses
One, or two with the app database

EFS file systems per Region

AWS default
1,000
What the installation uses
One, for source storage

The module creates no NAT gateway or Elastic IP address. Your VPC's NAT carries every outbound connection in the table above. Size it for your agents' traffic; see Cost.

Amazon Bedrock

From 0.9.0, inference.anthropic_provider = bedrock sends Anthropic calls through Amazon Bedrock in your AWS account. Cloud and Dedicated default to anthropic; choosing Bedrock is an operator decision. There is no second agent runtime or credential delivery path.

inference.anthropic_provider

Default
anthropic
Apply
restart
Meaning
anthropic uses the API key and optional gateway; bedrock uses AWS credentials.

inference.bedrock_region

Default
empty
Apply
restart
Meaning
Empty uses the task's region. A value selects another Bedrock endpoint region.

The API, worker, and inference binaries use the AWS default credential chain. On ECS, their task roles sign requests. No Anthropic key reaches Bedrock. The same route covers agent and app messages, compaction, merge, blueprint analysis, naming, design-system writing, and token extraction. inference.anthropic_base_url has no effect while Bedrock is selected. OpenAI and Z.ai configuration stays independent.

Model access and IAM

Enable Anthropic model access in the Bedrock console before installation. Complete the first-use form and any Marketplace subscription the console requires. Include the platform models Sonnet 4.5 and Haiku 4.5, as well as every agent model you offer. See AWS's model access guide.

The catalog's bedrockModels map in lib/modelcatalog/models.json owns the exact global profile IDs. Current supported Anthropic models and the platform's pinned models have mappings. An unmapped model is hidden from inference resource plans and refused before forwarding.

Set bedrock_model_arns to the exact inference-profile ARNs and every foundation-model ARN those profiles can invoke. Copy these from the Bedrock console for your account and regions. A cross-region profile needs grants for its destination models too. The accepted ARN shapes are:

  • Regional foundation model: arn:aws:bedrock:us-east-2::foundation-model/anthropic.claude-sonnet-5
  • Region-less foundation model for a global profile: arn:aws:bedrock:::foundation-model/anthropic.claude-sonnet-5
  • Inference profile: arn:aws:bedrock:us-east-2:123456789012:inference-profile/global.anthropic.claude-sonnet-5

The module grants only bedrock:InvokeModel and bedrock:InvokeModelWithResponseStream on that list, to the api, worker, and inference task roles. Empty grants nothing. It grants no subscription or model-access administration permissions. SCPs and account model access must also permit the calls.

With bedrock_vpc_endpoint = true, the module creates a bedrock-runtime interface endpoint in private_subnet_ids, with private DNS. Its security group accepts TCP 443 from the platform task security group. The endpoint uses the installation's region. An override in inference.bedrock_region needs connectivity to that other region's endpoint. The endpoint does not remove other services' internet requirements or restrict global profiles' processing regions.

Select or change the provider

For a first install, use upgrade <tag> --bedrock. It writes the provider to settings_bootstrap before services boot and skips the Anthropic key prompt. It does not replace a provider already stored in system settings.

For an existing installation, grant model access and apply the module inputs first. Then set the provider and restart all three callers:

printf '%s' bedrock |
  valet-dedicated settings set inference.anthropic_provider \
    --stdin --reason "use account Bedrock models"
valet-dedicated roll --yes

Set inference.bedrock_region before the roll if needed. Keep the old Anthropic key until the roll finishes; old tasks still use it. Afterward, settings unset inference.anthropic_api_key is allowed. check reports Bedrock as satisfying the Anthropic requirement; it does not invoke a model or verify IAM grants. Test an agent after installation.

To return to direct Anthropic, set its API key first, select anthropic, and roll again. The settings store refuses switching back without a key.

Behavior and limits

Streaming, client tools, prompt cache controls, thinking parameters, and token accounting use the same Anthropic adapter. The SDK translates Bedrock's binary event stream into Anthropic SSE. Valet retains the catalog model ID in usage; displayed costs use catalog prices, not an AWS invoice or your account's discounts.

Bedrock InvokeModel omits Anthropic user metadata. It does not expose the entire direct Anthropic API, such as Files and batch endpoints. Beta features and thinking modes depend on the selected Bedrock model and may be rejected. Global profiles can route across regions. AWS supplies access, quota, and provider error responses; there is no fallback to the direct Anthropic API when a Bedrock call fails.

Module inputs

The module is terraform-aws-valet-dedicated. Required inputs have no default.

Required

name

Description
The installation name. It prefixes every resource name, so it is unique within the account.

home_org

Description
The org every person joins on first sign-in. It appears in every site and app hostname. A DNS label of 3 to 63 lowercase letters, digits, and hyphens, and not a name the platform reserves. Set it once before first sign-in.

vpc_id

Description
The VPC the installation runs in.

private_subnet_ids

Description
Private subnets for tasks, RDS, and EFS, in two or more availability zones, with outbound internet access.

apex

Description
The DNS apex. The API is api.<apex>, the dashboard dashboard.<apex>, and sites and apps live under *.<apex>.

workos

Description
{client_id, authkit_domain} of the installation's WorkOS environment.

Optional

vpc_owner_account_id

Default
null
Description
The 12-digit ID of the account that owns vpc_id, when it is shared through AWS RAM. Set, the module creates the private zone on an empty anchor VPC it owns, authorizes the shared VPC, and outputs the command the VPC owner runs.

workload_subnet_ids

Default
private_subnet_ids
Description
Private subnets for runtime and builder tasks, in two or more availability zones, with outbound internet access.

ingress

Default
The three RFC 1918 ranges
Description
CIDRs that reach the internal load balancer on 443, and on 80 for the redirect.

public_zone_id

Default
none
Description
The public hosted zone for the apex, used when public_zone_lookup is false.

public_zone_lookup

Default
true
Description
Look the public zone up by the apex. Set false when you pass public_zone_id.

sizes

Default
One task per platform service
Description
CPU, memory, and count for each service family, the runtime type, and the builder's size.

database

Default
db.t4g.small, 20 GB
Description
The RDS instance class and initial storage.

app_database

Default
off; db.t4g.small, 20 GB when enabled
Description
A second RDS PostgreSQL instance for apps' PostgreSQL resource (valet-postgresql). { enabled, instance_class, allocated_gb }; allocated_gb is 20 to 65536. It has its own security group and admin secret <name>/resource_rds, the same protection and backup as the database, and is the resource server api and worker create each app's role and database on. Turning it off later destroys the instance; with protection it refuses.

protection

Default
true
Description
Deletion protection, final snapshots, and secret recovery windows. Set false only for disposable installations.

backup

Default
{ enabled = true, retention_days = 35 }
Description
Daily AWS Backup of the file system that holds your source repositories and of the database and the app database, at 05:00 UTC. It runs only when protection is true and enabled is true. retention_days is 1 to 3650. Deleting the backup vault fails while recovery points exist, which is intended.

log_retention_days

Default
365
Description
Days each CloudWatch log group the module creates keeps its events: the service and task groups and the ECS Exec groups. 0 keeps them forever. Otherwise a value CloudWatch accepts, such as 30, 90, 180, 365, or 731.

audit_retention_days

Default
400
Description
Days the audit log group /valet/<name>/audit and the database log group /aws/rds/instance/<name>-db/postgresql keep their events. 0 keeps them forever. Otherwise a value CloudWatch accepts, such as 90, 365, 400, or 731. Separate from log_retention_days. See Observe and what the database records.

alb_access_logs_bucket

Default
none
Description
The name of an S3 bucket you own. The load balancer writes access logs to it under the prefix <name>. You create the bucket and its policy; see Observe.

alerts_topic_arn

Default
none
Description
An SNS topic ARN in the installation's region. The module creates the alarms in Observe and publishes to the topic when each goes to ALARM and back to OK. Without it, the module creates no alarm.

alarms

Default
See below
Description
Thresholds for the alarms. Used only with alerts_topic_arn.

telemetry

Default
none
Description
{ endpoint, token_secret, auth_header, auth_prefix }. Sends Valet's metrics and traces to an OTLP/HTTP collector. endpoint is an https URL with no path. token_secret is the ARN or name of a Secrets Manager secret in the installation's region that holds the token. auth_header defaults to Authorization and auth_prefix to Bearer . See Observe. Without it, nothing exports.

private_systems

Default
{}
Description
Systems inside your network that apps may reach. Each has a required description, guide, and non-empty env, and plans; a plan has a required description, destinations ({ cidr, ports }), and optional subnet_ids among the workload subnets. The module creates one egress-only security group per plan. See Private systems.

bedrock_model_arns

Default
[]
Description
Exact foundation-model and inference-profile ARNs granted to api, worker, and inference task roles. No wildcards.

bedrock_vpc_endpoint

Default
false
Description
Create a private-DNS bedrock-runtime interface endpoint and HTTPS security group in the installation subnets.

distribution_registry

Default
Set by the release
Description
The registry release images are copied from. Leave it unset.

The alarms object

Set any field; the others keep their defaults. Every value is above zero.

alb_5xx_count

Default
10
Meaning
5xx responses in 5 minutes, from targets or from the load balancer, before an alarm

rds_cpu_percent

Default
80
Meaning
Average CPU over 15 minutes

rds_free_storage_percent

Default
10
Meaning
Free share of the allocated storage

rds_max_connections

Default
225
Meaning
The instance class's connection limit. 225 fits db.t4g.small; raise it for a larger class

rds_connections_percent

Default
80
Meaning
Share of rds_max_connections in use over 15 minutes

efs_burst_credit_bytes

Default
1000000000000
Meaning
Lowest burst credit balance, in bytes

What the database records

The database instance accepts IAM database authentication and exports its PostgreSQL log to the CloudWatch log group /aws/rds/instance/<name>-db/postgresql. The log names each connection and disconnection with the role that made it. The parameter group sets log_connections and log_disconnections to 1; both apply at once. It also loads pgaudit through shared_preload_libraries, with no audit class enabled.

A new installation loads pgaudit at its first boot. On an existing installation, shared_preload_libraries is a static parameter. After the apply, the console shows the parameter group as pending-reboot until the instance next reboots, such as at a maintenance window. Nothing breaks in the meantime, and the connection log works without the reboot. The apply turns on IAM authentication and the log export without a restart.

Outputs

descriptor_parameter

Description
The Parameter Store name of the installation's descriptor.

deployment_role_arn

Description
The role the tool assumes to deploy.

api_url

Description
The API's URL.

dashboard_url

Description
The dashboard's URL.

private_zone_id

Description
The private Route 53 zone for the apex.

private_zone_association_command

Description
Null unless vpc_owner_account_id is set. Then the two aws route53 associate-vpc-with-hosted-zone commands, one per line, the VPC owner runs: one for the private zone, one for the service discovery namespace.

The module needs two AWS providers, aws and aws.workloads, for the same account.

Installation policies

A superuser can require checks for every org. Org Admins see these policies read-only and cannot remove or weaken them. Org policies add requirements. A blocking policy outranks a monitor policy. Among blocking policies on the same checker, the lower severity threshold is stricter. Each policy keeps its own settings and evaluation result.

Upgrade the API and worker before setting an installation policy. Existing releases stay live. New releases must pass every applicable blocking policy.

valet-dedicated policies list

List installation policies, including their scope, settings, and enforcement. Secret settings show only their presence. Use --output text (default) or --output json.

valet-dedicated policies set

Read a policy JSON object from stdin and set it under the supplied name. --stdin and a nonempty --reason are required. The audit event records the name, checker, and reason; it never records settings. Only catalog checkers can apply across orgs. Omitted secret settings retain their stored values.

bin/valet-dedicated policies set secrets --stdin \
  --reason "Require credential scanning in every org" --output json <<'JSON'
{
  "checker": "catalog:secrets",
  "applies_to": "every_release",
  "enforcement": {"kind": "block", "block_at": "high"},
  "settings": {}
}
JSON

valet-dedicated policies delete

Remove an installation policy with a required, nonempty --reason:

bin/valet-dedicated policies delete secrets --reason "Replace the scanner"

The command reads the checker before deleting and refuses a stale checker. List policies again before retrying. Removing an absent policy changes nothing. Existing org policies remain in force.

All three commands accept --output text|json. They exit 0 on success, 1 on an API or output failure, and 2 for invalid usage or an installation that cannot be opened. They use the installation's operator token.

valet-dedicated access-rules

Use access-rules get to inspect the installation ceiling and existing violations. Use access-rules set to replace the ceiling. Both flags and an audit reason are required, so an omitted flag cannot clear a rule.

valet-dedicated access-rules get --output json
valet-dedicated access-rules set --forbid-public=true \
  --forbid-password=false --reason "security policy"

Both commands accept --output text or --output json. A rule restricts future access changes; it does not change existing services. Org Admins may add stricter rules, but cannot relax the installation ceiling.

Both commands exit 0 on success, 1 on an API or output failure, and 2 for invalid usage or an installation that cannot be opened. They use the installation's operator token. Each write records its reason and both flags in the admission audit.

Custom connectors

Dedicated defaults connector.custom to admin: only an org Admin adds a custom connector. developer permits Developers. allowlist permits only hosts and packages listed in connector.custom_allowlist.

Use exact lowercase host names, such as host:tools.example.com, or npm package names, such as package:@example/tools. Host entries ignore ports. Wildcards, URLs, and paths are invalid. Packages must run through npx; other launchers are refused. Set the list before selecting allowlist mode:

printf '%s' '["host:tools.example.com","package:@example/tools"]' |
  valet-dedicated settings set connector.custom_allowlist --stdin \
    --reason "approved custom connectors"
printf '%s' 'allowlist' |
  valet-dedicated settings set connector.custom --stdin \
    --reason "restrict custom connector definitions"

Both settings apply after the API reloads settings. Catalog installations, existing connectors, credential rotation, and attachments stay available. The allowlist controls definitions; it does not filter their network traffic or sandbox the code in a permitted package.