truefoundry-applications

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中的通用澄清模板。

Applications

应用

List, inspect, and manage applications and deployments on TrueFoundry.

列出、查看和管理TrueFoundry上的应用与部署。

When to Use

适用场景

List, inspect, or manage deployed applications and their deployment history. Also supports creating deployments via API manifest for pre-built images.

列出、查看或管理已部署的应用及其部署历史，也支持通过API清单为预构建镜像创建部署。

When NOT to Use

不适用场景

User wants to deploy local code → prefer
```
deploy
```
skill; ask if the user wants another valid path
User wants workspace/cluster info → prefer
```
workspaces
```
skill; ask if the user wants another valid path
User wants to delete an application → guide them to the TrueFoundry UI (see "Deleting Applications" below)

</objective> <instructions>

用户想要部署本地代码 → 优先使用
```
deploy
```
skill；询问用户是否需要其他可行路径
用户想要工作区/集群信息 → 优先使用
```
workspaces
```
skill；询问用户是否需要其他可行路径
用户想要删除应用 → 引导他们前往TrueFoundry UI（参见下方「删除应用」部分）

</objective> <instructions>

Execution Priority

执行优先级

For simple read/list operations in this skill, always use MCP tool calls first:

```
tfy_applications_list
```
```
tfy_applications_list_deployments
```

If tool calls are unavailable because the MCP server is not configured, or a tool is missing, fall back automatically to direct API via

tfy-api.sh

对于本skill中的简单读取/列表操作，始终优先使用MCP工具调用：

```
tfy_applications_list
```
```
tfy_applications_list_deployments
```

如果因为MCP服务器未配置、工具缺失导致工具调用不可用，自动降级为通过

tfy-api.sh

调用直连API。

IMPORTANT: Deleting Applications

重要提示：删除应用

Deletion is NOT supported via CLI, API, or any agent tool. Do NOT call any delete endpoint or attempt to delete applications programmatically.

When a user asks to delete, remove, or destroy an application, do NOT list apps for selection. Instead, immediately respond with:

To delete an application, use the TrueFoundry dashboard:

1. Open your TrueFoundry dashboard (TFY_BASE_URL in your browser)
2. Navigate to **Deployments** → select the workspace
3. Find the application you want to delete
4. Click the **three-dot menu (⋮)** on the application card → **Delete**
5. Confirm the deletion when prompted

⚠️ This action is irreversible — all pods, endpoints, and deployment history for this application will be permanently removed.

Do NOT attempt to call any delete API on behalf of the user. Do NOT list applications to ask which one to delete. Simply provide the UI instructions above.

不支持通过CLI、API或任何agent工具执行删除操作。请勿调用任何删除接口，也不要尝试通过程序方式删除应用。

当用户要求删除、移除或销毁应用时，不要列出应用供用户选择，而是直接回复以下内容：

To delete an application, use the TrueFoundry dashboard:

1. Open your TrueFoundry dashboard (TFY_BASE_URL in your browser)
2. Navigate to **Deployments** → select the workspace
3. Find the application you want to delete
4. Click the **three-dot menu (⋮)** on the application card → **Delete**
5. Confirm the deletion when prompted

⚠️ This action is irreversible — all pods, endpoints, and deployment history for this application will be permanently removed.

不要代用户调用任何删除API，不要列出应用询问要删除哪一个，仅需提供上述UI操作指引即可。

List Applications

列出应用

When using direct API, set

TFY_API_SH

to the full path of this skill's

scripts/tfy-api.sh

. See

references/tfy-api-setup.md

for paths per agent.

使用直连API时，请将

TFY_API_SH

设置为当前skill的

scripts/tfy-api.sh

的完整路径。各agent对应的路径可查看

references/tfy-api-setup.md

。

Via Tool Call

通过工具调用

tfy_applications_list()
tfy_applications_list(filters={"workspace_fqn": "my-cluster:my-workspace"})
tfy_applications_list(filters={"application_name": "my-app"})
tfy_applications_list(app_id="app-id-here")

tfy_applications_list()
tfy_applications_list(filters={"workspace_fqn": "my-cluster:my-workspace"})
tfy_applications_list(filters={"application_name": "my-app"})
tfy_applications_list(app_id="app-id-here")

Via Direct API

通过直连API

bash

undefined

bash

undefined

Set the path to tfy-api.sh for your agent (example for Claude Code):

TFY_API_SH=~/.claude/skills/truefoundry-applications/scripts/tfy-api.sh

List all

$TFY_API_SH GET /api/svc/v1/apps

Filter by workspace

$TFY_API_SH GET '/api/svc/v1/apps?workspaceFqn=my-cluster:my-workspace'

Filter by name

$TFY_API_SH GET '/api/svc/v1/apps?applicationName=my-app'

Get by ID

$TFY_API_SH GET /api/svc/v1/apps/APP_ID

undefined

$TFY_API_SH GET /api/svc/v1/apps/APP_ID

undefined

Filter Parameters

过滤参数

Parameter	API Key	Description
`workspace_fqn`	`workspaceFqn`	Filter by workspace FQN
`application_name`	`applicationName`	Filter by app name
`cluster_id`	`clusterId`	Filter by cluster
`application_type`	`applicationType`	Filter: service, job, etc.
`name_search_query`	`nameSearchQuery`	Search by name substring

参数	API Key	说明
`workspace_fqn`	`workspaceFqn`	按工作区FQN过滤
`application_name`	`applicationName`	按应用名称过滤
`cluster_id`	`clusterId`	按集群过滤
`application_type`	`applicationType`	按类型过滤：service、job等
`name_search_query`	`nameSearchQuery`	按名称子串搜索

Presenting Applications

展示应用

Show as a table. Use

updatedAt

from the API response for "Last Deployed" (ISO 8601 timestamp — format as date/time for readability). Use

kind

for Type and

status

for Status.

Applications in my-cluster:my-workspace:
| Name           | Type    | Status   | Last Deployed      |
|----------------|---------|----------|--------------------|
| tfy-tool-server | service | RUNNING  | 2026-02-10 14:30   |
| data-pipeline  | job     | STOPPED  | 2026-02-08 09:15   |

以表格形式展示。使用API返回的

updatedAt

作为「最后部署时间」（ISO 8601时间戳，格式化为易读的日期/时间），使用

kind

作为类型，

status

作为状态。

Applications in my-cluster:my-workspace:
| Name           | Type    | Status   | Last Deployed      |
|----------------|---------|----------|--------------------|
| tfy-tool-server | service | RUNNING  | 2026-02-10 14:30   |
| data-pipeline  | job     | STOPPED  | 2026-02-08 09:15   |

List Deployments

列出部署记录

Via Tool Call

通过工具调用

tfy_applications_list_deployments(app_id="app-id")
tfy_applications_list_deployments(app_id="app-id", deployment_id="dep-id")

tfy_applications_list_deployments(app_id="app-id")
tfy_applications_list_deployments(app_id="app-id", deployment_id="dep-id")

Via Direct API

通过直连API

bash

undefined

bash

undefined

List deployments for an app

$TFY_API_SH GET /api/svc/v1/apps/APP_ID/deployments

Get specific deployment

$TFY_API_SH GET /api/svc/v1/apps/APP_ID/deployments/DEPLOYMENT_ID

undefined

$TFY_API_SH GET /api/svc/v1/apps/APP_ID/deployments/DEPLOYMENT_ID

undefined

Create Deployment (API)

创建部署（API）

For creating a deployment via API manifest (advanced — most users should use the

deploy

skill).

Use this section when:

User has their own manifest/JSON and wants direct API deployment
User explicitly requests API-based deployment instead of SDK/Python
User wants to deploy from a pre-built image (not local code)

For deploying local code, use the
deploy
skill instead.

用于通过API清单创建部署（进阶功能，大多数用户应使用

deploy

skill）。

适用场景：

用户已有自己的清单/JSON，想要直接通过API部署
用户明确要求使用API部署而非SDK/Python方式
用户想要部署预构建镜像（而非本地代码）

如果要部署本地代码，请使用
deploy
skill。

Service Manifest Structure

服务清单结构

A basic TrueFoundry service manifest looks like this:

json

{
  "manifest": {
    "kind": "Service",
    "name": "my-app",
    "image": {
      "type": "image",
      "image_uri": "nginx:latest"
    },
    "ports": [
      {
        "port": 8000,
        "protocol": "TCP",
        "expose": false
      }
    ],
    "resources": {
      "cpu_request": 0.25,
      "cpu_limit": 0.5,
      "memory_request": 256,
      "memory_limit": 512
    },
    "env": {
      "APP_MODE": "production",
      "THIRD_PARTY_API_KEY": "tfy-secret://my-org:my-app-secrets:THIRD_PARTY_API_KEY"
    },
    "replicas": {
      "min": 1,
      "max": 1
    }
  },
  "workspaceId": "ws-id-here"
}

Key Fields:

```
kind
```
— "Service" for long-running services, "Job" for batch jobs
```
name
```
— Unique application name

image.image_uri

— Docker image (e.g.,

nginx:latest

ghcr.io/org/app:v1.0

)

```
ports
```
— Array of port configs (port, protocol, expose flag)
```
resources
```
— CPU (cores) and memory (MB) requests/limits
```
env
```
— Environment variables as key-value pairs. Security: Never include raw secret values (passwords, API keys, tokens) in manifests. Use
```
tfy-secret://
```
references for all sensitive environment variables. See the
```
secrets
```
skill.
```
replicas
```
— Min/max replica count (for autoscaling)
```
workspaceId
```
— Workspace ID (not FQN) where the app will be deployed

基础的TrueFoundry服务清单如下：

json

{
  "manifest": {
    "kind": "Service",
    "name": "my-app",
    "image": {
      "type": "image",
      "image_uri": "nginx:latest"
    },
    "ports": [
      {
        "port": 8000,
        "protocol": "TCP",
        "expose": false
      }
    ],
    "resources": {
      "cpu_request": 0.25,
      "cpu_limit": 0.5,
      "memory_request": 256,
      "memory_limit": 512
    },
    "env": {
      "APP_MODE": "production",
      "THIRD_PARTY_API_KEY": "tfy-secret://my-org:my-app-secrets:THIRD_PARTY_API_KEY"
    },
    "replicas": {
      "min": 1,
      "max": 1
    }
  },
  "workspaceId": "ws-id-here"
}

关键字段：

```
kind
```
— 长时间运行的服务填"Service"，批量任务填"Job"
```
name
```
— 唯一的应用名称

image.image_uri

— Docker镜像（例如

nginx:latest

、

ghcr.io/org/app:v1.0

）

```
ports
```
— 端口配置数组（端口、协议、暴露标识）
```
resources
```
— CPU（核数）和内存（MB）的请求/限制
```
env
```
— 键值对形式的环境变量。安全提示： 永远不要在清单中包含原始的敏感值（密码、API密钥、令牌），所有敏感环境变量都请使用
```
tfy-secret://
```
引用，参见
```
secrets
```
skill。
```
replicas
```
— 最小/最大副本数（用于自动扩缩容）
```
workspaceId
```
— 应用要部署到的工作区ID（不是FQN）

Before Submitting

提交前检查

Security: Credential Handling
NEVER embed raw API keys, passwords, or tokens in manifest
env
fields.
Always use
tfy-secret://
references for sensitive environment variables.
If the user provides a raw credential, warn them and suggest creating a TrueFoundry secret group first (use the
secrets
skill).
Never ask the user to paste secret values directly into the conversation.

ALWAYS confirm with the user before creating a deployment:

Service name — What should the app be called?
Image — Full image URI (e.g.,
```
nginx:latest
```
,
```
ghcr.io/user/app:tag
```
)
Resources — CPU request/limit (cores), memory request/limit (MB)
Ports — Which ports to expose, protocols (TCP/UDP), expose to internet?
Environment variables — Any env vars needed? (For sensitive values, only accept
```
tfy-secret://
```
references — never inline credentials in manifests)
Replicas — How many instances? (min/max for autoscaling)
Workspace ID — Which workspace to deploy to?

Present this summary and ask for confirmation before making the API call.

安全：凭证处理
永远不要在清单的
env
字段中嵌入原始API密钥、密码或令牌。
敏感环境变量始终使用
tfy-secret://
引用。
如果用户提供了原始凭证，需要提醒对方，建议先创建TrueFoundry密钥组（使用
secrets
skill）。
永远不要要求用户直接在对话中粘贴敏感值。

创建部署前必须和用户确认以下信息：

服务名称 — 应用应该叫什么？
镜像 — 完整的镜像URI（例如
```
nginx:latest
```
、
```
ghcr.io/user/app:tag
```
）
资源配置 — CPU请求/限制（核数）、内存请求/限制（MB）
端口配置 — 需要暴露哪些端口、协议（TCP/UDP）、是否暴露到公网？
环境变量 — 需要哪些环境变量？（敏感值仅接受
```
tfy-secret://
```
引用 — 永远不要在清单中内联凭证）
副本数 — 需要多少个实例？（自动扩缩容的最小/最大值）
工作区ID — 要部署到哪个工作区？

在发起API调用前，展示上述信息摘要并请求用户确认。

Via Tool Call

通过工具调用

tfy_applications_create_deployment(
    manifest={
        "kind": "Service",
        "name": "my-app",
        "image": {"type": "image", "image_uri": "nginx:latest"},
        "ports": [{"port": 8000, "protocol": "TCP", "expose": false}],
        "resources": {"cpu_request": 0.25, "cpu_limit": 0.5, "memory_request": 256, "memory_limit": 512},
        "env": {"APP_MODE": "production", "THIRD_PARTY_API_KEY": "tfy-secret://my-org:my-app-secrets:THIRD_PARTY_API_KEY"},
        "replicas": {"min": 1, "max": 1}
    },
    options={"workspace_id": "ws-id-here", "force_deploy": true}
)

Note: This requires human approval (HITL) when using tool calls.

tfy_applications_create_deployment(
    manifest={
        "kind": "Service",
        "name": "my-app",
        "image": {"type": "image", "image_uri": "nginx:latest"},
        "ports": [{"port": 8000, "protocol": "TCP", "expose": false}],
        "resources": {"cpu_request": 0.25, "cpu_limit": 0.5, "memory_request": 256, "memory_limit": 512},
        "env": {"APP_MODE": "production", "THIRD_PARTY_API_KEY": "tfy-secret://my-org:my-app-secrets:THIRD_PARTY_API_KEY"},
        "replicas": {"min": 1, "max": 1}
    },
    options={"workspace_id": "ws-id-here", "force_deploy": true}
)

注意： 使用工具调用时需要人工审批（HITL）。

Via Direct API

通过直连API

bash

$TFY_API_SH PUT /api/svc/v1/apps '{
  "manifest": {
    "kind": "Service",
    "name": "my-app",
    "image": {"type": "image", "image_uri": "nginx:latest"},
    "ports": [{"port": 8000, "protocol": "TCP", "expose": false}],
    "resources": {"cpu_request": 0.25, "cpu_limit": 0.5, "memory_request": 256, "memory_limit": 512},
    "env": {"APP_MODE": "production", "THIRD_PARTY_API_KEY": "tfy-secret://my-org:my-app-secrets:THIRD_PARTY_API_KEY"},
    "replicas": {"min": 1, "max": 1}
  },
  "workspaceId": "ws-id-here"
}'

bash

$TFY_API_SH PUT /api/svc/v1/apps '{
  "manifest": {
    "kind": "Service",
    "name": "my-app",
    "image": {"type": "image", "image_uri": "nginx:latest"},
    "ports": [{"port": 8000, "protocol": "TCP", "expose": false}],
    "resources": {"cpu_request": 0.25, "cpu_limit": 0.5, "memory_request": 256, "memory_limit": 512},
    "env": {"APP_MODE": "production", "THIRD_PARTY_API_KEY": "tfy-secret://my-org:my-app-secrets:THIRD_PARTY_API_KEY"},
    "replicas": {"min": 1, "max": 1}
  },
  "workspaceId": "ws-id-here"
}'

Common Deployment Patterns

常见部署模式

Web service (exposed to internet with public URL):

The

host

must match one of the cluster's

base_domains

. Look up base domains first:

bash

$TFY_API_SH GET /api/svc/v1/clusters/CLUSTER_ID

Web服务（暴露到公网，有公共URL）：

host

必须匹配集群的其中一个

base_domains

，先查询基础域名：

bash

$TFY_API_SH GET /api/svc/v1/clusters/CLUSTER_ID

→ look for base_domains, pick the wildcard one (e.g., "*.ml.your-org.truefoundry.cloud")

→ strip "*." to get the base domain: "ml.your-org.truefoundry.cloud"

→ construct host: "{service-name}-{workspace-name}.{base_domain}"


```json
{
  "ports": [{
    "port": 8080,
    "protocol": "TCP",
    "expose": true,
    "host": "my-app-dev-ws.ml.your-org.truefoundry.cloud",
    "app_protocol": "http"
  }],
  "replicas": {"min": 2, "max": 5}
}

If
host
does not match a cluster base domain, deploy will fail with: "Provided host is not configured in cluster".

Internal service (not exposed):

json

{
  "ports": [{"port": 8000, "protocol": "TCP", "expose": false}],
  "replicas": {"min": 1, "max": 1}
}

Resource-intensive service:

json

{
  "resources": {
    "cpu_request": 1.0,
    "cpu_limit": 2.0,
    "memory_request": 2048,
    "memory_limit": 4096
  }
}

</instructions>

<success_criteria>


```json
{
  "ports": [{
    "port": 8080,
    "protocol": "TCP",
    "expose": true,
    "host": "my-app-dev-ws.ml.your-org.truefoundry.cloud",
    "app_protocol": "http"
  }],
  "replicas": {"min": 2, "max": 5}
}

如果
host
不匹配集群的基础域名，部署会失败，报错："Provided host is not configured in cluster"。

内部服务（不对外暴露）：

json

{
  "ports": [{"port": 8000, "protocol": "TCP", "expose": false}],
  "replicas": {"min": 1, "max": 1}
}

资源消耗高的服务：

json

{
  "resources": {
    "cpu_request": 1.0,
    "cpu_limit": 2.0,
    "memory_request": 2048,
    "memory_limit": 4096
  }
}

</instructions>

<success_criteria>

Success Criteria

成功标准

The user can see the status of their deployed applications in a clear, formatted table
Unhealthy or stopped deployments are identified with actionable next steps (check logs, redeploy)
The agent has filtered results by the correct workspace when the user specified one
The user can find a specific application by name, ID, or workspace
Deployment details (replicas, resources, image, ports) are surfaced when the user asks for more info

</success_criteria>

用户可以通过清晰的格式化表格查看已部署应用的状态
可以识别出不健康或已停止的部署，并提供可落地的下一步操作（查看日志、重新部署）
当用户指定工作区时，agent可以正确按该工作区过滤结果
用户可以通过名称、ID或工作区查找特定应用
当用户要求查看更多信息时，可以展示部署详情（副本数、资源配置、镜像、端口）

</success_criteria>

Composability

组合使用

After listing apps: Use
```
logs
```
skill to check logs,
```
deploy
```
skill to redeploy
After deploy: Use this skill to verify the deployment succeeded
Check jobs: Use
```
jobs
```
skill for job-specific run details
Find workspace first: Use
```
workspaces
```
skill to get workspace FQN for filtering

</references> <troubleshooting>

列出应用后：使用
```
logs
```
skill查看日志，使用
```
deploy
```
skill重新部署
部署完成后：使用本skill验证部署是否成功
查看任务：使用
```
jobs
```
skill获取任务专属的运行详情
先查找工作区：使用
```
workspaces
```
skill获取用于过滤的工作区FQN

</references> <troubleshooting>

Error Handling

错误处理

No Applications Found

未找到应用

No applications found. Check:
- Workspace FQN is correct
- You have apps deployed in this workspace
- Your API key has access to this workspace

No applications found. Check:
- Workspace FQN is correct
- You have apps deployed in this workspace
- Your API key has access to this workspace

Application Not Found

应用不存在

Application ID not found. List apps first to find the correct ID.

Application ID not found. List apps first to find the correct ID.

Permission Denied

权限不足

Cannot access this application. Check your API key permissions.

</troubleshooting>

Cannot access this application. Check your API key permissions.

</troubleshooting>