truefoundry-platform

Routing note: For ambiguous user intents, use the shared clarification templates in references/intent-clarification.md.

TrueFoundry Platform

Platform setup and access management: verify credentials, discover workspaces and clusters, manage roles/teams/collaborators, handle secret groups, and create personal access tokens.

When to Use

• Verify TrueFoundry credentials and connectivity (preflight check)
• List clusters, workspaces, GPU types, or base domains
• Find workspace FQNs for deployment targets
• List or create roles, teams, or collaborators
• Manage secret groups and secret references (tfy-secret://)
• List and create personal access tokens (PATs)

When NOT to Use

• Deploy services/apps -> requires TrueFoundry Enterprise with connected cluster
• Configure AI Gateway -> gateway skill
• Register MCP servers -> mcp-servers skill
• Check logs -> observability skill
• First-time signup/login -> onboard skill

Credential Surfaces

Variable	Description	Example
TFY_BASE_URL	Platform URL	https://your-org.truefoundry.cloud
TFY_HOST	CLI host (set when TFY_API_KEY is set)	https://your-org.truefoundry.cloud
TFY_API_KEY	API key for REST calls	tfy-...

Status Check

Verify credentials and connectivity:

echo "TFY_BASE_URL: ${TFY_BASE_URL:-(not set)}"
echo "TFY_API_KEY: ${TFY_API_KEY:+(set)}${TFY_API_KEY:-(not set)}"

# Test connection
TFY_API_SH=~/.claude/skills/truefoundry-platform/scripts/tfy-api.sh
$TFY_API_SH GET '/api/svc/v1/workspaces?limit=1'

Present result as status summary. If login missing, use truefoundry-onboard.

Workspaces

Recommended Flow: Cluster -> Workspace

Never auto-pick a workspace. Always confirm with the user.

# Step 1: List clusters
$TFY_API_SH GET /api/svc/v1/clusters

# Step 2: List workspaces filtered by selected cluster
$TFY_API_SH GET '/api/svc/v1/workspaces?clusterId=SELECTED_CLUSTER_ID'

Present both as tables. Key field: fqn (needed for TFY_WORKSPACE_FQN).

If only one cluster exists, skip cluster selection and go to workspaces directly.

GPU Types

$TFY_API_SH GET /api/svc/v1/clusters/CLUSTER_ID/get-addons

For full GPU type table and cluster base domain lookups, see references/gpu-reference.md and references/cluster-discovery.md.

Access Control

Manage roles, teams, and collaborators. For full API calls, tool call syntax, presentation templates, common workflows, and subject format reference, see references/access-control.md.

Quick Reference

Action	API Call
List roles	$TFY_API_SH GET /api/svc/v1/roles
List teams	$TFY_API_SH GET /api/svc/v1/teams
List collaborators	$TFY_API_SH GET '/api/svc/v1/collaborators?resourceType=TYPE&resourceId=ID'
Create role	$TFY_API_SH POST /api/svc/v1/roles '{...}'
Create team	$TFY_API_SH POST /api/svc/v1/teams '{...}'
Add collaborator	$TFY_API_SH POST /api/svc/v1/collaborators '{...}'

Subject format: user:email, team:slug, serviceaccount:name, virtualaccount:name.

Security: Confirm subject, role, and resource with the user before granting access.

Destructive operations (delete roles, teams, collaborators): direct to dashboard.

Secrets

Manage secret groups and tfy-secret:// references. Never ask user to paste secret values in chat.

Quick Reference

Action	API Call
List secret groups	$TFY_API_SH GET /api/svc/v1/secret-groups
Create secret group	$TFY_API_SH POST /api/svc/v1/secret-groups '{...}'
Update secrets	$TFY_API_SH PUT '/api/svc/v1/secret-groups/ID' '{"secrets":[...]}'

Reference format: tfy-secret://<tenant>:<group>:<key>

Warning: Update operations delete omitted keys. Always include all keys.

For full create/update flows, API patterns, and security policies, see references/secrets-and-tokens.md.

Access Tokens

List and create PATs. Token values are shown only once at creation.

Action	API Call
List PATs	$TFY_API_SH GET /api/svc/v1/personal-access-tokens
Create PAT	$TFY_API_SH POST /api/svc/v1/personal-access-tokens '{"name":"..."}'

Security: Never repeat, store, or log token values. Show masked preview by default; full value only on explicit confirmation.

For full token display policy and security rules, see references/secrets-and-tokens.md.

Deletion: direct to dashboard.

<success_criteria>

Success Criteria

• Status check confirms connectivity or provides actionable next steps
• Workspaces presented in formatted table with FQNs
• Cluster/GPU discovery completed before offering resource options
• Access control operations confirmed before executing
• Secret groups listed without revealing values
• Token values shown only once at creation with masked preview default
• Destructive operations directed to dashboard

</success_criteria>

Error Handling

401 Unauthorized

API key invalid or expired. Generate new one: Dashboard -> Access -> API Keys.

Connection Refused / Timeout

Check: URL correct (include https://), network/VPN connected, no trailing slash.

CLI Host Missing

If tfy CLI says "TFY_HOST env must be set": export TFY_HOST="${TFY_HOST:-${TFY_BASE_URL%/}}"

No Workspaces Found

Selected cluster may have no workspaces, or API key lacks access. Try different cluster.

Permission Denied

Admin access may be required for access control and token operations.

Invalid Subject Format

Use pattern type:identifier — e.g., user:[email protected], team:platform-team.

Token Value Lost

Token values only shown at creation. Create a new token, update affected services, revoke old one in dashboard.

References

• access-control.md — Roles, teams, collaborators: full API calls, workflows, presentation
• secrets-and-tokens.md — Secret groups, PATs: create/update flows, security policies
• cli-reference.md — CLI commands and what doesn't exist
• api-endpoints.md — Full REST API reference
• cluster-discovery.md — Base domains and cluster lookups
• gpu-reference.md — GPU type table and SDK examples
• prerequisites.md — Credential reference and workspace FQN rules

Composability

• After status OK: Use any other skill (gateway, mcp-servers, prompts, etc.)
• AI Gateway auth: PATs authenticate gateway requests (gateway skill)
• Before deploy: Set up teams and grant workspace access first
• Dependency chain: Create roles -> create teams -> add collaborators