LLM Reference

This section provides documentation optimized for Large Language Models (LLMs) to understand and use Vultrino effectively.

Quick Reference

What is Vultrino?

Vultrino is a credential proxy that allows applications (including AI agents) to make authenticated API requests without seeing the actual credentials.

Key Concept: You use credential aliases (like "github-api"), not actual secrets.

Available Paths

For programmatic access to documentation, these raw markdown paths are available:

Condensed Reference

Making Authenticated Requests

Via HTTP API (vultrino web, default port 7879):

curl -sX POST http://localhost:7879/api/v1/execute \
     -H "Authorization: Bearer vk_your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{"credential": "<alias>", "method": "GET", "url": "https://target-api.com/endpoint"}'

Via MCP (AI Agents):

{
  "tool": "http_request",
  "arguments": {
    "api_key": "vk_your_api_key_here",
    "credential": "<alias>",
    "method": "GET",
    "url": "https://target-api.com/endpoint"
  }
}

Via CLI (requires running Vultrino web server):

vultrino --key vk_your_api_key request <alias> https://target-api.com/endpoint

MCP Tools Summary

Important: Every tool call requires an api_key parameter for authentication. This value may be a regular API key (vk_…) or a use token (vut_…) — a single-use or time-scoped grant restricted to one credential/action.

Approval gating: If a request requires human approval, http_request returns an "APPROVAL REQUIRED" message with an approval_id and the action does not run. Poll check_approval with that id (re-sending your api_key) every ~10–30 seconds; once a human approves, it returns the real result. A denied/expired approval tells you to stop — do not retry.

Common Credential Aliases

Typical naming patterns:

• github-api — GitHub API token
• stripe-live / stripe-test — Stripe API keys
• openai — OpenAI API key
• anthropic — Anthropic API key
• aws-prod / aws-staging — AWS credentials

For AI Agents

Authentication Model: Every tool call requires your API key. This enables multiple agents to use the same MCP server with different scoped keys.

Step 1: Check Available Credentials

{
  "tool": "list_credentials",
  "arguments": {
    "api_key": "vk_your_api_key_here"
  }
}

Response:

{
  "credentials": [
    {"alias": "github-api", "type": "api_key", "description": "..."},
    {"alias": "stripe-test", "type": "api_key", "description": "..."}
  ]
}

Step 2: Make Request

{
  "tool": "http_request",
  "arguments": {
    "api_key": "vk_your_api_key_here",
    "credential": "github-api",
    "method": "GET",
    "url": "https://api.github.com/user"
  }
}

Response:

{
  "status": 200,
  "headers": {"content-type": "application/json"},
  "body": "{\"login\":\"username\",...}"
}

Step 3: Parse Response

The body field is a JSON string. Parse it to access the data.

Error Handling

If a credential isn't available:

1. List what IS available
2. Explain to user
3. Offer alternatives

Example response to user:

"I don't have access to AWS credentials. I can access: github-api, stripe-test. Would you like to add AWS credentials?"

HTTP API Quick Reference

Base URL http://127.0.0.1:7879 (served by vultrino web). All routes are under /api/v1/. Authenticate every call with Authorization: Bearer vk_… (API key) or vut_… (use token). There is no credential header and no transparent proxy.

Execute an action

POST /api/v1/execute
Authorization: Bearer <vk_ or vut_ token>
Content-Type: application/json

{"credential": "<alias>", "method": "GET", "url": "https://api.example.com/endpoint"}

The body is flat; action is optional (defaults to http.request). Optional headers, body, and query fields are also accepted.

List Credentials

GET /api/v1/credentials
Authorization: Bearer <vultrino-api-key>

Configuration Summary

Environment Variables

• VULTRINO_PASSWORD — Storage encryption password (required)
• VULTRINO_CONFIG — Config file path
• RUST_LOG — Log level

Default Ports

• 7879 — vultrino web: HTTP JSON API (/api/v1/…, /mcp, /llm) and the HTML admin UI
• stdio — vultrino mcp: MCP server for local AI agents (no port)

File Locations

• ~/.local/share/vultrino/credentials.enc — Encrypted vault (default; ~/ path is configurable)
• Config: --config <path>, else the OS config dir (~/.config/vultrino/config.toml on Linux)

Security Model

1. Credentials encrypted at rest — AES-256-GCM
2. Aliases only — Raw credential fields are absent from the LLM-facing schema
3. RBAC — Role-based access control via API keys
4. Policies — URL/method restrictions
5. Audit logging — Track all usage

API Key Authentication

Vultrino uses per-request API key authentication. Include your API key in every tool call:

{
  "tool": "list_credentials",
  "arguments": {
    "api_key": "vk_your_api_key_here"
  }
}

This design enables:

• Multiple agents using the same MCP server with different keys
• Scoped access - each key has its own permissions and credential access
• No session state - stateless, secure by default

The API key determines what credentials you can access based on your assigned role:

Every tool call requires the api_key parameter.

Common Tasks

"List my credentials"

{"tool": "list_credentials", "arguments": {"api_key": "vk_..."}}

"Get my GitHub user info"

{
  "tool": "http_request",
  "arguments": {
    "api_key": "vk_...",
    "credential": "github-api",
    "method": "GET",
    "url": "https://api.github.com/user"
  }
}

"Create a Stripe customer"

{
  "tool": "http_request",
  "arguments": {
    "api_key": "vk_...",
    "credential": "stripe-api",
    "method": "POST",
    "url": "https://api.stripe.com/v1/customers",
    "headers": {"Content-Type": "application/x-www-form-urlencoded"},
    "body": "[email protected]"
  }
}

"List GitHub repos"

{
  "tool": "http_request",
  "arguments": {
    "api_key": "vk_...",
    "credential": "github-api",
    "method": "GET",
    "url": "https://api.github.com/user/repos"
  }
}