Integrations, proxy, client and tool environments
Integrations, proxy, client and tool environments
Section titled “Integrations, proxy, client and tool environments”All examples are unexecuted. Overview conventions apply; variables are optional except stated conditions. Resource fields do not automatically become environment variables. Deployment mail/secret/artifact backends differ from project resources.
SMTP, endpoint Redis and chat policy
Section titled “SMTP, endpoint Redis and chat policy”| Variable | Type; default | Range, scope and precedence |
|---|---|---|
VIAT_SMTP_HOST | string; unset / 未设置 | D. Trimmed nonblank enables deployment mail relay; required to save email alert rules. Not project SMTP resource configuration. |
VIAT_SMTP_TLS | enum; starttls | D. Trim/case-fold implicit/tls → implicit TLS; none/plain → plaintext; anything else including typo → STARTTLS. |
VIAT_SMTP_PORT | u16; 587 or 465 | D. 465 for implicit TLS, otherwise 587. Trimmed numeric override, 0 accepted by parser but not a useful relay port. |
VIAT_SMTP_USER | string; unset / 未设置 | D. Trimmed nonblank optional AUTH identity; use with password when relay requires it. |
VIAT_SMTP_PASSWORD | string; unset / 未设置 | D. Trimmed nonblank optional relay secret. Plaintext TLS mode can expose this on the network. |
VIAT_SMTP_FROM | string; user or viat@localhost | D. Trimmed nonblank sender; explicit > SMTP user > fallback. Relay/address validation still applies. |
VIAT_RATELIMIT_REDIS_URL | URL; unset / 未设置 | S. Optional shared endpoint rate-limit buckets; malformed configured URI fails startup. Outage falls back to per-instance memory limits; credential throttle stays PostgreSQL. |
VIAT_IM_BIND_BASE_URL | URL; unset / 未设置 | D + S route availability. Nonempty opts into self-service chat binding links. No automatic fallback to PUBLIC_URL. Operator must provide trusted external base and working binding UI. |
VIAT_IM_BIND_PAGE_PREFIX | path; derived / 推导 | D. Optional console path override; normalized leading/no trailing slash; explicit empty means root-mounted external UI. Default uses deployment base path + /ui. |
VIAT_IM_MAX_ACCOUNTS_PER_PROJECT | i64; 500 accounts | D. Positive project cap; invalid/0 → default. Not a performance guarantee. |
VIAT_IM_MAX_ACCOUNTS_TOTAL | i64; 2000 accounts | D. Positive deployment cap; project cap does not replace it. |
VIAT_IM_MAX_ACCOUNTS_PER_INSTANCE | i64 → usize; 200 accounts | D. Positive lease/connection budget per node; beyond it node stops acquiring accounts. |
VIAT_IM_BIND_LINK_MAX_TTL_HOURS | i64; 168 h | D. Positive maximum minted link lifetime (7d); individual link can lower. |
VIAT_IM_BIND_LINK_MAX_USES | i64 → i32; 500 uses | D. Positive then clamped 1..10000; link can request fewer uses. |
VIAT_IM_BIND_RATELIMIT_IP_PER_MINUTE | u32; 1200 requests/min | S. Binding route/IP throttle; 0 disables bucket. Separate from login throttle. |
VIAT_IM_BIND_RATELIMIT_IDENTITY_PER_MINUTE | u32; 60 requests/min | S. Binding route/identity throttle; 0 disables bucket. |
VIAT_IM_WEIXIN_HOSTS | CSV hosts; weixin.qq.com | D (connector config). Nonblank CSV replaces defaults, lowercased/trimmed; allowed host or subdomain. Not additive; preserve needed official suffixes. |
VIAT_IM_FEISHU_HOSTS | CSV hosts; feishu.cn,larksuite.com | D. Replaces Feishu/Lark allowed suffixes; same parsing rule. Gateway can receive account credentials; trust deliberately. |
VIAT_IM_DINGTALK_HOSTS | CSV hosts; dingtalk.com | D. Replaces DingTalk allowed suffixes. Not an inbound HTTP bind address. |
VIAT_SOCIAL_HOSTS | CSV hosts; see below / 见下文 | D. Replaces social exchange allowlist; host/subdomain validation, not DNS/IP sandbox. See full defaults below. |
Worker environment, clients and local tools
Section titled “Worker environment, clients and local tools”| Variable | Type; default | Range, scope and precedence |
|---|---|---|
VIAT_RUNTIME_ENV_PASSTHROUGH | CSV names; empty / 空 | W. Additional exact names or trailing-* prefixes. Unset source variables skipped. Explicit denylist still wins. Every forwarded value is visible to worker code; not a secret-vault interface. |
VIAT_CONFIG_DIR | path; discovered / 自动查找 | C, CLI/MCP. Nonblank override names config directory itself, not parent. Else search cwd ancestors for .viat/config.yaml, else cwd/.viat. No server effect. |
VIAT_NO_PROXY | boolean; off / 关闭 | C, CLI HTTP client. Trim/case-fold nonempty other than 0/false/no bypasses environment proxies. Does not change server egress or guarantee MCP transport uses it. |
VIAT_SERVER | URL; config server_url / 配置值 | C, MCP. Environment presence overrides legacy YAML server_url; missing both is startup error. Not a general server bind setting. |
VIAT_TOKEN | string; config token / 配置值 | C, MCP. Environment presence overrides legacy YAML token; required by loader if no token. Current CLI access/refresh fields are not automatically the same legacy field; prefer explicit least-privilege token for MCP. |
VIAT_PROJECT | string; current_project / 配置值 | C, MCP. Optional default project override; tools may also accept project. Not server project selection. |
VIAT_BUILD_WAIT_SECS | u64; 1800 s | C, CLI. Client —wait budget, 0 accepted; not server build timeout and does not cancel a server build when client stops waiting. |
VIAT_TEST_HOST_BIN | path; discovery / 自动查找 | C, CLI script testing. Override local viat-test-host executable; otherwise sibling installed binary then build-location discovery. Must match CLI release. |
VIAT_ENDPOINT_TEST_HOST_BIN | path; discovery / 自动查找 | C, CLI endpoint testing. Override viat-endpoint-test-host executable; matching release required. |
VIAT_ENDPOINT_TEST_DB | PostgreSQL URI; required for local endpoint tests / 本地端点测试必填 | C. Base PostgreSQL URL for disposable endpoint-test databases. Requires database-creation privileges; never point at production. Not the server DATABASE_URL replacement. |
VIAT_TEST_HOST | path; tool-provided / 工具注入 | Local SDK/test process. Selects real-DB resource test host. Not a deployment knob or permission bypass. |
Package sources, proxies and CAs: three trust domains
Section titled “Package sources, proxies and CAs: three trust domains”Server egress, dependency installation and user-script networking are different clients. Several platform clients explicitly use .no_proxy() (including shared HTTP/Vault); setting HTTPS_PROXY does not proxy every request. Prefer explicit resource proxy fields for http_api/graphql where supported and verify other backends separately. One global proxy is not evidence of one universal egress path.
Workers receive PATH, HOME and namespaced UV_*, PIP_*, BUN_CONFIG_*, NPM_CONFIG_*, npm_config_* by default. These open prefixes are interpreted by their tools; Viat does not validate every possible tool field:
| Variable/family | Type, default, override and scope |
|---|---|
PATH, HOME | W strings, inherited from server; image HOME is /home/viat. Executable/cache paths must exist with appropriate permissions. |
UV_INDEX_URL, UV_DEFAULT_INDEX, PIP_INDEX_URL | W URLs, tool defaults when absent; forwarded by default. Use trusted internal sources. Empty/precedence behavior belongs to the installed tool version. |
UV_NATIVE_TLS, other UV_*/PIP_* | W tool-defined boolean/string values with uv/pip defaults. Installer options, not Viat listener-TLS switches. |
npm_config_registry, NPM_CONFIG_*, BUN_CONFIG_* | W tool-defined values/defaults; configure trusted registries. Registry authentication enters the worker environment and can be read by script code. |
npm_config_proxy, npm_config_https_proxy | W URLs, tool defaults when absent; namespaced variables forward automatically, not universal script HTTP proxying. |
HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, NO_PROXY and lowercase variants | Strings/URLs, no Viat-specific default. Adoption by server clients varies. Not forwarded to workers by default: explicit opt-in required; wildcard/CIDR NO_PROXY syntax varies by client. |
SSL_CERT_FILE, SSL_CERT_DIR, REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE, NODE_EXTRA_CA_CERTS | File/directory paths, tool trust-store defaults. Not forwarded to workers by default; explicitly opt in and mount readable certificates. Some replace rather than extend trust; no variable works for every runtime. |
AWS_REGION, AWS_DEFAULT_REGION, AWS_PROFILE, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN | Server AWS SDK chain inputs; absent values use other SDK providers. Secrets Manager still needs a resolvable identity/region. Not aliases for Rust S3 explicit credentials. Core AWS credentials are blocked from passthrough. |
CARGO_HOME, RUSTUP_HOME, CARGO_TARGET_DIR, CARGO_BUILD_JOBS, CARGO_REGISTRIES_*_TOKEN, SSH_* | Compiler/local CLI tool configuration with tool-defined types/defaults/ranges, not runtime-worker server knobs. CARGO_*/SSH_* are blocked from runtime passthrough. The -build image sets Cargo/rustup directories. CLI compilation chooses VIAT_RUST_TARGET_DIR, then CARGO_TARGET_DIR, then a temporary target directory. |
PYTHONPATH | C; local CLI script testing appends an existing value. Not server interpreter selection. |
Unexecuted example for dependency proxying with explicit internal-host exclusions; forward the variables into the container and create new worker environments:
UV_INDEX_URL=https://packages.example.com/pypi/simplenpm_config_registry=https://packages.example.com/npm/VIAT_RUNTIME_ENV_PASSTHROUGH=HTTPS_PROXY,NO_PROXYHTTPS_PROXY=http://proxy.example.com:3128NO_PROXY=localhost,127.0.0.1,.example.internalRegardless of passthrough, DATABASE_URL, VIAT_MASTER_KEY, VIAT_JWT_SECRET, VAULT_ADDR, VAULT_TOKEN, the three core AWS credential names and CARGO_*/SSH_* are blocked. This is not automatic recognition of every secret name. Never use broad * rules to forward SMTP, artifact or custom credentials. Some resource objects still project credentials; see security boundaries.
Chat/social gateways and throttles
Section titled “Chat/social gateways and throttles”The full default VIAT_SOCIAL_HOSTS list is weixin.qq.com,dingtalk.com,alipay.com,alipaydev.com,douyin.com,toutiao.com,kuaishou.com. Lists match hosts/subdomains; a nonblank CSV replaces, not appends. A gateway receives app secrets and needs operator approval. An allowlist is not a DNS-rebinding firewall. Self-service binding is a separate opt-in, not enabled by VIAT_PUBLIC_URL; links are bearer capabilities to create accounts, so bound lifetime/use count and provide a functioning UI.
When endpoint Redis limiting fails, each node falls back to local buckets; combined admissions can approach the sum of each node’s allowance. Do not treat this as a strict fleet quota. Login identity throttling independently uses PostgreSQL. SMTP plaintext plus credentials warns but can still send AUTH unencrypted: use trusted TLS and correctly authorized relay/sender domains.
Client/test variables are not production tuning
Section titled “Client/test variables are not production tuning”VIAT_CONFIG_DIR names the directory itself, e.g. config.yaml inside /home/operator/viat-session. Session files contain access/refresh tokens: restrict directory permissions and exclude from version control. Prefer an explicit path across working directories. MCP’s legacy YAML loader reads token, not automatically the CLI access_token/refresh_token fields. Follow MCP for explicit credentials instead of inventing session values.
CLI project roles/local endpoint-test actors are operator/developer/admin/owner, not an invented viewer role. See the full CLI. Local endpoint testing creates disposable databases and executes code; it is not read-only. This page’s local endpoint-test instructions have not been executed as part of its configuration reference acceptance.
Development/verification inputs also include VIAT_UPDATE_BINDINGS (exactly 1 regenerates TS bindings), SQLX_OFFLINE (build-time query-cache selection), DOC_CONTRACT_EXAMPLES/DOC_EXAMPLE_ROOT/DOC_EXAMPLE_CLI (documentation fixtures), and MYSQL_TEST_URL/REDIS_TEST_URL/MONGO_TEST_URL/AMQP_TEST_URL/SQLSERVER_TEST_*/MINIO_TEST_*/KEYCLOAK_URL/LOCALSTACK_AWS/PGPASSWORD (integration-service fixtures). These have no production configuration default/reload contract. Do not expose test services on production just to avoid skipped tests.
VIAT_ARGS_JSON, VIAT_RESOURCES, VIAT_REQUEST, VIAT_PRINCIPAL, VIAT_REQUEST_BODY_FILE are per-run context injected into shell workers, not installer inputs. ___VIAT_*___ strings are protocol sentinels, not configuration.
Expanded examples VIAT_ARGS_NAME, VIAT_ARGS_USER_ID, VIAT_RESOURCE_DB_HOST, VIAT_RESOURCE_DB_PORT, VIAT_RESOURCE_DB_DATABASE and VIAT_RESOURCE_DB_URL are derived from per-run inputs/resource projections, not independent startup knobs. Internal tests also name VIAT_RESOURCE_DB_PASSWORD and VIAT_RESOURCE_DB_USER when checking that nested secret fields are not flattened. That does not guarantee that top-level projections or VIAT_RESOURCES are credential-free in 1.1.0. Do not log resource environment values or use these names as a credential-recovery API; the documented projection limitations apply to shell too.