truefoundry-onboarding

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中共享的意图澄清模板。

TrueFoundry Onboarding

TrueFoundry 新手上路

Guide a new user from zero to a working TrueFoundry setup: account creation, credential configuration, and first successful API call.

引导新用户从零开始搭建可用的TrueFoundry环境：创建账号、配置凭证、首次成功调用API。

When to Use

适用场景

User has no TrueFoundry account yet
User says "get started", "set up", "register", "onboard", or "I'm new to TrueFoundry"
Credentials (
```
TFY_BASE_URL
```
,
```
TFY_API_KEY
```
) are missing and the user hasn't set them up before
User explicitly asks how to create an account or get an API key

用户还没有TrueFoundry账号
用户提及「入门」、「设置」、「注册」、「新手上路」或者「我刚接触TrueFoundry」
凭证(
```
TFY_BASE_URL
```
、
```
TFY_API_KEY
```
)缺失，且用户此前没有完成过配置
用户明确询问如何创建账号或获取API密钥

When NOT to Use

不适用场景

User already has credentials and wants to check status → prefer
```
status
```
skill
User wants to manage existing tokens → prefer
```
access-tokens
```
skill
User wants to deploy → prefer
```
deploy
```
skill (it has its own preflight)
User wants to list workspaces → prefer
```
workspaces
```
skill

</objective> <instructions>

用户已经配置好凭证，想要检查状态 → 优先使用
```
status
```
技能
用户想要管理已有令牌 → 优先使用
```
access-tokens
```
技能
用户想要部署服务 → 优先使用
```
deploy
```
技能（自带前置检查流程）
用户想要列出工作区 → 优先使用
```
workspaces
```
技能

</objective> <instructions>

Step 1: Detect Current State

步骤1：检测当前状态

Before starting the registration flow, check if the user already has credentials configured.

bash

echo "TFY_BASE_URL: ${TFY_BASE_URL:-(not set)}"
echo "TFY_HOST: ${TFY_HOST:-(not set)}"
echo "TFY_API_KEY: ${TFY_API_KEY:+(set)}${TFY_API_KEY:-(not set)}"
[ -f .env ] && grep -c '^TFY_' .env 2>/dev/null && echo ".env has TFY_ vars" || echo "No .env with TFY_ vars"

If credentials are already set, skip to Step 5: Verify Connection.

If credentials are missing, ask the user:

Do you already have a TrueFoundry account? If yes, I'll help you configure credentials. If not, I'll walk you through creating one.

Has account → skip to Step 3: Configure Credentials
No account → continue to Step 2

在启动注册流程前，先检查用户是否已经配置好凭证。

bash

echo "TFY_BASE_URL: ${TFY_BASE_URL:-(not set)}"
echo "TFY_HOST: ${TFY_HOST:-(not set)}"
echo "TFY_API_KEY: ${TFY_API_KEY:+(set)}${TFY_API_KEY:-(not set)}"
[ -f .env ] && grep -c '^TFY_' .env 2>/dev/null && echo ".env has TFY_ vars" || echo "No .env with TFY_ vars"

如果凭证已配置，直接跳转到步骤5：验证连接。

如果凭证缺失，询问用户：

你是否已经拥有TrueFoundry账号？如果有，我会帮你配置凭证。如果没有，我会带你一步步完成账号创建。

已有账号 → 跳转到步骤3：配置凭证
没有账号 → 继续执行步骤2

Step 2: Register a New Account

步骤2：注册新账号

Run the TrueFoundry registration CLI:

bash

tfy register

tfy

is not installed yet, use:

bash

uv run --from truefoundry tfy register

IMPORTANT:
tfy register
is fully interactive — it requires terminal input. Let the user drive this step. Do not attempt to pipe or automate the prompts.

运行TrueFoundry注册CLI：

bash

tfy register

如果还没有安装

tfy

，使用以下命令：

bash

uv run --from truefoundry tfy register

重要提示：
tfy register
是完全交互式的命令，需要终端输入，请让用户自主完成这一步，不要尝试管道传输或者自动填写提示内容。

What the CLI does (4-step wizard)

CLI执行逻辑（4步向导）

Choose account details — prompts for:
- Tenant name (3-15 chars, lowercase alphanumeric + dashes, e.g.,
```
acme-ai
```
  )
- Work email (company email recommended)
- Password (min 8 characters, confirmed twice)
- Primary use case — "llm ops" or "ml infrastructure"
Confirm terms — displays links to Privacy Policy and Terms of Service; requires acceptance
Complete human verification if required — some registration servers may open a browser for CAPTCHA or similar anti-abuse checks; let the user complete that step manually
Create account — the CLI calls the TrueFoundry registration service and retries individual fields on validation errors
Email verification — user must check their inbox, click the verification link, then press Enter to continue

填写账号信息 — 提示输入以下内容：
- 租户名称（3-15个字符，小写字母+数字+短横线，例如
```
acme-ai
```
  ）
- 工作邮箱（推荐使用公司邮箱）
- 密码（最少8个字符，需要确认输入两次）
- 主要使用场景 — 「llm ops」或者「ml infrastructure」
确认服务条款 — 展示隐私政策和服务条款链接，需要用户同意才能继续
按需完成人机验证 — 部分注册服务器会打开浏览器要求完成CAPTCHA等反滥用校验，请让用户手动完成该步骤
创建账号 — CLI调用TrueFoundry注册服务，字段校验失败时会重试该字段的输入
邮箱验证 — 用户需要查收收件箱，点击验证链接后按回车键继续

After registration

注册完成后

The CLI outputs:

The tenant URL (e.g.,
```
https://acme-ai.truefoundry.cloud
```
)
Instructions to create a Personal Access Token (PAT)
Optionally offers to install TrueFoundry agent skills

If the registration server is configured to require CAPTCHA, the CLI may also need a browser-based verification step before registration completes. Do not try to script or bypass that step.

Tell the user:

Your TrueFoundry tenant is ready at
<tenant-url>
. Next, create your first API key:
Open
<tenant-url>
in your browser
Go to Settings → Access → Personal Access Tokens → Generate New Token

Copy the token — you'll need it in the next step
See: https://docs.truefoundry.com/docs/generate-api-key

CLI会输出：

租户URL（例如
```
https://acme-ai.truefoundry.cloud
```
）
创建**个人访问令牌（PAT）**的说明
可选提供TrueFoundry agent技能的安装选项

如果注册服务器要求CAPTCHA验证，CLI可能还需要在注册完成前执行浏览器端验证步骤，不要尝试编写脚本或者绕过该步骤。

告知用户：

你的TrueFoundry租户已准备就绪，地址是
<tenant-url>
。接下来创建你的第一个API密钥：
在浏览器中打开
<tenant-url>
进入设置 → 访问控制 → 个人访问令牌 → 生成新令牌

复制令牌，下一步会用到
参考文档：https://docs.truefoundry.com/docs/generate-api-key

Step 3: Configure Credentials

步骤3：配置凭证

Once the user has their tenant URL and API key, set up the environment.

用户获取到租户URL和API密钥后，即可配置环境。

Option A: Environment Variables (recommended for development)

选项A：环境变量（开发场景推荐）

bash

export TFY_BASE_URL="https://your-org.truefoundry.cloud"
export TFY_API_KEY="tfy-..."
export TFY_HOST="${TFY_BASE_URL}"

bash

export TFY_BASE_URL="https://your-org.truefoundry.cloud"
export TFY_API_KEY="tfy-..."
export TFY_HOST="${TFY_BASE_URL}"

Option B: .env File (recommended for project-scoped config)

选项B：.env文件（项目级配置场景推荐）

bash

cat > .env << 'EOF'
TFY_BASE_URL=https://your-org.truefoundry.cloud
TFY_API_KEY=tfy-...
EOF

Security: Never commit
.env
files with API keys to Git. Ensure
.env
is in
.gitignore
.

Ask the user which option they prefer, then help them set the values with their actual tenant URL and API key.

bash

cat > .env << 'EOF'
TFY_BASE_URL=https://your-org.truefoundry.cloud
TFY_API_KEY=tfy-...
EOF

安全提示： 永远不要把包含API密钥的
.env
文件提交到Git仓库，确保
.env
已经添加到
.gitignore
中。

询问用户偏好的配置方式，然后帮助用户替换为实际的租户URL和API密钥。

Step 4: Install the CLI (Optional)

步骤4：安装CLI（可选）

The CLI is recommended but not required — all skills fall back to the REST API.

bash

tfy --version 2>/dev/null || echo "CLI not installed"

If not installed:

bash

pip install 'truefoundry==0.5.0'

TFY_API_KEY

is set and the user will use CLI commands, ensure

TFY_HOST

is also set:

bash

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

CLI是推荐工具但不是必须项，所有技能都可以降级使用REST API。

bash

tfy --version 2>/dev/null || echo "CLI not installed"

如果未安装：

bash

pip install 'truefoundry==0.5.0'

如果已经设置了

TFY_API_KEY

且用户会使用CLI命令，确保同时配置了

TFY_HOST

：

bash

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

Step 5: Verify Connection

步骤5：验证连接

Test that credentials work with a lightweight API call. 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.

bash

~/.claude/skills/truefoundry-onboarding/scripts/tfy-api.sh GET '/api/svc/v1/workspaces?limit=1'

Present the result:

TrueFoundry Status:
- Base URL: https://your-org.truefoundry.cloud ✓
- API Key: configured ✓
- Connection: OK ✓

You're all set!

If the connection fails, see Troubleshooting.

通过轻量API调用测试凭证是否生效。将

TFY_API_SH

设置为当前技能

scripts/tfy-api.sh

的完整路径，不同agent的路径可参考

references/tfy-api-setup.md

。

bash

~/.claude/skills/truefoundry-onboarding/scripts/tfy-api.sh GET '/api/svc/v1/workspaces?limit=1'

输出结果示例：

TrueFoundry Status:
- Base URL: https://your-org.truefoundry.cloud ✓
- API Key: configured ✓
- Connection: OK ✓

You're all set!

如果连接失败，参考故障排查。

Step 6: What's Next?

步骤6：后续操作指引

After successful setup, guide the user based on what they want to do:

You're connected to TrueFoundry! Here's what you can do next:

Deploy & Run
Deploy a service →
deploy
skill
Deploy an LLM →
llm-deploy
skill
Run a batch job →
jobs
skill
Launch a notebook →
notebooks
skill
Manage
List workspaces →
workspaces
skill
View running apps →
applications
skill
Check logs →
logs
skill
Optional add-on: For AI Gateway features (LLM routing, rate limiting, guardrails), install the gateway skills:
npx skills add truefoundry/tfy-gateway-skills
What would you like to do?

</instructions>

<success_criteria>

The user has a TrueFoundry account (either pre-existing or newly created via
```
tfy register
```
)
```
TFY_BASE_URL
```
and
```
TFY_API_KEY
```
are configured (via env vars or
```
.env
```
)
A test API call has confirmed connectivity
The user knows what they can do next and which skill to use
No credentials have been logged, echoed, or stored by the agent

</success_criteria>

成功完成搭建后，根据用户的需求提供后续指引：

你已成功连接到TrueFoundry！你可以选择以下后续操作：

部署与运行
部署服务 → 使用
deploy
技能
部署大模型 → 使用
llm-deploy
技能
运行批量任务 → 使用
jobs
技能
启动notebook → 使用
notebooks
技能
管理操作
列出工作区 → 使用
workspaces
技能
查看运行中的应用 → 使用
applications
技能
查看日志 → 使用
logs
技能
可选扩展： 如果需要使用AI网关功能（LLM路由、限流、防护规则），可以安装网关技能：
npx skills add truefoundry/tfy-gateway-skills
你想要进行什么操作？

</instructions>

<success_criteria>

用户拥有TrueFoundry账号（既存账号或者通过
```
tfy register
```
新创建的账号）
已完成
```
TFY_BASE_URL
```
和
```
TFY_API_KEY
```
配置（通过环境变量或者
```
.env
```
文件）
测试API调用已确认连通性正常
用户了解后续可执行的操作以及对应的技能
Agent没有记录、输出或者存储任何凭证信息

</success_criteria>

Error Handling

错误处理

tfy register

fails

tfy register

执行失败

If tfy CLI is not installed:
  uv run --from truefoundry tfy register
  # or: pip install 'truefoundry==0.5.0' && tfy register

If registration service is unreachable:
  Check network connectivity to https://registration.truefoundry.com

If a field validation error occurs (e.g., tenant name taken, invalid email):
  The CLI will retry only the failed field — follow the prompts.

If the CLI says CAPTCHA or human verification is required:
  Let it open the browser and complete the verification there.
  If the browser does not open automatically, copy the URL shown by the CLI into your browser.

如果tfy CLI未安装：
  uv run --from truefoundry tfy register
  # 或者：pip install 'truefoundry==0.5.0' && tfy register

如果无法访问注册服务：
  检查到https://registration.truefoundry.com的网络连通性

如果出现字段校验错误（例如租户名称已被占用、邮箱格式无效）：
  CLI会仅重试失败字段，请按照提示操作

如果CLI提示需要CAPTCHA或者人机验证：
  等待浏览器打开，在浏览器中完成验证即可。
  如果浏览器没有自动打开，将CLI展示的URL复制到浏览器中访问即可。

Email verification not received

未收到验证邮件

Check spam/junk folder. Try registering again with the same email.
If the problem persists, contact support@truefoundry.com.

检查垃圾邮件文件夹，尝试使用相同邮箱重新注册。
如果问题仍然存在，请联系support@truefoundry.com。

401 Unauthorized after setting credentials

配置凭证后返回401未授权

API key is invalid or expired. Generate a new one:
1. Open your tenant URL in browser
2. Go to Settings → API Keys → Generate New Key
3. Update TFY_API_KEY with the new value

See: https://docs.truefoundry.com/docs/generate-api-key

API密钥无效或者已过期，请生成新的密钥：
1. 在浏览器中打开你的租户URL
2. 进入设置 → API密钥 → 生成新密钥
3. 用新值更新TFY_API_KEY

参考文档：https://docs.truefoundry.com/docs/generate-api-key

Connection Refused / Timeout

连接被拒绝/超时

Cannot reach TFY_BASE_URL. Check:
- URL is correct (include https://)
- Network/VPN is connected
- No trailing slash in the URL

无法访问TFY_BASE_URL，请检查：
- URL填写正确（包含https://）
- 网络/VPN连接正常
- URL末尾没有多余的斜杠

.env

not picked up

无法读取

.env

配置

The .env file must be in the current working directory.
Variable names must match exactly: TFY_BASE_URL, TFY_API_KEY (no quotes around values).
The tfy-api.sh script handles .env parsing — never use `source .env`.

.env文件必须放在当前工作目录下。
变量名必须完全匹配：TFY_BASE_URL、TFY_API_KEY（值不要加引号）。
tfy-api.sh脚本会自动解析.env文件，永远不要执行`source .env`命令。

CLI host error: "TFY_HOST env must be set"

CLI主机错误：「必须设置TFY_HOST环境变量」

When using tfy CLI with TFY_API_KEY, TFY_HOST is also required:
  export TFY_HOST="${TFY_HOST:-${TFY_BASE_URL%/}}"

</troubleshooting> <references>

使用带TFY_API_KEY的tfy CLI时，必须同时配置TFY_HOST：
  export TFY_HOST="${TFY_HOST:-${TFY_BASE_URL%/}}"

</troubleshooting> <references>

Composability

可组合性

After onboarding → Use
```
status
```
skill to re-verify credentials at any time
Token management → Use
```
access-tokens
```
skill to create additional PATs
First deployment → Use
```
deploy
```
skill to ship a service
Workspace selection → Use
```
workspaces
```
skill to list and pick a workspace
Read the docs → Use
```
docs
```
skill to search TrueFoundry documentation

完成新手引导后 → 可随时使用
```
status
```
技能重新验证凭证
令牌管理 → 使用
```
access-tokens
```
技能创建额外的PAT
首次部署 → 使用
```
deploy
```
技能发布服务
工作区选择 → 使用
```
workspaces
```
技能列出并选择工作区
查阅文档 → 使用
```
docs
```
技能搜索TrueFoundry文档

truefoundry-onboarding

Original

Translation

TrueFoundry Onboarding

TrueFoundry 新手上路

When to Use

适用场景

When NOT to Use

不适用场景

Step 1: Detect Current State

步骤1：检测当前状态

Step 2: Register a New Account

步骤2：注册新账号

What the CLI does (4-step wizard)

CLI执行逻辑（4步向导）

After registration

注册完成后

Step 3: Configure Credentials

步骤3：配置凭证

Option A: Environment Variables (recommended for development)

选项A：环境变量（开发场景推荐）

Option B: .env File (recommended for project-scoped config)

选项B：.env文件（项目级配置场景推荐）

Step 4: Install the CLI (Optional)

步骤4：安装CLI（可选）

Step 5: Verify Connection

步骤5：验证连接

Step 6: What's Next?

步骤6：后续操作指引

Error Handling

错误处理

tfy register fails

tfy register执行失败

Email verification not received

未收到验证邮件

401 Unauthorized after setting credentials

配置凭证后返回401未授权

Connection Refused / Timeout

连接被拒绝/超时

.env not picked up

无法读取.env配置

CLI host error: "TFY_HOST env must be set"

CLI主机错误：「必须设置TFY_HOST环境变量」

Composability

可组合性

Related Documentation

相关文档

`tfy register`
fails

`tfy register`
执行失败

`.env`
not picked up

无法读取
`.env`
配置