Publishing Agents to Traylinx Catalog¶

Learn how to publish your agents to the Traylinx catalog and make them discoverable by other users.

Overview¶

Publishing agents allows you to share your work with the Traylinx community. The publishing process uses Sentinel Pass authentication to verify your identity and ensure secure agent distribution.

Quick Start¶

# 1. Create your developer identity (ONE TIME)
traylinx sentinel pass create --name my-developer-identity

# 2. Set environment variables (ONE TIME - add to ~/.zshrc)
export TRAYLINX_DEVELOPER_AGENT_ID="agent-user-xxx"
export TRAYLINX_DEVELOPER_SECRET="secret-xxx"

# 3. Publish your agent (EVERY TIME)
traylinx publish

Understanding Sentinel Passes¶

The Two-Pass Model¶

Publishing requires understanding TWO different types of Sentinel Passes:

Developer Sentinel Pass¶

What it is: YOUR identity for publishing agents
Created: Once per developer
Used by: traylinx publish command
Purpose: Authenticates YOU when publishing

traylinx sentinel pass create --name my-developer-identity

Agent Sentinel Pass¶

What it is: The AGENT's runtime identity
Created: Once per agent
Used by: The agent when it runs
Purpose: Authenticates the AGENT during execution

traylinx sentinel pass create --name my-weather-agent

Why Two Different Passes?¶

This separation provides:

Access Control: Revoke developer access without affecting running agents
Auditing: Track who published what
Team Collaboration: Multiple developers can publish the same agent
Security: Agent credentials separate from developer credentials

Step-by-Step Guide¶

Prerequisites¶

Traylinx CLI installed:
```
npm install -g traylinx-cli
```
Logged in:
```
traylinx login
```
Agent manifest created:
```
traylinx init
```

Step 1: Create Developer Sentinel Pass¶

This is a ONE-TIME setup:

$ traylinx sentinel pass create --name my-developer-identity

Output:

✅ Sentinel Pass created successfully!

   Pass ID:       SP-2026-abc123
   Agent Name:    my-developer-identity
   Agent ID:      agent-user-789abc
   Client ID:     oauth-client-456def
   Client Secret: secret-xyz123...
   Saved to:      ~/.traylinx/agents/my-developer-identity/credentials.json

⚠ The client_secret is shown ONCE. Store it securely!

Important: Save the Agent ID and Client Secret!

Step 2: Configure Environment¶

Add to your shell profile (~/.zshrc or ~/.bashrc):

# Traylinx Developer Credentials
export TRAYLINX_DEVELOPER_AGENT_ID="agent-user-789abc"
export TRAYLINX_DEVELOPER_SECRET="secret-xyz123..."

Reload your shell:

source ~/.zshrc

Step 3: Verify Configuration¶

$ traylinx status

Look for:

⚙️  Configuration
Environment: dev
Registry: https://discovery.traylinx.com
Publishing Identity: ✓ Configured (agent-user-789abc)

Step 4: Publish Your Agent¶

$ cd /path/to/your/agent
$ traylinx publish

Success output:

Publishing to Traylinx Catalog

✓ Manifest valid: my-weather-agent v1.0.0
✓ Registry: https://discovery.traylinx.com
✓ Publishing Identity: agent-user-789abc

Publishing...

╭─────────────────────────────────────────╮
│ 🚀 Published                            │
│                                         │
│ Published successfully!                 │
│                                         │
│ Agent: my-weather-agent                 │
│ Version: 1.0.0                          │
│                                         │
│ View in catalog:                        │
│   https://discovery.traylinx.com/...   │
╰─────────────────────────────────────────╯

Credential Storage¶

All credentials are stored securely in ~/.traylinx/:

~/.traylinx/
├── credentials.json              # OAuth login
├── context.json                  # Current org/project
├── agents/                       # Sentinel Passes
│   ├── my-developer-identity/
│   │   └── credentials.json      # Developer Pass
│   └── my-weather-agent/
│       └── credentials.json      # Agent Pass
└── keys/                         # API keys
    └── key-abc123_production.json

Security: - Files created with 0600 permissions (owner read/write only) - Stored in your home directory - Consider backing up ~/.traylinx/agents/

Common Issues¶

Publishing Identity Not Configured¶

Symptom:

⚙️  Configuration
Publishing Identity: ✗ Not configured

Solution: 1. Create Sentinel Pass:

traylinx sentinel pass create --name my-developer-identity

Set environment variables:

export TRAYLINX_DEVELOPER_AGENT_ID="agent-user-xxx"
export TRAYLINX_DEVELOPER_SECRET="secret-xxx"

Verify:
```
traylinx status
```

401 Unauthorized Error¶

Causes: - Wrong TRAYLINX_DEVELOPER_AGENT_ID - Wrong TRAYLINX_DEVELOPER_SECRET - Sentinel Pass deleted or expired

Solution: 1. Verify credentials:

traylinx sentinel pass show my-developer-identity

If needed, create new pass:

traylinx sentinel pass create --name my-developer-identity-2

Advanced Usage¶

Dry Run¶

Test publishing without actually publishing:

traylinx publish --dry-run

Custom Registry¶

Publish to a different registry:

traylinx publish --registry http://localhost:8000

Custom Manifest¶

Use a different manifest file:

traylinx publish --manifest /path/to/manifest.yaml

Managing Sentinel Passes¶

List All Passes¶

$ traylinx sentinel pass list

Sentinel Passes
┏━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ Name                   ┃ Pass ID      ┃ Agent ID    ┃ Created    ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ my-developer-identity  │ SP-2026-abc  │ agent-us... │ 2026-02-05 │
└────────────────────────┴──────────────┴─────────────┴────────────┘

Show Pass Details¶

$ traylinx sentinel pass show my-developer-identity

╭─────────────────────────────────────────╮
│ Sentinel Pass: my-developer-identity    │
│                                         │
│ Pass ID:     SP-2026-abc123             │
│ Agent ID:    agent-user-789abc          │
│ Client ID:   oauth-client-456def        │
│ Agent Type:  service                    │
│ Project:     proj-xxx                   │
│ Created:     2026-02-05T10:30:00        │
│ Linked:      Yes                        │
╰─────────────────────────────────────────╯

Delete Pass¶

# Delete local only
traylinx sentinel pass delete my-developer-identity

# Delete local AND revoke remote
traylinx sentinel pass delete my-developer-identity --remote

FAQ¶

Q: Do I need a Sentinel Pass for every agent?
A: No! You need ONE developer pass for publishing, and ONE agent pass per agent for runtime.

Q: Can multiple developers publish the same agent?
A: Yes! Each developer uses their own Sentinel Pass. The registry tracks who published what.

Q: What if I lose my credentials?
A: Create a new Sentinel Pass and update your environment variables.

Q: Where are credentials stored?
A: In ~/.traylinx/agents/<name>/credentials.json with 0600 permissions.

Q: Can I share my Sentinel Pass?
A: No! Each developer should have their own Sentinel Pass for security and auditing.

Next Steps¶

CLI Reference: Traylinx CLI Documentation
Agent Development: Getting Started Guide
API Reference: Agent Registry API

Need help? Contact support or visit the Traylinx Community