Back to Details

truefoundry-deploy

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Routing note: For ambiguous user intents, use the shared clarification templates in references/intent-clarification.md.
路由注意：如果用户意图不明确，请使用 references/intent-clarification.md 中的通用澄清模板。

Deploy to TrueFoundry

部署到TrueFoundry

Route user intent to the right deployment workflow. Load only the references you need.
将用户意图路由到正确的部署工作流。仅加载你需要的参考文档。

Intent Router

意图路由器

User IntentActionReference
"deploy", "deploy my app", "ship this"Single HTTP servicedeploy-service.md
"mount this file", "mount config file", "mount certificate file", "mount key file"Single service with file mounts (no image rebuild)deploy-service.md
"tfy apply", "apply manifest", "deploy from yaml"Declarative manifest applydeploy-apply.md
"deploy everything", "full stack", docker-compose, "docker-compose.yaml", "compose.yaml"Multi-service: use compose as source of truthdeploy-multi.md + compose-translation.md
"async service", "queue consumer", "worker"Async/queue servicedeploy-async.md
"deploy LLM", "serve model"Model serving intent (may be ambiguous)Ask user: dedicated model serving (
llm-deploy
) or generic service deploy (
deploy
)
"deploy helm chart"Helm chart intentConfirm Helm path and collect chart details, then proceed with 
helm
workflow
"deploy postgres docker", "dockerized postgres", "deploy redis docker", "database in docker/container"Containerized database intentProceed with 
deploy
workflow (do not route to Helm)
"deploy database", "deploy postgres", "deploy redis"Ambiguous infra intentAsk user: Helm chart (
helm
) or containerized service (
deploy
)
Load only the reference file matching the user's intent. Do not preload all references.
用户意图动作参考文档
"deploy", "deploy my app", "ship this"单HTTP服务deploy-service.md
"mount this file", "mount config file", "mount certificate file", "mount key file"带文件挂载的单服务（无需重建镜像）deploy-service.md
"tfy apply", "apply manifest", "deploy from yaml"声明式清单应用deploy-apply.md
"deploy everything", "full stack", docker-compose, "docker-compose.yaml", "compose.yaml"多服务：以compose为事实来源deploy-multi.md + compose-translation.md
"async service", "queue consumer", "worker"异步/队列服务deploy-async.md
"deploy LLM", "serve model"模型服务意图（可能存在歧义）询问用户：专用模型服务（
llm-deploy
）还是通用服务部署（
deploy
）
"deploy helm chart"Helm chart意图确认Helm路径并收集chart详情，然后执行
helm
工作流
"deploy postgres docker", "dockerized postgres", "deploy redis docker", "database in docker/container"容器化数据库意图执行
deploy
工作流（不要路由到Helm）
"deploy database", "deploy postgres", "deploy redis"模糊的基础设施意图询问用户：Helm chart（
helm
）还是容器化服务（
deploy
）
仅加载与用户意图匹配的参考文件。 不要预加载所有参考文档。

Prerequisites (All Workflows)

前置要求（所有工作流）

bash
undefined
bash
undefined

1. Check credentials

1. 检查凭证

grep '^TFY_' .env 2>/dev/null || true env | grep '^TFY_' 2>/dev/null || true
grep '^TFY_' .env 2>/dev/null || true env | grep '^TFY_' 2>/dev/null || true

2. Derive TFY_HOST for CLI (MUST run before any tfy command)

2. 为CLI推导TFY_HOST（执行任何tfy命令前必须运行）

export TFY_HOST="${TFY_HOST:-${TFY_BASE_URL%/}}"
export TFY_HOST="${TFY_HOST:-${TFY_BASE_URL%/}}"

3. Check CLI

3. 检查CLI

tfy --version 2>/dev/null || echo "Install: pip install 'truefoundry==0.5.0'"
tfy --version 2>/dev/null || echo "Install: pip install 'truefoundry==0.5.0'"

4. Check for existing manifests

4. 检查现有清单

ls tfy-manifest.yaml truefoundry.yaml 2>/dev/null

- `TFY_BASE_URL` and `TFY_API_KEY` must be set (env or `.env`).
- **`TFY_HOST` must be set before any `tfy` CLI command.** The export above handles this automatically.
- `TFY_WORKSPACE_FQN` required. **HARD RULE: Never auto-pick a workspace. Always ask the user to confirm, even if only one workspace exists or a preference is saved.** See `references/prerequisites.md` for the full workspace confirmation flow.
- For full credential setup, see `references/prerequisites.md`.

> **WARNING:** Never use `source .env`. The `tfy-api.sh` script handles `.env` parsing automatically. For shell access: `grep KEY .env | cut -d= -f2-`
ls tfy-manifest.yaml truefoundry.yaml 2>/dev/null

- 必须设置`TFY_BASE_URL`和`TFY_API_KEY`（环境变量或`.env`文件中）。
- **在执行任何`tfy` CLI命令前必须设置`TFY_HOST`。** 上面的导出命令会自动处理这一点。
- 需要`TFY_WORKSPACE_FQN`。**硬性规则：永远不要自动选择工作区。即使用户只有一个工作区或保存了偏好，也要始终请用户确认。** 完整的工作区确认流程请查看`references/prerequisites.md`。
- 完整的凭证设置说明请查看`references/prerequisites.md`。

> **警告：** 永远不要使用`source .env`。`tfy-api.sh`脚本会自动解析`.env`。如需获取shell访问权限，请使用：`grep KEY .env | cut -d= -f2-`

Quick Ops (Inline)

快速操作（内联）

Apply a manifest (most common)

应用清单（最常用）

bash
undefined
bash
undefined

tfy CLI expects TFY_HOST when TFY_API_KEY is set

当TFY_API_KEY已设置时，tfy CLI需要TFY_HOST参数

export TFY_HOST="${TFY_HOST:-${TFY_BASE_URL%/}}"
export TFY_HOST="${TFY_HOST:-${TFY_BASE_URL%/}}"

Preview changes

预览变更

tfy apply -f tfy-manifest.yaml --dry-run --show-diff
tfy apply -f tfy-manifest.yaml --dry-run --show-diff

Apply

应用变更

tfy apply -f tfy-manifest.yaml
undefined
tfy apply -f tfy-manifest.yaml
undefined

Deploy from source (local code or git)

从源码部署（本地代码或git仓库）

bash
undefined
bash
undefined

tfy CLI expects TFY_HOST when TFY_API_KEY is set

当TFY_API_KEY已设置时，tfy CLI需要TFY_HOST参数

export TFY_HOST="${TFY_HOST:-${TFY_BASE_URL%/}}"
export TFY_HOST="${TFY_HOST:-${TFY_BASE_URL%/}}"

tfy deploy builds remotely — use for local code or git sources

tfy deploy会执行远程构建 — 适用于本地代码或git源码

tfy deploy -f truefoundry.yaml --no-wait

> **`tfy apply` does NOT support `build_source`.** Use `tfy deploy -f` for source-based deployments.
tfy deploy -f truefoundry.yaml --no-wait

> **`tfy apply`不支持`build_source`。** 基于源码的部署请使用`tfy deploy -f`

Minimal service manifest template

最简服务清单模板

yaml
name: my-service
type: service
image:
  type: image
  image_uri: docker.io/myorg/my-api:v1.0
ports:
  - port: 8000
    expose: true
    app_protocol: http
resources:
  cpu_request: 0.5
  cpu_limit: 1
  memory_request: 512
  memory_limit: 1024
  ephemeral_storage_request: 1000
  ephemeral_storage_limit: 2000
env:
  LOG_LEVEL: info
replicas: 1
workspace_fqn: "WORKSPACE_FQN_HERE"
yaml
name: my-service
type: service
image:
  type: image
  image_uri: docker.io/myorg/my-api:v1.0
ports:
  - port: 8000
    expose: true
    app_protocol: http
resources:
  cpu_request: 0.5
  cpu_limit: 1
  memory_request: 512
  memory_limit: 1024
  ephemeral_storage_request: 1000
  ephemeral_storage_limit: 2000
env:
  LOG_LEVEL: info
replicas: 1
workspace_fqn: "WORKSPACE_FQN_HERE"

Check deployment status

检查部署状态

bash
TFY_API_SH=~/.claude/skills/truefoundry-deploy/scripts/tfy-api.sh
bash $TFY_API_SH GET '/api/svc/v1/apps?workspaceFqn=WORKSPACE_FQN&applicationName=SERVICE_NAME'
Or use the 
applications
skill.
bash
TFY_API_SH=~/.claude/skills/truefoundry-deploy/scripts/tfy-api.sh
bash $TFY_API_SH GET '/api/svc/v1/apps?workspaceFqn=WORKSPACE_FQN&applicationName=SERVICE_NAME'
或者使用
applications
skill。

Post-Deploy Verification (Automatic)

部署后验证（自动）

After any successful deploy/apply action, verify deployment status automatically without asking an extra prompt.
Preferred verification path:
  1. Use MCP tool call first:
tfy_applications_list(filters={"workspace_fqn": "WORKSPACE_FQN", "application_name": "SERVICE_NAME"})
  1. If MCP tool calls are unavailable, fall back to:
bash
TFY_API_SH=~/.claude/skills/truefoundry-deploy/scripts/tfy-api.sh
bash $TFY_API_SH GET '/api/svc/v1/apps?workspaceFqn=WORKSPACE_FQN&applicationName=SERVICE_NAME'
Always report the observed status (
BUILDING
, 
DEPLOYING
, 
DEPLOY_SUCCESS
, 
DEPLOY_FAILED
, etc.) in the same response.
If status is 
DEPLOY_FAILED
or 
BUILD_FAILED
, follow deploy-debugging.md: fetch logs (use 
logs
skill), identify cause, apply one fix and retry once; if still failed, report to user with summary and log excerpt and stop.
任何部署/应用操作成功后，无需额外询问即可自动验证部署状态。
推荐的验证路径：
  1. 优先使用MCP工具调用：
tfy_applications_list(filters={"workspace_fqn": "WORKSPACE_FQN", "application_name": "SERVICE_NAME"})
  1. 如果无法使用MCP工具调用，降级使用：
bash
TFY_API_SH=~/.claude/skills/truefoundry-deploy/scripts/tfy-api.sh
bash $TFY_API_SH GET '/api/svc/v1/apps?workspaceFqn=WORKSPACE_FQN&applicationName=SERVICE_NAME'
请始终在同一条响应中返回观察到的状态（
BUILDING
、
DEPLOYING
、
DEPLOY_SUCCESS
、
DEPLOY_FAILED
等）。
如果状态为
DEPLOY_FAILED
或
BUILD_FAILED
，请遵循deploy-debugging.md：获取日志（使用
logs
skill）、定位问题、应用修复并重试一次；如果仍然失败，向用户返回摘要和日志片段后终止流程。

REST API fallback (when CLI unavailable)

REST API降级方案（CLI不可用时）

See 
references/cli-fallback.md
for converting YAML to JSON and deploying via 
tfy-api.sh
.
如需将YAML转换为JSON并通过
tfy-api.sh
部署，请查看
references/cli-fallback.md
。

Auto-Detection: Single vs Multi-Service

自动检测：单服务vs多服务

Before creating any manifest, scan the project:
  1. Check for 
    docker-compose.yml
    , 
    docker-compose.yaml
    , or 
    compose.yaml
    first.     If present (or user mentions docker-compose), treat it as the primary source of truth: load deploy-multi.md and compose-translation.md, generate manifests from the compose file, wire services per service-wiring.md, then complete deployment. Do not ask the user to manually create manifests when a compose file exists.
  2. Look for multiple 
    Dockerfile
    files across the project
  3. Check for service directories with their own dependency files in 
    services/
    , 
    apps/
    , 
    frontend/
    , 
    backend/
  • Compose file present or user says "docker-compose" → Multi-service from compose: load 
    deploy-multi.md
    + 
    compose-translation.md
  • Single service → Load 
    references/deploy-service.md
  • Multiple services (no compose) → Load 
    references/deploy-multi.md
在创建任何清单前，请先扫描项目：
  1. 优先检查是否存在
    docker-compose.yml
    、
    docker-compose.yaml
    或
    compose.yaml
    。     如果存在（或用户提到docker-compose），将其视为首要事实来源：加载deploy-multi.md和compose-translation.md，从compose文件生成清单，按照service-wiring.md连接服务，然后完成部署。当存在compose文件时，不要要求用户手动创建清单。
  2. 扫描项目中是否存在多个
    Dockerfile
    文件
  3. 检查
    services/
    、
    apps/
    、
    frontend/
    、
    backend/
    目录下是否存在自带依赖文件的服务目录
  • 存在Compose文件或用户提到"docker-compose" → 基于compose的多服务部署：加载
    deploy-multi.md
    + 
    compose-translation.md
  • 单服务 → 加载
    references/deploy-service.md
  • 多服务（无compose） → 加载
    references/deploy-multi.md

Secrets Handling (Default: Secret Groups)

密钥处理（默认：密钥组）

By default, do not put secrets in env as raw values. For any env var that looks sensitive (e.g. 
*PASSWORD*
, 
*SECRET*
, 
*TOKEN*
, 
*KEY*
, 
*API_KEY*
, 
*DATABASE_URL*
with credentials):
  1. Create a secret group (use the 
    secrets
    skill or API) with those keys.
  2. Reference them in the manifest with 
    tfy-secret://
    format.
yaml
env:
  LOG_LEVEL: info                                              # plain text OK
  DB_PASSWORD: tfy-secret://my-org:my-service-secrets:DB_PASSWORD  # sensitive
Pattern: 
tfy-secret://<TENANT_NAME>:<SECRET_GROUP_NAME>:<SECRET_KEY>
where TENANT_NAME is the subdomain of 
TFY_BASE_URL
.
Use the 
secrets
skill for guided secret group creation. For the full workflow, see 
references/deploy-service.md
(Secrets Handling section).
默认情况下，不要将密钥以明文形式放在环境变量中。 对于任何看起来敏感的环境变量（例如
*PASSWORD*
、
*SECRET*
、
*TOKEN*
、
*KEY*
、
*API_KEY*
、带凭证的
*DATABASE_URL*
）：
  1. （使用
    secrets
    skill或API）创建包含这些密钥的密钥组。
  2. 在清单中使用
    tfy-secret://
    格式引用它们。
yaml
env:
  LOG_LEVEL: info                                              # 明文允许
  DB_PASSWORD: tfy-secret://my-org:my-service-secrets:DB_PASSWORD  # 敏感数据
格式：
tfy-secret://<TENANT_NAME>:<SECRET_GROUP_NAME>:<SECRET_KEY>
，其中TENANT_NAME是
TFY_BASE_URL
的子域名。
如需引导式创建密钥组，请使用
secrets
skill。完整工作流请查看
references/deploy-service.md
（密钥处理章节）。

File Mounts (Config, Secrets, Shared Data)

文件挂载（配置、密钥、共享数据）

When users ask to mount files into a deployment, prefer manifest 
mounts
over Dockerfile edits:
  • type: secret
    for sensitive file content (keys, certs, credentials)
  • type: config_map
    for non-sensitive config files
  • type: volume
    for writable/shared runtime data
See 
references/deploy-service.md
(File Mounts section) for the end-to-end workflow.
当用户要求将文件挂载到部署中时，优先使用清单的
mounts
配置而非修改Dockerfile：
  • type: secret
    用于敏感文件内容（密钥、证书、凭证）
  • type: config_map
    用于非敏感配置文件
  • type: volume
    用于可写/共享运行时数据
端到端工作流请查看
references/deploy-service.md
（文件挂载章节）。

Shared References

共享参考文档

These references are available for all workflows — load as needed:
ReferenceContents
manifest-schema.md
Complete YAML field reference (single source of truth)
manifest-defaults.md
Per-service-type defaults with YAML templates
cli-fallback.md
CLI detection and REST API fallback pattern
cluster-discovery.md
Extract cluster ID, base domains, available GPUs
resource-estimation.md
CPU, memory, GPU sizing rules of thumb
health-probes.md
Startup, readiness, liveness probe configuration
gpu-reference.md
GPU types and VRAM reference
container-versions.md
Pinned container image versions
prerequisites.md
Credential setup and .env configuration
rest-api-manifest.md
Full REST API manifest reference
参考文档内容
manifest-schema.md
完整YAML字段参考（唯一事实来源）
manifest-defaults.md
各服务类型默认配置与YAML模板
cli-fallback.md
CLI检测与REST API降级方案
cluster-discovery.md
提取集群ID、基础域名、可用GPU
resource-estimation.md
CPU、内存、GPU sizing经验规则
health-probes.md
启动探针、就绪探针、存活探针配置
gpu-reference.md
GPU类型与显存参考
container-versions.md
固定版本的容器镜像
prerequisites.md
凭证设置与.env配置
rest-api-manifest.md
完整REST API清单参考

Workflow-Specific References

工作流专属参考文档

ReferenceUsed By
deploy-api-examples.md
deploy-service
deploy-errors.md
deploy-service
deploy-scaling.md
deploy-service
load-analysis-questions.md
deploy-service
codebase-analysis.md
deploy-service
tfy-apply-cicd.md
deploy-apply
tfy-apply-extra-manifests.md
deploy-apply
compose-translation.md
deploy-multi
dependency-graph.md
deploy-multi
multi-service-errors.md
deploy-multi
multi-service-patterns.md
deploy-multi
service-wiring.md
deploy-multi
deploy-debugging.md
All deploy/apply (when status is failed)
async-errors.md
deploy-async
async-queue-configs.md
deploy-async
async-python-library.md
deploy-async
async-sidecar-deploy.md
deploy-async
参考文档适用工作流
deploy-api-examples.md
deploy-service
deploy-errors.md
deploy-service
deploy-scaling.md
deploy-service
load-analysis-questions.md
deploy-service
codebase-analysis.md
deploy-service
tfy-apply-cicd.md
deploy-apply
tfy-apply-extra-manifests.md
deploy-apply
compose-translation.md
deploy-multi
dependency-graph.md
deploy-multi
multi-service-errors.md
deploy-multi
multi-service-patterns.md
deploy-multi
service-wiring.md
deploy-multi
deploy-debugging.md
所有deploy/apply（状态失败时）
async-errors.md
deploy-async
async-queue-configs.md
deploy-async
async-python-library.md
deploy-async
async-sidecar-deploy.md
deploy-async

Composability

可组合性

  • Find workspace: Use 
    workspaces
    skill
  • Check what's deployed: Use 
    applications
    skill
  • View logs: Use 
    logs
    skill
  • Manage secrets: Use 
    secrets
    skill
  • Deploy Helm charts: Use 
    helm
    skill
  • Deploy LLMs: Use 
    llm-deploy
    skill
  • Test after deploy: Use 
    service-test
    skill
  • 查找工作区：使用
    workspaces
    skill
  • 检查已部署内容：使用
    applications
    skill
  • 查看日志：使用
    logs
    skill
  • 管理密钥：使用
    secrets
    skill
  • 部署Helm charts：使用
    helm
    skill
  • 部署LLMs：使用
    llm-deploy
    skill
  • 部署后测试：使用
    service-test
    skill

Success Criteria

成功标准

  • User confirmed service name, resources, port, and deployment source before deploying
  • Deployment URL and status reported back to the user
  • Deployment status verified automatically immediately after apply/deploy (no extra prompt)
  • Health probes configured for production deployments
  • Secrets stored securely (not hardcoded in manifests)
  • For multi-service: all services wired together and working end-to-end
  • 部署前用户已确认服务名称、资源、端口和部署源
  • 已向用户返回部署URL和状态
  • 应用/部署完成后立即自动验证了部署状态（无额外询问）
  • 生产环境部署已配置健康检查探针
  • 密钥已安全存储（未硬编码在清单中）
  • 多服务部署：所有服务已互相连接且端到端正常运行