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.
| Flag | Description |
|---|---|
--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|json | Print 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 code | Meaning |
|---|---|
| 0 | Every item passed. |
| 1 | An item failed. |
| 2 | check 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
upgradewrote.
ecs.json
- Holds
- Each service's recent events and the stop reasons of its last ten stopped tasks.
logs/<service>.log
- Holds
- The last
--sinceof each service's log, up to 5 MB.
settings.json
- Holds
- Every system setting. A secret shows
setorunset.
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.
| Flag | Description |
|---|---|
--out <dir> | The directory to write. Required. The command refuses a directory that holds files. |
--force | Write 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.jsonagainstmanifest.jsonandmanifest.json.sigin 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
workossecret.
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> --stdinChanges the system setting <key> through the installation's API. The
value comes from stdin, never from an argument. The command trims one
trailing newline.
| Flag | Description |
|---|---|
--stdin | Read 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 --stdinReplacing 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.
| Flag | Description |
|---|---|
--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) orbedrock.
--openai
- Description
- Include the OpenAI rows.
--languages <list>
- Description
- Builder rows for
python,node, andgo.
--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) orjson.
--file <path>
- Description
- Read a local
egress.jsoninstead; 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.
| Flag | Description |
|---|---|
--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.
checkwarns 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
runtimeuses 49 andbuilderuses 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
anthropicuses the API key and optional gateway;bedrockuses 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 --yesSet 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 dashboarddashboard.<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_lookupisfalse.
public_zone_lookup
- Default
true- Description
- Look the public zone up by the apex. Set
falsewhen you passpublic_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_gbis 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; withprotectionit refuses.
protection
- Default
true- Description
- Deletion protection, final snapshots, and secret recovery windows. Set
falseonly 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
protectionistrueandenabledistrue.retention_daysis 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.
0keeps 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>/auditand the database log group/aws/rds/instance/<name>-db/postgresqlkeep their events.0keeps them forever. Otherwise a value CloudWatch accepts, such as 90, 365, 400, or 731. Separate fromlog_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
ALARMand back toOK. 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.endpointis an https URL with no path.token_secretis the ARN or name of a Secrets Manager secret in the installation's region that holds the token.auth_headerdefaults toAuthorizationandauth_prefixtoBearer. 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-emptyenv, andplans; a plan has a requireddescription,destinations({ cidr, ports }), and optionalsubnet_idsamong 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_connectionsin 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_idis set. Then the twoaws route53 associate-vpc-with-hosted-zonecommands, 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": {}
}
JSONvalet-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.