A comprehensive collection of agent skills for managing TrueFoundry platform operations — deployments, secrets, access control, AI gateway, guardrails, logs, MCP servers, prompts, and more.
npx @senso-ai/shipables install mnvsk97/truefoundry-agent-skillsA bundled skill package for managing the TrueFoundry MLOps platform.
TFY_BASE_URL (or TFY_HOST) and TFY_API_KEYRun the Status section first to verify your credentials.
Check TrueFoundry connection and verify credentials are configured.
Verify TrueFoundry credentials and connectivity, or diagnose authentication issues before performing platform operations.
workspaces skill; ask if the user wants another valid pathdeploy skill; ask if the user wants another valid pathapplications skill; ask if the user wants another valid path| Variable | Description | Example |
|---|---|---|
TFY_BASE_URL | TrueFoundry platform URL | https://your-org.truefoundry.cloud |
TFY_HOST | CLI host alias (recommended when TFY_API_KEY is set for CLI commands) | https://your-org.truefoundry.cloud |
TFY_API_KEY | API key (raw, no Bearer prefix) | tfy-... |
If the TrueFoundry tool server is available, use this tool call:
tfy_config_status
This returns connection status, configured base URL, and whether an API key is set.
Check environment variables and test the connection. 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.
# Check env vars are set
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)}"
# Test connection — list workspaces (lightweight call). Use full path shown above.
# Example for Claude Code:
~/.claude/skills/truefoundry-status/scripts/tfy-api.sh GET '/api/svc/v1/workspaces?limit=1'
If env vars are not set, check for a .env file:
[ -f .env ] && echo ".env found" || echo "No .env file"
TrueFoundry Status:
- Base URL: https://your-org.truefoundry.cloud ✓
- API Key: configured ✓
- Connection: OK (listed 1 workspace)
Or if something is wrong:
TrueFoundry Status:
- Base URL: (not set) ✗
- API Key: (not set) ✗
Set TFY_BASE_URL and TFY_API_KEY in your environment or .env file.
Get an API key: https://docs.truefoundry.com/docs/generating-truefoundry-api-keys
<success_criteria>
deploy, list workspaces, etc.)</success_criteria>
API key is invalid or expired. Generate a new one:
https://docs.truefoundry.com/docs/generating-truefoundry-api-keys
Cannot reach TFY_BASE_URL. Check:
- URL is correct (include https://)
- Network/VPN is connected
TFY_BASE_URL and TFY_API_KEY are required.
Set them via environment variables or add to .env in project root.
TFY_HOST error)If tfy CLI says: "TFY_HOST env must be set since TFY_API_KEY env is set"
run: export TFY_HOST="${TFY_HOST:-${TFY_BASE_URL%/}}"
tfy_config_set to persist credentialsFetch up-to-date TrueFoundry documentation for features, API reference, and deployment guides.
Fetch up-to-date TrueFoundry documentation for features, API reference, deployment guides, or troubleshooting.
Full API docs:
https://truefoundry.com/docs/api-reference
Fetch a specific section:
curl -s https://truefoundry.com/docs/api-reference/applications/list-applications
| Topic | URL |
|---|---|
| Introduction to Services | https://truefoundry.com/docs/introduction-to-a-service |
| Deploy First Service | https://truefoundry.com/docs/deploy-first-service |
| Dockerize Code | https://truefoundry.com/docs/dockerize-code |
| Ports and Domains | https://truefoundry.com/docs/define-ports-and-domains |
| Endpoint Auth | https://truefoundry.com/docs/endpoint-authentication |
| Resources (CPU/Memory) | https://truefoundry.com/docs/resources-cpu-memory-storage |
| Fractional GPUs | https://truefoundry.com/docs/using-fractional-gpus |
| Environment Variables | https://truefoundry.com/docs/environment-variables-and-secrets |
| Autoscaling | https://truefoundry.com/docs/autoscaling-overview |
| Liveness/Readiness Probes | https://truefoundry.com/docs/liveness-readiness-probe |
| Rollout Strategy | https://truefoundry.com/docs/rollout-strategy |
| Deploy Programmatically | https://truefoundry.com/docs/deploy-service-programatically |
| CI/CD Setup | https://truefoundry.com/docs/setting-up-cicd-for-your-service |
| Monitoring | https://truefoundry.com/docs/monitor-your-service |
| Topic | URL |
|---|---|
| Introduction to Jobs | https://truefoundry.com/docs/introduction-to-a-job |
| Deploy First Job | https://truefoundry.com/docs/deploy-first-job |
| Topic | URL |
|---|---|
| ML Repos | https://truefoundry.com/docs/ml-repos |
| LLM Deployment | https://truefoundry.com/docs/llm-deployment |
| LLM Tracing | https://truefoundry.com/docs/llm-tracing |
| Topic | URL |
|---|---|
| Generating API Keys | https://docs.truefoundry.com/docs/generating-truefoundry-api-keys |
To fetch a specific docs page for the user:
curl -sL "https://truefoundry.com/docs/deploy-first-service" | head -200
Or use WebFetch if available in the agent.
<success_criteria>
</success_criteria>
references/api-endpoints.md in _sharedManage TrueFoundry roles, teams, and collaborators. Roles define permission sets, teams group users, and collaborators grant access to specific resources.
List, create, or delete roles, teams, and collaborators on TrueFoundry. Use when managing permissions, organizing users into teams, or granting/revoking access to workspaces, applications, MCP servers, or other resources.
Roles are named permission sets scoped to a resource type. Built-in roles vary by resource type (for example, workspace-admin, workspace-member).
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.
tfy_roles_list()
# Set the path to tfy-api.sh for your agent (example for Claude Code):
TFY_API_SH=~/.claude/skills/truefoundry-access-control/scripts/tfy-api.sh
# List all roles
$TFY_API_SH GET /api/svc/v1/roles
Roles:
| Name | ID | Resource Type | Permissions |
|-------------------|----------|---------------|-------------|
| workspace-admin | role-abc | workspace | 12 |
| workspace-member | role-def | workspace | 5 |
| custom-deployer | role-ghi | workspace | 3 |
tfy_roles_create(payload={"name": "custom-deployer", "displayName": "Custom Deployer", "description": "Can deploy apps", "resourceType": "workspace", "permissions": ["deploy:create", "deploy:read"]})
Note: Requires human approval (HITL) via tool call.
$TFY_API_SH POST /api/svc/v1/roles '{"name":"custom-deployer","displayName":"Custom Deployer","description":"Can deploy apps","resourceType":"workspace","permissions":["deploy:create","deploy:read"]}'
tfy_roles_delete(id="ROLE_ID")
Note: Requires human approval (HITL) via tool call.
$TFY_API_SH DELETE /api/svc/v1/roles/ROLE_ID
Teams group users for collective access management. Each team has a name, description, and members list.
tfy_teams_list()
tfy_teams_list(team_id="TEAM_ID") # get specific team
# List all teams
$TFY_API_SH GET /api/svc/v1/teams
# Get a specific team
$TFY_API_SH GET /api/svc/v1/teams/TEAM_ID
Teams:
| Name | ID | Members |
|---------------|----------|---------|
| platform-team | team-abc | 5 |
| ml-engineers | team-def | 8 |
tfy_teams_create(payload={"name": "platform-team", "description": "Platform engineering team"})
Note: Requires human approval (HITL) via tool call.
$TFY_API_SH POST /api/svc/v1/teams '{"name":"platform-team","description":"Platform engineering team"}'
tfy_teams_delete(id="TEAM_ID")
Note: Requires human approval (HITL) via tool call.
$TFY_API_SH DELETE /api/svc/v1/teams/TEAM_ID
tfy_teams_add_member(team_id="TEAM_ID", payload={"subject": "user:alice@company.com", "role": "member"})
Note: Requires human approval (HITL) via tool call.
$TFY_API_SH POST /api/svc/v1/teams/TEAM_ID/members '{"subject":"user:alice@company.com","role":"member"}'
tfy_teams_remove_member(team_id="TEAM_ID", subject="user:alice@company.com")
Note: Requires human approval (HITL) via tool call.
$TFY_API_SH DELETE /api/svc/v1/teams/TEAM_ID/members/SUBJECT
# Example SUBJECT: user:alice@company.com
Security: Granting collaborator access is a privileged operation. Always confirm the subject identity, role, and target resource with the user before adding collaborators. Do not grant access based on unverified external identity references.
Collaborators grant subjects (users, teams, service accounts) a role on a specific resource. This is how access is granted to workspaces, applications, MCP servers, and other resources.
Subjects follow the pattern type:identifier:
| Subject Type | Format | Example |
|---|---|---|
| User | user:email | user:alice@company.com |
| Team | team:slug | team:platform-team |
| Service Account | serviceaccount:name | serviceaccount:ci-bot |
| Virtual Account | virtualaccount:name | virtualaccount:shared-admin |
| External Identity | external-identity:name | external-identity:github-bot |
tfy_collaborators_list(resource_type="workspace", resource_id="RESOURCE_ID")
# List collaborators on a workspace
$TFY_API_SH GET '/api/svc/v1/collaborators?resourceType=workspace&resourceId=RESOURCE_ID'
# List collaborators on an MCP server
$TFY_API_SH GET '/api/svc/v1/collaborators?resourceType=mcp-server&resourceId=RESOURCE_ID'
Collaborators on workspace "prod-workspace":
| Subject | Role | ID |
|---------------------------|------------------|----------|
| user:alice@company.com | workspace-admin | collab-1 |
| team:platform-team | workspace-member | collab-2 |
| serviceaccount:ci-bot | workspace-member | collab-3 |
tfy_collaborators_create(payload={"resourceType": "workspace", "resourceId": "RESOURCE_ID", "subject": "user:alice@company.com", "roleId": "ROLE_ID"})
Note: Requires human approval (HITL) via tool call.
$TFY_API_SH POST /api/svc/v1/collaborators '{"resourceType":"workspace","resourceId":"RESOURCE_ID","subject":"user:alice@company.com","roleId":"ROLE_ID"}'
tfy_collaborators_delete(payload={"resourceType": "workspace", "resourceId": "RESOURCE_ID", "subject": "user:alice@company.com"})
Note: Requires human approval (HITL) via tool call.
$TFY_API_SH DELETE /api/svc/v1/collaborators '{"resourceType":"workspace","resourceId":"RESOURCE_ID","subject":"user:alice@company.com"}'
workspace-admin or workspace-member)# 1. Find the role ID
$TFY_API_SH GET /api/svc/v1/roles
# 2. Add collaborator
$TFY_API_SH POST /api/svc/v1/collaborators '{"resourceType":"workspace","resourceId":"WORKSPACE_ID","subject":"user:alice@company.com","roleId":"ROLE_ID"}'
# 1. Create team
$TFY_API_SH POST /api/svc/v1/teams '{"name":"ml-engineers","description":"ML engineering team"}'
# 2. Add members (use team ID from response)
$TFY_API_SH POST /api/svc/v1/teams/TEAM_ID/members '{"subject":"user:alice@company.com","role":"member"}'
# 3. Grant team access to a workspace
$TFY_API_SH POST /api/svc/v1/collaborators '{"resourceType":"workspace","resourceId":"WORKSPACE_ID","subject":"team:ml-engineers","roleId":"ROLE_ID"}'
List all collaborators to see who has access and with what role:
$TFY_API_SH GET '/api/svc/v1/collaborators?resourceType=workspace&resourceId=WORKSPACE_ID'
<success_criteria>
</success_criteria>
status skill to verify credentials before managing access controlRole ID not found. List roles first to find the correct ID.
Team ID not found. List teams first to find the correct ID.
Cannot manage access control. Check your API key permissions — admin access may be required.
Collaborator with this subject and role already exists on the resource. Use a different role or remove the existing collaborator first.
Invalid subject format. Use the pattern "type:identifier" — e.g., user:alice@company.com, team:platform-team, serviceaccount:ci-bot.
Resource not found. Verify the resourceType and resourceId are correct. List the resources first to confirm.
Built-in roles cannot be deleted. Only custom roles can be removed.
Manage TrueFoundry personal access tokens (PATs). List, create, and delete tokens used for API authentication, CI/CD pipelines, and AI Gateway access.
List, create, or delete personal access tokens for API authentication, CI/CD pipelines, or AI Gateway access.
Security Policy: Credential Handling
- The agent MUST NOT repeat, store, or log token values in its own responses.
- After creating a token, direct the user to copy the value from the API response output above — do not re-display it.
- Never include token values in summaries, follow-up messages, or any other output.
Run the status skill first to verify TFY_BASE_URL and TFY_API_KEY are set and valid.
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.
tfy_access_tokens_list()
TFY_API_SH=~/.claude/skills/truefoundry-access-tokens/scripts/tfy-api.sh
# List all personal access tokens
$TFY_API_SH GET /api/svc/v1/personal-access-tokens
Present results:
Personal Access Tokens:
| Name | ID | Created At | Expires At |
|---------------|----------|-------------|-------------|
| ci-pipeline | pat-abc | 2025-01-15 | 2025-07-15 |
| dev-local | pat-def | 2025-03-01 | Never |
Security: Never display token values. They are only shown once at creation time.
Ask the user for a token name before creating.
tfy_access_tokens_create(payload={"name": "my-token"})
Note: Requires human approval (HITL) via tool call.
# Create a new personal access token
$TFY_API_SH POST /api/svc/v1/personal-access-tokens '{"name":"my-token"}'
IMPORTANT: The token value is returned ONLY in the creation response.
Security: Token Display Policy
- Default to showing only a masked preview (for example: first 4 + last 4 characters).
- Show the full token only after explicit user confirmation that they are ready to copy it now.
- If a full token is shown, show it only once, in a minimal response, and never repeat it in summaries/follow-up messages.
- The agent must NEVER store, log, or re-display the token value after the initial one-time reveal.
- If the user asks to see the token again later, instruct them to create a new token.
Present the result:
Token created successfully!
Name: my-token
Token (masked): tfy_****...****
If user explicitly confirms they are ready to copy it:
One-time token: <full value from API response>
⚠️ Save this token NOW — it will not be shown again.
Store it in a password manager, CI/CD secret store, or TrueFoundry secret group.
Never commit tokens to Git or share them in plain text.
Ask for confirmation before deleting — this is irreversible and will break any integrations using the token.
tfy_access_tokens_delete(id="TOKEN_ID")
Note: Requires human approval (HITL) via tool call.
# Delete a personal access token
$TFY_API_SH DELETE /api/svc/v1/personal-access-tokens/TOKEN_ID
<success_criteria>
</success_criteria>
ai-gateway skill)gitops skill, deploy skill declarative apply workflow)status skill to verify a PAT is workingsecrets skill)See references/api-endpoints.md for the full Personal Access Tokens API reference.
Cannot manage access tokens. Check your API key permissions.
Token ID not found. List tokens first to find the correct ID.
A token with this name already exists. Use a different name.
If services fail after token deletion, they were using the deleted token.
Create a new token and update the affected services/pipelines.
Token values are only shown at creation time. If lost, delete the old token
and create a new one, then update all services that used the old token.
Use TrueFoundry's AI Gateway to access 1000+ LLMs through a unified OpenAI-compatible API with rate limiting, budget controls, load balancing, routing, and observability.
Access LLMs through TrueFoundry's unified OpenAI-compatible gateway, configure auth tokens (PAT/VAT), set up rate limiting, budget controls, or load balancing across providers.
llm-deploy skill; ask if the user wants another valid path (then connect to gateway)deploy skill; ask if the user wants another valid path (service with tool-proxy)status skill; ask if the user wants another valid pathThe AI Gateway sits between your application and LLM providers:
Your App → AI Gateway → OpenAI / Anthropic / Azure / Self-hosted vLLM / etc.
↑
Unified API + Auth + Rate Limiting + Routing + Logging
Key benefits:
The gateway base URL is your TrueFoundry platform URL + /api/llm:
{TFY_BASE_URL}/api/llm
Example: https://your-org.truefoundry.cloud/api/llm
For development and individual use:
For production applications (recommended):
VATs are recommended for production because:
from openai import OpenAI
client = OpenAI(
api_key="<your-PAT-or-VAT>",
base_url="https://<your-truefoundry-url>/api/llm",
)
# Chat completion
response = client.chat.completions.create(
model="openai/gpt-4o", # or any configured model name
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Hello!"},
],
max_tokens=200,
)
print(response.choices[0].message.content)
stream = client.chat.completions.create(
model="openai/gpt-4o",
messages=[{"role": "user", "content": "Write a haiku about AI"}],
stream=True,
)
for chunk in stream:
if chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="")
curl "${TFY_BASE_URL}/api/llm/chat/completions" \
-H "Authorization: Bearer ${TFY_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-4o",
"messages": [{"role": "user", "content": "Hello!"}],
"max_tokens": 200
}'
import OpenAI from "openai";
const client = new OpenAI({
apiKey: "<your-PAT-or-VAT>",
baseURL: "https://<your-truefoundry-url>/api/llm",
});
const response = await client.chat.completions.create({
model: "openai/gpt-4o",
messages: [{ role: "user", content: "Hello!" }],
});
Set these to use with any OpenAI-compatible library:
export OPENAI_BASE_URL="${TFY_BASE_URL}/api/llm"
export OPENAI_API_KEY="<your-PAT-or-VAT>"
Then any code using openai.OpenAI() without explicit parameters will use the gateway automatically.
| API | Endpoint | Description |
|---|---|---|
| Chat Completions | /chat/completions | Chat with any model (streaming + non-streaming) |
| Completions | /completions | Legacy text completions |
| Embeddings | /embeddings | Text embeddings (text + list inputs) |
| Image Generation | /images/generations | Generate images |
| Image Editing | /images/edits | Edit images |
| Audio Transcription | /audio/transcriptions | Speech-to-text |
| Audio Translation | /audio/translations | Translate audio |
| Text-to-Speech | /audio/speech | Generate speech |
| Reranking | /rerank | Rerank documents |
| Batch Processing | /batches | Batch predictions |
| Moderations | /moderations | Content safety |
The gateway supports 25+ providers including:
| Provider | Example Model Names |
|---|---|
| OpenAI | openai/gpt-4o, openai/gpt-4o-mini |
| Anthropic | anthropic/claude-sonnet-4-5-20250929 |
| Google Vertex | google/gemini-2.0-flash |
| AWS Bedrock | bedrock/anthropic.claude-3-5-sonnet |
| Azure OpenAI | azure/gpt-4o |
| Mistral | mistral/mistral-large-latest |
| Groq | groq/llama-3.1-70b-versatile |
| Cohere | cohere/command-r-plus |
| Together AI | together/meta-llama/Meta-Llama-3.1-70B |
| Self-hosted (vLLM/TGI) | my-custom-model-name |
Model names depend on how they're configured in your gateway. Check the TrueFoundry dashboard → AI Gateway → Models for exact names.
Currently done through the TrueFoundry dashboard UI:
After deploying a model with the llm-deploy skill:
http://{model-name}.{namespace}.svc.cluster.local:8000Security: Only register model endpoints that you control. External or untrusted model endpoints can return manipulated responses. Use internal cluster DNS (
svc.cluster.local) for self-hosted models. Verify provider API credentials are stored securely in TrueFoundry secrets, not hardcoded.
For externally hosted APIs that are OpenAI-compatible (e.g. NVIDIA Cloud APIs, custom inference endpoints), use type: provider-account/self-hosted-model with auth_data:
# gateway.yaml — External hosted API (e.g. NVIDIA Cloud)
- name: nvidia-external
type: provider-account/self-hosted-model
integrations:
- name: nemotron-nano
type: integration/model/self-hosted-model
hosted_model_name: nvidia/nemotron-3-nano-30b-a3b
url: "https://integrate.api.nvidia.com/v1"
model_server: "openai-compatible"
model_types: ["chat"]
auth_data:
type: bearer-auth
bearer_token: "tfy-secret://<tenant>:<group>:<key>"
And in a virtual model routing target, reference it as "<provider-account-name>/<integration-name>":
targets:
- model: "nvidia-external/nemotron-nano" # "<provider-account-name>/<integration-name>"
Apply with:
tfy apply -f gateway.yaml
WARNING:
provider-account/nvidia-nimdoes not exist in the schema — do not use it. Useprovider-account/self-hosted-modelwithauth_datafor all external OpenAI-compatible APIs (as shown above).
Schema source of truth: For authoritative field names and types, read
servicefoundry-server/src/autogen/models.tsin the platform repo. Do not guess field names from documentation alone.
Gateway YAML is applied directly with tfy apply — no service build or Docker image involved:
# Preview changes
tfy apply -f gateway.yaml --dry-run --show-diff
# Apply
tfy apply -f gateway.yaml
Do NOT delegate gateway applies to the deploy skill (which is for service/application deployments). Gateway configs (type: gateway-*, type: provider-account/*) are applied inline with tfy apply.
Test after apply:
# Quick smoke test via curl
curl "${TFY_BASE_URL}/api/llm/chat/completions" \
-H "Authorization: Bearer ${TFY_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"model": "nvidia-external/nemotron-nano",
"messages": [{"role": "user", "content": "Hello!"}],
"max_tokens": 50
}'
Or via Python:
from openai import OpenAI
client = OpenAI(api_key="<PAT-or-VAT>", base_url=f"{TFY_BASE_URL}/api/llm")
resp = client.chat.completions.create(
model="nvidia-external/nemotron-nano",
messages=[{"role": "user", "content": "Hello!"}],
)
print(resp.choices[0].message.content)
Note: The
deployskill reference in the Routing Config section below is only for CI/CD GitOps pipelines — not for one-off gateway config applies.
The gateway supports intelligent request routing across multiple model instances.
Distribute requests proportionally:
Automatically route to the lowest-latency model:
Route to highest-priority healthy model with SLA cutoff:
Routing configurations can be managed as YAML and applied via tfy apply:
# Store routing config in git, apply via CLI
tfy apply -f gateway-routing-config.yaml
See deploy skill (declarative apply workflow) and gitops skill for CI/CD integration.
Control model usage per user, team, or application:
Enforce cost limits:
All gateway requests are logged with:
Tag requests with custom metadata for tracking:
response = client.chat.completions.create(
model="openai/gpt-4o",
messages=[{"role": "user", "content": "Hello"}],
extra_headers={
"X-TFY-LOGGING-CONFIG": '{"project": "my-app", "environment": "production"}'
},
)
View usage analytics in TrueFoundry dashboard:
Export traces to your observability stack:
For content filtering, PII detection, prompt injection prevention, and custom safety rules, use the guardrails skill. It configures guardrail providers and rules that apply to this gateway's traffic.
If a user has already deployed a tool server and wants to attach it to MCP gateway:
deploy + applications skills)mcp-servers skill)The gateway works with popular AI frameworks:
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
model="openai/gpt-4o",
api_key="<your-PAT-or-VAT>",
base_url="https://<your-truefoundry-url>/api/llm",
)
from llama_index.llms.openai import OpenAI
llm = OpenAI(
model="openai/gpt-4o",
api_key="<your-PAT-or-VAT>",
api_base="https://<your-truefoundry-url>/api/llm",
)
Configure the gateway as a custom API endpoint in your coding assistant settings:
{TFY_BASE_URL}/api/llmWhen the user asks about gateway configuration:
AI Gateway:
Endpoint: https://your-org.truefoundry.cloud/api/llm
Auth: Personal Access Token (PAT) or Virtual Access Token (VAT)
Available Models (check dashboard for current list):
| Model Name | Provider | Type |
|-------------------|-------------|-------------|
| openai/gpt-4o | OpenAI | Cloud |
| my-gemma-2b | Self-hosted | vLLM (T4) |
| anthropic/claude | Anthropic | Cloud |
Usage:
export OPENAI_BASE_URL="https://your-org.truefoundry.cloud/api/llm"
export OPENAI_API_KEY="your-token"
# Then use any OpenAI-compatible SDK
<success_criteria>
</success_criteria>
llm-deploy skill to deploy a self-hosted model, then add to gatewaydeploy skill (declarative apply workflow) to apply routing YAML via GitOpsdeploy skill to deploy tool servers (service with tool-proxy), register in gatewayapplications skill to see running model servicesGateway authentication failed. Check:
- API key (PAT or VAT) is valid and not expired
- Using correct header: Authorization: Bearer <token>
Model access denied. Your token may not have access to this model.
- PATs inherit user permissions
- VATs only have access to explicitly selected models
- Check with your admin to grant model access
Rate limit exceeded. Options:
- Wait and retry (check Retry-After header)
- Request higher limits from admin
- Use load balancing to distribute across providers
Upstream provider error. The gateway will automatically:
- Retry on configured status codes
- Fallback to alternate models if routing is configured
If persistent, check provider status page or self-hosted model health.
Model name not found in gateway. Check:
- Exact model name in TrueFoundry dashboard → AI Gateway → Models
- Provider account is active and model is enabled
- Your token has access to this model
Configure content safety guardrails for TrueFoundry AI Gateway. Guardrails add safety controls to LLM inputs/outputs and MCP tool invocations.
Set up guardrail providers, create guardrail rules, or manage content safety policies for AI Gateway endpoints. This includes PII filtering, content moderation, prompt injection detection, secret detection, and custom validation rules.
When the user asks to deploy a guardrails server or run guardrails as a deployed service, start from the official template so the server adheres to the gateway's input/output formats:
deploy skill to deploy the resulting service (Dockerfile or build from source as in the template).This keeps guardrail servers compatible with TrueFoundry AI Gateway expectations.
Guardrails require a two-step setup:
A guardrail config group holds integration credentials for one or more guardrail providers. See references/guardrail-providers.md for all supported providers.
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.
tfy_guardrail_config_groups_list()
TFY_API_SH=~/.claude/skills/truefoundry-guardrails/scripts/tfy-api.sh
$TFY_API_SH GET '/api/svc/v1/provider-accounts?type=guardrail-config-group'
tfy_guardrail_config_groups_create(payload={"name": "my-guardrails", "type": "provider-account/guardrail-config-group", "integrations": [...]})
Note: Requires human approval (HITL) via tool call.
$TFY_API_SH POST /api/svc/v1/provider-accounts '{
"name": "my-guardrails",
"type": "provider-account/guardrail-config-group",
"integrations": [
{
"type": "integration/guardrail/tfy-pii",
"config": {}
},
{
"type": "integration/guardrail/tfy-content-moderation",
"config": {}
}
]
}'
Each integration has a type (from the providers reference) and a config object with provider-specific fields. Some providers (like tfy-pii, tfy-content-moderation) require no config. Others (like aws-bedrock, azure-content-safety) need cloud credentials.
Security: Guardrail providers with external
endpoint_urlfields (e.g.,custom,opa,fiddler,palo-alto-prisma-airs) route request data to third-party services. Verify that all external endpoints are trusted and controlled by your organization before registering them. Prefer TrueFoundry built-in providers (tfy-pii,tfy-content-moderation,tfy-prompt-injection) when possible.
Guardrail Config Groups:
| Name | ID | Integrations |
|------------------|----------|--------------|
| my-guardrails | pa-abc | 3 |
| prod-safety | pa-def | 5 |
Gateway guardrails config defines rules that control which guardrails apply to which models, users, and tools.
tfy_gateway_guardrails_list()
$TFY_API_SH GET /api/svc/v1/gateway-guardrails-configs
tfy_gateway_guardrails_create(payload={"name": "production-guardrails", "type": "gateway-guardrails-config", "gateway_ref": "GATEWAY_FQN", "rules": [...]})
Note: Requires human approval (HITL) via tool call.
$TFY_API_SH POST /api/svc/v1/gateway-guardrails-configs '{
"name": "production-guardrails",
"type": "gateway-guardrails-config",
"gateway_ref": "GATEWAY_FQN",
"rules": [
{
"id": "pii-filter-all-models",
"when": {
"target_conditions": {
"models": ["*"],
"mcp_servers": [],
"tools": []
},
"subject_conditions": {
"users": ["*"],
"teams": []
}
},
"llm_input_guardrails": [
{
"provider_ref": "provider-account-id:integration/guardrail/tfy-pii",
"operation": "validate",
"enforcing_strategy": "enforce",
"priority": 1
}
],
"llm_output_guardrails": [
{
"provider_ref": "provider-account-id:integration/guardrail/tfy-pii",
"operation": "validate",
"enforcing_strategy": "enforce",
"priority": 1
}
],
"mcp_tool_pre_invoke_guardrails": [],
"mcp_tool_post_invoke_guardrails": []
}
]
}'
$TFY_API_SH PUT /api/svc/v1/gateway-guardrails-configs/GUARDRAILS_CONFIG_ID '{
"name": "production-guardrails",
"type": "gateway-guardrails-config",
"gateway_ref": "GATEWAY_FQN",
"rules": [...]
}'
Each rule contains:
target_conditions.models — Model name patterns (use ["*"] for all)target_conditions.mcp_servers — MCP server names to targettarget_conditions.tools — Specific tool names to targetsubject_conditions.users — User patterns (use ["*"] for all)subject_conditions.teams — Team namesEach guardrail entry in a rule has:
<provider-account-id>:integration/guardrail/<provider-type>validate (check and block) or mutate (modify content, e.g., redact PII)enforce — Block the request on violationaudit — Log the violation but allow the requestenforce_but_ignore_on_error — Enforce if guardrail succeeds, allow if guardrail errors# Step 1: Create config group with tfy-pii
$TFY_API_SH POST /api/svc/v1/provider-accounts '{
"name": "pii-guardrails",
"type": "provider-account/guardrail-config-group",
"integrations": [
{"type": "integration/guardrail/tfy-pii", "config": {}}
]
}'
# Step 2: Create rule targeting all models
# Use the provider account ID from step 1 response in provider_ref
Use "enforcing_strategy": "audit" to log violations without blocking — useful for monitoring before enforcement.
Target specific MCP tools with mcp_tool_pre_invoke_guardrails to validate inputs before tool execution, or mcp_tool_post_invoke_guardrails to scan tool outputs.
Use target_conditions.models to apply guardrails only to specific models:
"when": {
"target_conditions": {
"models": ["openai/gpt-4*", "anthropic/claude-*"],
"mcp_servers": [],
"tools": []
}
}
Combine broad model targeting with specific user conditions to exempt admin users:
"subject_conditions": {
"users": ["user1@example.com", "user2@example.com"],
"teams": ["engineering"]
}
The gateway_ref is the fully qualified name (FQN) of your AI Gateway deployment. Use the ai-gateway skill to list gateways and get the FQN.
<success_criteria>
</success_criteria>
status skill to verify credentials before configuring guardrailsgateway_refreferences/guardrail-providers.md for all 23 supported providersProvider account not found. List config groups first to find the correct ID.
Unknown guardrail integration type. Check references/guardrail-providers.md for valid types.
Gateway reference not found. Use the ai-gateway skill to list available gateways.
Rule ID already exists in this config. Use a unique ID for each rule.
Integration config missing required fields. Check the provider reference for required config.
Cannot manage guardrails. Check your API key permissions.
View and download application and job logs from TrueFoundry.
View, download, and search application and job logs from TrueFoundry. Useful for debugging deployments, checking startup output, and finding errors.
Security: Log output may contain sensitive data (secrets, tokens, PII). Do not forward raw logs to external services or include them in responses without reviewing for sensitive content first.
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.
tfy_logs_download(payload={
"workspace_id": "ws-id",
"application_fqn": "app-fqn",
"start_ts": "2026-02-10T00:00:00Z",
"end_ts": "2026-02-10T23:59:59Z"
})
# Set the path to tfy-api.sh for your agent (example for Claude Code):
TFY_API_SH=~/.claude/skills/truefoundry-logs/scripts/tfy-api.sh
# Download logs for an app in a workspace
$TFY_API_SH GET '/api/svc/v1/logs/WORKSPACE_ID/download?applicationFqn=APP_FQN&startTs=START&endTs=END'
# With search filter
$TFY_API_SH GET '/api/svc/v1/logs/WORKSPACE_ID/download?applicationId=APP_ID&searchString=error&searchType=contains'
| Parameter | API Key | Description |
|---|---|---|
workspace_id | (path) | Workspace ID (required) |
application_id | applicationId | Filter by app ID |
application_fqn | applicationFqn | Filter by app FQN |
deployment_id | deploymentId | Filter by deployment |
job_run_name | jobRunName | Filter by job run |
start_ts | startTs | Start timestamp (ISO 8601) |
end_ts | endTs | End timestamp (ISO 8601) |
search_string | searchString | Search within logs |
search_type | searchType | contains, regex |
pod_name | podName | Filter by pod |
Show logs in chronological order. For long output, show the last N lines or summarize errors:
Logs for tfy-tool-server (last 20 lines):
2026-02-10 14:30:01 INFO Server starting on port 8000
2026-02-10 14:30:02 INFO Tools endpoint ready at /tools
2026-02-10 14:30:05 INFO Health check: OK
<success_criteria>
</success_criteria>
applications skill to get app ID or FQNworkspaces skill to get workspace IDsearchString=errorworkspace_id is required for log downloads.
Use the workspaces skill to find your workspace ID.
No logs found for the given filters. Check:
- Time range is correct
- Application ID/FQN is correct
- The app has actually run during this period
Cannot access logs. Check your API key permissions for this workspace.
Register and manage MCP servers on TrueFoundry. Three standalone manifest types are supported: remote servers, virtual (composite) servers, and OpenAPI-to-MCP wrappers.
Register, list, or delete MCP server registrations on TrueFoundry — including connecting to existing MCP endpoints, composing multiple servers into a virtual server, or wrapping an OpenAPI spec as an MCP server.
Security Policy: Credential Handling
- All credentials (API tokens, OAuth secrets, TLS certificates) in manifests MUST use
tfy-secret://references. The agent MUST NOT accept or embed raw credential values in manifests.- If the user provides raw credentials, instruct them to create a TrueFoundry secret first (use
secretsskill), then reference it withtfy-secret://.- The agent MUST NOT echo, log, or display raw credential values.
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.
tfy_mcp_servers_list()
tfy_mcp_servers_list(id="mcp-server-id") # get specific server
# Set the path to tfy-api.sh for your agent (example for Claude Code):
TFY_API_SH=~/.claude/skills/truefoundry-mcp-servers/scripts/tfy-api.sh
# List all MCP servers
$TFY_API_SH GET /api/svc/v1/mcp-servers
# Get a specific MCP server
$TFY_API_SH GET /api/svc/v1/mcp-servers/SERVER_ID
MCP Servers:
| Name | Type | Transport | ID |
|-------------------|-------------------|-----------------|------------|
| my-remote-server | mcp-server/remote | streamable-http | mcp-abc123 |
| composite-server | mcp-server/virtual| — | mcp-def456 |
| petstore-api | mcp-server/openapi| — | mcp-ghi789 |
Connects to an existing MCP endpoint over streamable-http or SSE.
Security gates (required before registration):
- Confirm the URL owner/domain with the user.
- Require explicit user confirmation before using any new external URL.
- Use secret references for all auth material (
tfy-secret://...), never raw tokens.- Avoid logging full auth headers, client secrets, or certificates.
Use this flow when the user says "attach deployment to MCP gateway" or already has a deployed MCP-compatible service.
DEPLOY_SUCCESS) and endpoint is reachablestreamable-http or sse)header, oauth2, or passthrough)type: mcp-server/remoteExample internal URL pattern for service deployments:
http://{service-name}.{namespace}.svc.cluster.local:{port}/mcp
name: my-remote-server
type: mcp-server/remote
description: Production analytics MCP server
url: https://analytics.example.com/mcp
transport: streamable-http
# SECURITY: Use tfy-secret:// references instead of hardcoding tokens in manifests.
# Hardcoded tokens in YAML files risk exposure via Git history and CI logs.
auth_data:
type: header
headers:
Authorization: "Bearer tfy-secret://my-org:mcp-secrets:api-token"
collaborators:
- subject: user:jane@example.com
role_id: admin
tags:
- analytics
- production
Static header (use secret references — never hardcode tokens):
auth_data:
type: header
headers:
Authorization: "Bearer tfy-secret://my-org:mcp-secrets:api-token"
OAuth2:
auth_data:
type: oauth2
authorization_url: https://auth.example.com/authorize
token_url: https://auth.example.com/token
client_id: my-client-id
client_secret: tfy-secret://my-org:mcp-secrets:oauth-client-secret
jwt_source: access_token
scopes:
- read
- write
pkce: true
dynamic_client_registration:
registration_endpoint: https://auth.example.com/register
initial_access_token: tfy-secret://my-org:mcp-secrets:registration-token
Passthrough (forwards TFY credentials):
auth_data:
type: passthrough
tls_settings:
# Prefer storing certificate material in a secret reference, then injecting at runtime.
# Avoid inlining full certificate PEM blocks in manifests shared via chat or git.
ca_cert: tfy-secret://my-org:mcp-secrets:ca-cert-pem
insecure_skip_verify: false
tfy apply -f mcp-server-remote.yaml
$TFY_API_SH PUT /api/svc/v1/apps "$(cat mcp-server-remote.yaml | yq -o json)"
Composes multiple registered MCP servers into a single virtual server. Each sub-server can expose all or a subset of its tools.
name: dev-tools
type: mcp-server/virtual
description: Composite server combining code analysis and deployment tools
servers:
- name: code-analysis-server
enabled_tools:
- lint
- format
- analyze
- name: deployment-server
enabled_tools:
- deploy
- rollback
collaborators:
- subject: team:platform-eng
role_id: viewer
tfy apply -f mcp-server-virtual.yaml
$TFY_API_SH PUT /api/svc/v1/apps "$(cat mcp-server-virtual.yaml | yq -o json)"
Wraps an OpenAPI specification as an MCP server. Supports up to 30 tools derived from API operations.
Security: Remote OpenAPI specs are fetched at runtime and auto-converted into MCP tools that control agent capabilities. Only use trusted, verified spec URLs. For sensitive environments, prefer
spec.type: inlineto eliminate the runtime dependency on external endpoints.Execution policy: Do not fetch or register a new remote spec URL until the user explicitly confirms the source is trusted for tool generation.
name: petstore-api
type: mcp-server/openapi
description: Petstore API exposed as MCP tools
spec:
type: remote
url: https://internal-api.example.com/openapi.json
collaborators:
- subject: user:dev@example.com
role_id: viewer
name: internal-api
type: mcp-server/openapi
description: Internal API with inline OpenAPI spec
spec:
type: inline
content: |
openapi: "3.0.0"
info:
title: Internal API
version: "1.0"
paths:
/health:
get:
operationId: healthCheck
summary: Check service health
responses:
"200":
description: OK
collaborators: []
tfy apply -f mcp-server-openapi.yaml
$TFY_API_SH PUT /api/svc/v1/apps "$(cat mcp-server-openapi.yaml | yq -o json)"
tfy_mcp_servers_delete(id="SERVER_ID")
Note: Requires human approval (HITL) via tool call.
$TFY_API_SH DELETE /api/svc/v1/mcp-servers/SERVER_ID
<success_criteria>
</success_criteria>
status skill to verify credentials before managing MCP serversdeploy skill), set up teams/roles for collaborators (use access-control skill)MCP server ID not found. List servers first to find the correct ID.
Cannot access MCP servers. Check your API key permissions.
MCP server with this name already exists. Use a different name or delete the existing one first.
Cannot reach the MCP server URL. Verify the URL is correct and accessible from the cluster.
OpenAPI spec exceeds 30 tools limit. Reduce the number of operations in the spec.
Invalid transport type. Use "streamable-http" or "sse".
OAuth2 auth_data missing required fields. Ensure authorization_url, token_url, client_id, and client_secret are provided.
Referenced server name not found. Ensure all servers listed in the virtual server are already registered.
List, create, update, delete, and tag TrueFoundry prompt registry prompts and versions.
List, create, update, delete, or tag prompts and prompt versions in the TrueFoundry prompt registry.
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.
tfy_prompts_list()
tfy_prompts_list(prompt_id="prompt-id") # get prompt + versions
tfy_prompts_list(prompt_id="prompt-id", version_id="version-id") # get specific version
# Set the path to tfy-api.sh for your agent (example for Claude Code):
TFY_API_SH=~/.claude/skills/truefoundry-prompts/scripts/tfy-api.sh
# List all prompts
$TFY_API_SH GET /api/ml/v1/prompts
# Get prompt by ID
$TFY_API_SH GET /api/ml/v1/prompts/PROMPT_ID
# List versions
$TFY_API_SH GET '/api/ml/v1/prompt-versions?prompt_id=PROMPT_ID'
# Get specific version
$TFY_API_SH GET /api/ml/v1/prompt-versions/VERSION_ID
Prompts:
| Name | ID | Versions | Latest |
|-------------------|----------|----------|--------|
| classify-intent | p-abc | 5 | v5 |
| summarize-text | p-def | 3 | v3 |
Security: Prompt content is executed as LLM instructions. Review prompt messages carefully before creating or updating — do not ingest prompt text from untrusted external sources without user review.
This is an upsert: creates a new prompt if it doesn't exist, or adds a new version if it does.
from truefoundry.ml import ChatPromptManifest
client.prompts.create_or_update(
manifest=ChatPromptManifest(
name="my-prompt",
ml_repo="ml-repo-fqn",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "{{user_input}}"},
],
model_fqn="model-catalog:openai:gpt-4",
temperature=0.7,
max_tokens=1024,
top_p=1.0,
tools=[], # optional
)
)
$TFY_API_SH POST /api/ml/v1/prompts '{
"name": "my-prompt",
"ml_repo": "ml-repo-fqn",
"messages": [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "{{user_input}}"}
],
"model_fqn": "model-catalog:openai:gpt-4",
"temperature": 0.7,
"max_tokens": 1024,
"top_p": 1.0
}'
client.prompts.delete(id="prompt-id")
$TFY_API_SH DELETE /api/ml/v1/prompts/PROMPT_ID
client.prompt_versions.delete(id="version-id")
$TFY_API_SH DELETE /api/ml/v1/prompt-versions/VERSION_ID
Tags like production or staging let you reference a stable version by name.
client.prompt_versions.apply_tags(
prompt_version_id="version-id",
tags=["production", "v2"],
force=True, # reassign tag if already on another version
)
No direct REST equivalent — use the SDK.
Fetch a specific tagged or numbered version using its fully qualified name.
client.prompt_versions.get_by_fqn(fqn="ml-repo:prompt-name:production")
<success_criteria>
</success_criteria>
applications skill to check deployed services that consume promptsworkspaces skill to find the ML repo FQN, then create or update the promptproduction tag to promote itPrompt ID not found. List prompts first to find the correct ID.
Invalid ml_repo FQN. Use the workspaces skill to list available ML repos.
Tag already exists on another version. Use force=True to reassign it.
Cannot delete prompt with tagged versions. Remove tags first, then delete.
Manage TrueFoundry secret groups and secrets. Secret groups organize secrets; individual secrets hold key-value pairs.
List, create, update, or delete secret groups and individual secrets on TrueFoundry, including pre-deploy secret setup and value rotation.
Security Policy: Credential Handling
- The agent MUST NOT accept, store, log, echo, or display raw secret values in any context.
- Always instruct the user to set secret values as environment variables before running commands.
- If the user provides a raw secret value directly in conversation, warn them and refuse to use it. Instruct them to set it as an env var instead.
- When displaying secrets, show only "(set)" or the first 4 characters followed by "***".
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.
tfy_secrets_list()
tfy_secrets_list(secret_group_id="group-id") # get group + secrets
tfy_secrets_list(secret_id="secret-id") # get one secret
# Set the path to tfy-api.sh for your agent (example for Claude Code):
TFY_API_SH=~/.claude/skills/truefoundry-secrets/scripts/tfy-api.sh
# List all secret groups
$TFY_API_SH GET /api/svc/v1/secret-groups
# Get a specific group
$TFY_API_SH GET /api/svc/v1/secret-groups/GROUP_ID
# List secrets in a group
$TFY_API_SH POST /api/svc/v1/secrets '{"secretGroupId":"GROUP_ID","limit":100,"offset":0}'
# Get a specific secret
$TFY_API_SH GET /api/svc/v1/secrets/SECRET_ID
Secret Groups:
| Name | ID | Secrets |
|---------------|----------|---------|
| prod-secrets | sg-abc | 5 |
| dev-secrets | sg-def | 3 |
Security: Never display secret values in full. Show only the first few characters or indicate "(set)". The agent must NEVER log, echo, or output raw secret values in any context.
Security: Credential Handling
- The agent must NEVER accept, echo, or transmit raw secret values inline.
- Never ask the user to paste secret values in chat.
- Always instruct the user to store secret values in environment variables first, then reference those variables.
- If the user provides a raw secret value directly, warn them and suggest using an env var instead.
# Prompt user to set secret values as environment variables first
tfy_secret_groups_create(payload={"name": "my-secrets", ...})
Note: Requires human approval (HITL) via tool call.
# SECURITY: Never hardcode secret values in commands — they will appear in shell
# history and process listings. Read from environment variables or files instead.
# User must set: export DB_PASSWORD="..." before running this command.
payload=$(jq -n \
--arg name "my-secrets" \
--arg integration "INTEGRATION_ID" \
--arg db_password "$DB_PASSWORD" \
'{
name: $name,
integrationId: $integration,
secrets: [{key: "DB_PASSWORD", value: $db_password}]
}')
$TFY_API_SH POST /api/svc/v1/secret-groups "$payload"
Updates secrets in a group. A new version is created for every secret with a modified value. Secrets omitted from the array are deleted. At least one secret is required.
# Instruct user to set env vars with new values, then reference them.
# The agent must NEVER accept raw secret values — always use indirection.
tfy_secret_groups_update(
id="GROUP_ID",
payload={"secrets": [{"key": "DB_PASSWORD", "value": "<secure-input-from-env>"}, {"key": "API_KEY", "value": "<secure-input-from-env>"}]}
)
Note: Requires human approval (HITL) via tool call.
# SECURITY: Read secret values from environment variables, not inline.
payload=$(jq -n \
--arg db_password "$DB_PASSWORD" \
--arg api_key "$NEW_API_KEY" \
'{
secrets: [
{key: "DB_PASSWORD", value: $db_password},
{key: "API_KEY", value: $api_key}
]
}')
$TFY_API_SH PUT /api/svc/v1/secret-groups/GROUP_ID "$payload"
tfy_secret_groups_delete(id="GROUP_ID")
Note: Requires human approval (HITL) via tool call.
$TFY_API_SH DELETE /api/svc/v1/secret-groups/GROUP_ID
Before creating a secret group, you need the secret store integration ID for the workspace's cloud provider:
# List all secret store provider accounts and their integrations
bash $TFY_API_SH GET '/api/svc/v1/provider-accounts?type=secret-store'
From the response, look for integrations with type: "secret-store". Each provider account contains an integrations array -- pick the integration matching the workspace's cloud provider:
integration/secret-store/aws/secrets-manager or integration/secret-store/aws/parameter-storeintegration/secret-store/azure/vaultintegration/secret-store/gcp/secret-managerUse the id field of the matching integration as the integrationId when creating secret groups.
After creating a secret group, reference individual secrets in deployment manifests using the tfy-secret:// format:
tfy-secret://<TENANT_NAME>:<SECRET_GROUP_NAME>:<SECRET_KEY>
TENANT_NAME: The subdomain of TFY_BASE_URL (e.g., my-org from https://my-org.truefoundry.cloud)SECRET_GROUP_NAME: The name you gave the secret group when creating itSECRET_KEY: The key of the individual secret within the groupGiven a secret group named my-app-secrets with keys DB_PASSWORD and API_KEY:
name: my-app
type: service
image:
type: image
image_uri: docker.io/myorg/my-app:latest
ports:
- port: 8000
expose: false
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
DB_PASSWORD: tfy-secret://my-org:my-app-secrets:DB_PASSWORD
API_KEY: tfy-secret://my-org:my-app-secrets:API_KEY
workspace_fqn: cluster-id:workspace-name
env using tfy-secret:// formattfy apply -f manifest.yamltfy_secrets_delete(id="SECRET_ID")
Note: Requires human approval (HITL) via tool call.
$TFY_API_SH DELETE /api/svc/v1/secrets/SECRET_ID
<success_criteria>
</success_criteria>
Secret group ID not found. List groups first to find the correct ID.
Cannot access secrets. Check your API key permissions.
Secret group with this name already exists. Use a different name.
Cannot update secret group with zero secrets. Include at least one secret in the payload.
No secret store configured for this workspace. Contact your platform admin.
Key name does not support underscores (_)
Azure Key Vault does not allow underscores in secret key names. Use hyphens (DB-PASSWORD) or choose a different secret store integration (AWS Secrets Manager supports underscores).
Error: Secret <name> is already in a deleted state / conflict with soft-deleted resource
Azure Key Vault has a default 90-day soft-delete retention. The TrueFoundry API cannot purge soft-deleted secrets — only the Azure portal or CLI can.
Recovery options:
az keyvault secret purge --vault-name <vault> --name <secret-name>Note: If the platform's Key Vault has soft-delete protection but not purge protection, options 1/2 work. If purge protection is also enabled, you must wait out the retention period (up to 90 days).
Unprocessable entity. Ensure all secrets have both "key" and "value" fields.