Skip to content
Back to search

station

Station is our open-source runtime that lets teams deploy agents on their own infrastructure with full control.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/cloudshipai--station/badge.svg)](/listings/cloudshipai--station)

HTML

<a href="/listings/cloudshipai--station"><img src="/api/listings/cloudshipai--station/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Prerequisites

- **Docker** - Required for Jaeger (traces and observability) - **AI Provider** - Choose one: - **CloudShip AI** (Recommended) - `STN_CLOUDSHIP_KEY` or `CLOUDSHIPAI_REGISTRATION_KEY` - `OPENAI_API_KEY` - OpenAI (gpt-5-mini, gpt-5, etc.) - `GEMINI_API_KEY` - Google Gemini - `ANTHROPIC_API_KEY` - Anthropic (claude-sonnet-4-20250514, etc.)

1. Install Station

curl -fsSL https://raw.githubusercontent.com/cloudshipai/station/main/install.sh | bash

2. Initialize Station

Choose your AI provider:

<details open> <summary><b>CloudShip AI (Recommended)</b></summary>

Use CloudShip AI for optimized inference with Llama and Qwen models. This is the default when a registration key is available.

# Set your CloudShip registration key
export CLOUDSHIPAI_REGISTRATION_KEY="csk-..."
# Or use: export STN_CLOUDSHIP_KEY="csk-..."

stn init --provider cloudshipai --ship  # defaults to cloudship/llama-3.1-70b

**Available models:** - `cloudship/llama-3.1-70b` (default) - Best balance of performance and cost - `cloudship/llama-3.1-8b` - Faster, lower cost - `cloudship/qwen-72b` - Alternative large model

</details>

<details> <summary><b>Claude Max/Pro Subscription (⚠️ DEPRECATED)</b></summary>

> **⚠️ DEPRECATED: Anthropic OAuth is currently unavailable.** > > Anthropic has restricted third-party use of OAuth tokens. This authentication method is not working until further notice. > > **Please use one of the following alternatives:** > - **OpenAI API Key** (recommended) > - **Google Gemini API Key** > - **Anthropic API Key** (pay-per-token, not subscription-based)

~~Use your existing Claude Max or Claude Pro subscription - no API billing required.~~

# ❌ NOT WORKING - Anthropic OAuth disabled
# stn init --provider anthropic --ship
# stn auth anthropic login

</details>

<details> <summary><b>OpenAI (API Key)</b></summary>

export OPENAI_API_KEY="sk-..."
stn init --provider openai --ship  # defaults to gpt-5-mini

</details>

<details> <summary><b>Google Gemini (API Key)</b></summary>

export GEMINI_API_KEY="..."
stn init --provider gemini --ship

</details>

This sets up: - ✅ Your chosen AI provider - ✅ [Ship CLI](https://github.com/cloudshipai/ship) for filesystem MCP tools - ✅ Configuration at `~/.config/station/config.yaml`

3. Start Jaeger (Tracing)

Start the Jaeger tracing backend for observability:

stn jaeger up

This starts Jaeger UI at [http://localhost:16686](http://localhost:16686) for viewing agent execution traces.

4. Connect Your MCP Client

Choose your editor and add Station:

<details> <summary><b>Claude Code CLI</b></summary>

claude mcp add station -e OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 --scope user -- stn stdio

Verify with `claude mcp list`.

</details>

<details> <summary><b>OpenCode</b></summary>

Add to `opencode.jsonc`:

{
  "mcp": {
    "station": {
      "enabled": true,
      "type": "local",
      "command": ["stn", "stdio"],
      "environment": {
        "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4318"
      }
    }
  }
}

</details>

<details> <summary><b>Cursor</b></summary>

Add to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for global):

{
  "mcpServers": {
    "station": {
      "command": "stn",
      "args": ["stdio"],
      "env": {
        "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4318"
      }
    }
  }
}

</details>

<details> <summary><b>Claude Desktop</b></summary>

| OS | Config Path | |-----|------| | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` | | Windows | `%APPDATA%\Claude\claude_desktop_config.json` | | Linux | `~/.config/Claude/claude_desktop_config.json` |

{
  "mcpServers": {
    "station": {
      "command": "stn",
      "args": ["stdio"],
      "env": {
        "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4318"
      }
    }
  }
}

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 39 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "cloudshipai-station",
  3. "owner": {
  4. "name": "CloudShip AI",
  5. "email": "hello@cloudshipai.com"
  6. },
  7. "metadata": {
  8. "description": "Station AI agent orchestration platform plugins",
  9. "version": "1.0.0"
  10. },
  11. "plugins": [
  12. {
  13. "name": "station",
  14. "source": "./claude-code-plugin",
  15. "description": "Lightweight Station integration with skills and slash commands - guides Claude through Station operations",
  16. "version": "1.0.0",
  17. "author": {
  18. "name": "CloudShip AI"
  19. },
  20. "homepage": "https://docs.cloudshipai.com/station/overview",
  21. "repository": "https://github.com/cloudshipai/station",
  22. "license": "Apache-2.0",
  23. "keywords": ["station", "agents", "mcp", "orchestration", "ai", "cloudship", "sre", "devops", "skills"]
  24. },
  25. {
  26. "name": "station-agent",
  27. "source": "./claude-code-plugin-agent",
  28. "description": "Full Station integration with pre-configured subagent - autonomous Station operations via dedicated expert agent",
  29. "version": "1.0.0",
  30. "author": {
  31. "name": "CloudShip AI"
  32. },
  33. "homepage": "https://docs.cloudshipai.com/station/overview",
  34. "repository": "https://github.com/cloudshipai/station",
  35. "license": "Apache-2.0",
  36. "keywords": ["station", "agents", "mcp", "orchestration", "ai", "cloudship", "sre", "devops", "subagent"]
  37. }
  38. ]
  39. }
README.md · README · 1,741 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ![Station](./station-logo.png)
  2. # Station - AI Agent Orchestration Platform
  3. [![Test Coverage](https://img.shields.io/badge/coverage-52.7%25-yellow?style=flat-square)](./TESTING_PROGRESS.md) [![Go Tests](https://img.shields.io/badge/tests-passing-brightgreen?style=flat-square)](./.github/workflows/ci.yml)
  4. **Build, test, and deploy intelligent agent teams. Self-hosted. Git-backed. Production-ready.**
  5. [Quick Start](#quick-start) | [Real Example](#real-example-sre-incident-response-team) | [Deploy](#deploy-to-production) | [Documentation](https://docs.cloudshipai.com)
  6. ---
  7. ## Why Station?
  8. Build multi-agent systems that coordinate like real teams. Test with realistic scenarios. Deploy on your infrastructure.
  9. **Station gives you:**
  10. - ✅ **Multi-Agent Teams** - Coordinate specialist agents under orchestrators
  11. - ✅ **Built-in Evaluation** - LLM-as-judge tests every agent automatically
  12. - ✅ **Git-Backed Workflow** - Version control agents like code
  13. - ✅ **One-Command Deploy** - Push to production with `stn deploy`
  14. - ✅ **Full Observability** - Jaeger traces for every execution
  15. - ✅ **Self-Hosted** - Your data, your infrastructure, your control
  16. ---
  17. ## Quick Start (2 minutes)
  18. ### Prerequisites
  19. - **Docker** - Required for Jaeger (traces and observability)
  20. - **AI Provider** - Choose one:
  21. - **CloudShip AI** (Recommended) - `STN_CLOUDSHIP_KEY` or `CLOUDSHIPAI_REGISTRATION_KEY`
  22. - `OPENAI_API_KEY` - OpenAI (gpt-5-mini, gpt-5, etc.)
  23. - `GEMINI_API_KEY` - Google Gemini
  24. - `ANTHROPIC_API_KEY` - Anthropic (claude-sonnet-4-20250514, etc.)
  25. ### 1. Install Station
  26. ```bash
  27. curl -fsSL https://raw.githubusercontent.com/cloudshipai/station/main/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 41 on GitHub
  28. ```
  29. ### 2. Initialize Station
  30. Choose your AI provider:
  31. <details open>
  32. <summary><b>CloudShip AI (Recommended)</b></summary>
  33. Use CloudShip AI for optimized inference with Llama and Qwen models. This is the default when a registration key is available.
  34. ```bash
  35. # Set your CloudShip registration key
  36. export CLOUDSHIPAI_REGISTRATION_KEY="csk-..."
  37. # Or use: export STN_CLOUDSHIP_KEY="csk-..."
  38. stn init --provider cloudshipai --ship # defaults to cloudship/llama-3.1-70b
  39. ```
  40. **Available models:**
  41. - `cloudship/llama-3.1-70b` (default) - Best balance of performance and cost
  42. - `cloudship/llama-3.1-8b` - Faster, lower cost
  43. - `cloudship/qwen-72b` - Alternative large model
  44. </details>
  45. <details>
  46. <summary><b>Claude Max/Pro Subscription (⚠️ DEPRECATED)</b></summary>
  47. > **⚠️ DEPRECATED: Anthropic OAuth is currently unavailable.**
  48. >
  49. > Anthropic has restricted third-party use of OAuth tokens. This authentication method is not working until further notice.
  50. >
  51. > **Please use one of the following alternatives:**
  52. > - **OpenAI API Key** (recommended)
  53. > - **Google Gemini API Key**
  54. > - **Anthropic API Key** (pay-per-token, not subscription-based)
  55. ~~Use your existing Claude Max or Claude Pro subscription - no API billing required.~~
  56. ```bash
  57. # ❌ NOT WORKING - Anthropic OAuth disabled
  58. # stn init --provider anthropic --ship
  59. # stn auth anthropic login
  60. ```
  61. </details>
  62. <details>
  63. <summary><b>OpenAI (API Key)</b></summary>
  64. ```bash
  65. export OPENAI_API_KEY="sk-..."
  66. stn init --provider openai --ship # defaults to gpt-5-mini
  67. ```
  68. </details>
  69. <details>
  70. <summary><b>Google Gemini (API Key)</b></summary>
  71. ```bash
  72. export GEMINI_API_KEY="..."
  73. stn init --provider gemini --ship
  74. ```
  75. </details>
  76. This sets up:
  77. - ✅ Your chosen AI provider
  78. - ✅ [Ship CLI](https://github.com/cloudshipai/ship) for filesystem MCP tools
  79. - ✅ Configuration at `~/.config/station/config.yaml`
  80. ### 3. Start Jaeger (Tracing)
  81. Start the Jaeger tracing backend for observability:
  82. ```bash
  83. stn jaeger up
  84. ```
  85. This starts Jaeger UI at [http://localhost:16686](http://localhost:16686) for viewing agent execution traces.
  86. ### 4. Connect Your MCP Client
  87. Choose your editor and add Station:
  88. <details>
  89. <summary><b>Claude Code CLI</b></summary>
  90. ```bash
  91. claude mcp add station -e OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 --scope user -- stn stdio
  92. ```
  93. Verify with `claude mcp list`.
  94. </details>
  95. <details>
  96. <summary><b>OpenCode</b></summary>
  97. Add to `opencode.jsonc`:
  98. ```jsonc
  99. {
  100. "mcp": {
  101. "station": {
  102. "enabled": true,
  103. "type": "local",
  104. "command": ["stn", "stdio"],
  105. "environment": {
  106. "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4318"
  107. }
  108. }
  109. }
  110. }
  111. ```
  112. </details>
  113. <details>
  114. <summary><b>Cursor</b></summary>
  115. Add to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for global):
  116. ```json
  117. {
  118. "mcpServers": {
  119. "station": {
  120. "command": "stn",
  121. "args": ["stdio"],
  122. "env": {
  123. "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4318"
  124. }
  125. }
  126. }
  127. }
  128. ```
  129. </details>
  130. <details>
  131. <summary><b>Claude Desktop</b></summary>
  132. | OS | Config Path |
  133. |-----|------|
  134. | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
  135. | Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
  136. | Linux | `~/.config/Claude/claude_desktop_config.json` |
  137. ```json
  138. {
  139. "mcpServers": {
  140. "station": {
  141. "command": "stn",
  142. "args": ["stdio"],
  143. "env": {
  144. "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4318"
  145. }
  146. }
  147. }
  148. }
  149. ```
  150. </details>
  151. **Optional GitOps:** Point to a Git-backed workspace:
  152. ```json
  153. "command": ["stn", "--config", "/path/to/my-agents/config.yaml", "stdio"]
  154. ```
  155. ### 5. Install Editor Plugins (Optional)
  156. Get skills, slash commands, and enhanced documentation for your AI editor:
  157. <details>
  158. <summary><b>Claude Code Plugin</b></summary>
  159. Adds `/station` commands, skills for agent creation, and MCP server config.
  160. ```bash
  161. # Add Station marketplace and install plugin
  162. /plugin marketplace add cloudshipai/station
  163. /plugin install station@cloudshipai-station
  164. ```
  165. Or install from local clone:
  166. ```bash
  167. /plugin install ./station/claude-code-plugin
  168. ```
  169. </details>
  170. <details>
  171. <summary><b>OpenCode Skill</b></summary>
  172. Adds Station CLI reference skill with agent, workflow, and deployment docs.
  173. ```bash
  174. # Copy skill to your project
  175. cp -r station/opencode-plugin/.opencode .
  176. # Or install globally
  177. cp -r station/opencode-plugin/.opencode ~/.config/opencode/
  178. ```
  179. Restart OpenCode - skill auto-loads.
  180. </details>
  181. ### 6. Start Building
  182. Restart your editor. Station provides:
  183. - ✅ **Web UI** at `http://localhost:8585` for configuration
  184. - ✅ **Jaeger UI** at `http://localhost:16686` for traces
  185. - ✅ **41 MCP tools** available in your AI assistant
  186. **Try your first command:**
  187. ```
  188. "Show me all Station MCP tools available"
  189. ```
  190. <details>
  191. <summary><b>Interactive Onboarding Guide (3-5 min tutorial)</b></summary>
  192. Copy this prompt into your AI assistant for a hands-on tour:
  193. ```
  194. You are my Station onboarding guide. Walk me through an interactive hands-on tutorial.
  195. RULES:
  196. 1. Create a todo list to track progress through each section
  197. 2. At each section, STOP and let me engage before continuing
  198. 3. Use Station MCP tools to demonstrate - don't just explain, DO IT
  199. 4. Keep it fun and celebrate wins!
  200. THE JOURNEY:
  201. ## 1. Hello World Agent
  202. - Create a "hello-world" agent that greets users and tells a joke
  203. - Call the agent and show the result
  204. [STOP for me to try it]
  205. ## 2. Faker Tools & MCP Templates
  206. - Explain Faker tools (AI-generated mock data for safe development)
  207. - Note: Real MCP tools are added via Station UI or template.json
  208. - Explain MCP templates - they keep credentials safe when deploying
  209. - Create a "prometheus-metrics" faker for realistic metrics
  210. [STOP to see the faker]
  211. ## 3. DevOps Investigation Agent
  212. - Create a "metrics-investigator" agent using our prometheus faker
  213. - Call it: "Check for performance issues in the last hour"
  214. [STOP to review the investigation]
  215. ## 4. Multi-Agent Hierarchy
  216. - Create an "incident-coordinator" that delegates to:
  217. - metrics-investigator (existing)
  218. - logs-investigator (new - create a logs faker)
  219. - Show hierarchy structure in the .prompt file
  220. - Call coordinator: "Investigate why the API is slow"
  221. [STOP to see delegation]
  222. ## 5. Inspecting Runs
  223. - Use inspect_run to show detailed execution
  224. - Explain: tool calls, delegations, timing
  225. [STOP to explore]
  226. ## 6. Workflow with Human-in-the-Loop
  227. - Create a workflow: investigate → switch on severity → human_approval if high → report
  228. - Make it complex (switch/parallel), not sequential
  229. - Start the workflow
  230. [STOP for me to approve/reject]
  231. ## 7. Evaluation & Reporting
  232. - Run evals with evaluate_benchmark
  233. - Generate a performance report
  234. [STOP to review]
  235. ## 8. Grand Finale
  236. - Direct me to http://localhost:8585 (Station UI)
  237. - Quick tour: Agents, MCP servers, Runs, Workflows
  238. - Celebrate!
  239. ## 9. Want More? (Optional)
  240. Briefly explain these advanced features (no demo needed):
  241. - **Schedules**: Cron-based agent scheduling
  242. - **Sandboxes**: Isolated code execution (Python/Node/Bash)
  243. - **Notify Webhooks**: Send alerts to Slack, ntfy, Discord
  244. - **Bundles**: Package and share agent teams
  245. - **Deploy**: `stn deploy` to Fly.io, Docker, K8s
  246. - **CloudShip**: Centralized management and team OAuth
  247. Start now with Section 1!
  248. ```
  249. </details>
  250. ---
  251. ## Running Station with `stn up`
  252. The easiest way to run Station is with `stn up` - a single command that starts Station in a Docker container with everything configured.
  253. ### Primary Use Case: Running Bundles
  254. `stn up` is designed to make it trivial to run agent bundles from your CloudShip account or the community:
  255. ```bash
  256. # Run a bundle from CloudShip (by ID or name)
  257. stn up --bundle finops-cost-analyzer
  258. # Run a bundle from URL
  259. stn up --bundle https://example.com/my-bundle.tar.gz
  260. # Run a local bundle file
  261. stn up --bundle ./my-custom-agents.tar.gz
  262. ```
  263. This is the recommended way for most users to get started - just pick a bundle and go.
  264. ### Secondary Use Case: Testing Local Configurations
  265. Developers can also use `stn up` to test their local agent configurations in an isolated container environment:
  266. ```bash
  267. # Test your local workspace in a container
  268. stn up --workspace ~/my-agents
  269. # Test with a specific environment
  270. stn up --environment production
  271. # Test with development tools enabled
  272. stn up --develop
  273. ```
  274. This lets you validate that your agents work correctly in the same containerized environment they'll run in production.
  275. ### Quick Commands
  276. ```bash
  277. # Start Station (interactive setup on first run)
  278. stn up
  279. # Start with specific AI provider
  280. stn up --provider openai --model gpt-5
  281. # Check status
  282. stn status
  283. # View logs
  284. stn logs -f
  285. # Stop Station
  286. stn down
  287. # Stop and remove all data (fresh start)
  288. stn down --remove-volume
  289. ```
  290. ### What `stn up` Provides
  291. | Service | Port | Description |
  292. |---------|------|-------------|
  293. | Web UI | 8585 | Configuration interface |
  294. | MCP Server | 8586 | Main MCP endpoint for tools |
  295. | Agent MCP | 8587 | Dynamic agent execution |
  296. | Jaeger UI | 16686 | Distributed tracing |
  297. **[See Container Lifecycle](https://docs.cloudshipai.com/station/container-lifecycle) for detailed architecture.**
  298. ---
  299. ## AI Provider Authentication
  300. Station supports multiple authentication methods for AI providers.
  301. ### API Keys (Default)
  302. The simplest way to authenticate - set your API key as an environment variable:
  303. ```bash
  304. # CloudShip AI (Recommended - auto-detected when registration key is set)
  305. export CLOUDSHIPAI_REGISTRATION_KEY="csk-..."
  306. # Or: export STN_CLOUDSHIP_KEY="csk-..."
  307. # OpenAI
  308. export OPENAI_API_KEY="sk-..."
  309. # Google Gemini
  310. export GEMINI_API_KEY="..."
  311. # Anthropic (API billing)
  312. export ANTHROPIC_API_KEY="sk-ant-api03-..."
  313. ```
  314. ### Anthropic OAuth (Claude Max/Pro Subscription) - ⚠️ DEPRECATED
  315. > **⚠️ DEPRECATED: Anthropic OAuth is currently unavailable.**
  316. >
  317. > Anthropic has restricted third-party use of OAuth tokens. This authentication method is **not working until further notice**.
  318. >
  319. > **Use these alternatives instead:**
  320. > - `OPENAI_API_KEY` for OpenAI models (recommended)
  321. > - `GEMINI_API_KEY` for Google Gemini models
  322. > - `ANTHROPIC_API_KEY` for Anthropic API (pay-per-token billing)
  323. <details>
  324. <summary>Previous OAuth documentation (for reference only)</summary>
  325. ~~Use your Claude Max or Claude Pro subscription instead of pay-per-token API billing.~~
  326. **Setup (NOT WORKING):**
  327. ```bash
  328. # ❌ DEPRECATED - Anthropic OAuth disabled
  329. # stn auth anthropic login
  330. ```
  331. **Authentication Priority:**
  332. | Priority | Method | Description |
  333. |----------|--------|-------------|
  334. | 1 | `STN_AI_AUTH_TYPE=api_key` | Force API key mode (override) |
  335. | ~~2~~ | ~~Station OAuth tokens~~ | ~~From `stn auth anthropic login`~~ **DEPRECATED** |
  336. | ~~3~~ | ~~Claude Code credentials~~ | ~~From `~/.claude/.credentials.json`~~ **DEPRECATED** |
  337. | 4 | `ANTHROPIC_API_KEY` env var | Standard API key (**USE THIS**) |
  338. </details>
  339. **For Anthropic models, use API key authentication:**
  340. ```bash
  341. # Set Anthropic API key
  342. export ANTHROPIC_API_KEY="sk-ant-api03-..."
  343. # Or in Docker
  344. docker run \
  345. -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  346. -e STN_AI_PROVIDER=anthropic \
  347. station:latest
  348. ```
  349. ---
  350. ## How You Interface: MCP-Driven Platform
  351. **Station is driven entirely through MCP tools in your AI assistant.** Natural language requests use 41+ available MCP tools.
  352. ### MCP Tool Categories
  353. | Category | Tools | Key Functions |
  354. |----------|-------|---------------|
  355. | **Agent Management** | 11 | `create_agent`, `update_agent`, `add_agent_as_tool` |
  356. | **Execution** | 4 | `call_agent`, `inspect_run`, `list_runs` |
  357. | **Evaluation** | 7 | `evaluate_benchmark`, `batch_execute_agents` |
  358. | **Reports** | 4 | `create_report`, `generate_report` |
  359. | **Environments** | 3 | `create_environment`, `list_environments` |
  360. | **MCP Servers** | 5 | `add_mcp_server_to_environment` |
  361. | **Scheduling** | 3 | `set_schedule`, `remove_schedule` |
  362. | **Faker/Bundles** | 2 | `faker_create_standalone`, `create_bundle` |
  363. **Example interaction:**
  364. ```
  365. You: "Create a logs analysis agent that uses Datadog and Elasticsearch"
  366. Claude: [Using create_agent tool...] ✅ Created logs_investigator
  367. You: "Run the incident coordinator on the API timeout issue"
  368. Claude: [Using call_agent...] [Full investigation with multi-agent delegation]
  369. ```
  370. **Discover all tools:** Ask your AI assistant "Show me all Station MCP tools" or see [MCP Tools Reference →](https://docs.cloudshipai.com/station/mcp-tools)
  371. ---
  372. ## Real Example: SRE Incident Response Team
  373. We built a complete SRE incident response team with 9 specialized agents that achieved a **7.5/10 performance score** in automated testing.
  374. ### The Team Structure
  375. ```
  376. incident_coordinator (Orchestrator)
  377. ├── logs_investigator - Analyzes error patterns in application logs
  378. ├── metrics_investigator - Identifies performance spikes and anomalies
  379. ├── traces_investigator - Examines distributed trace slowdowns
  380. ├── change_detective - Correlates with recent deployments
  381. ├── infra_sre - Checks K8s, AWS, and infrastructure
  382. ├── saas_dependency_analyst - Monitors external service outages
  383. ├── runbook_recommender - Finds relevant documentation
  384. └── scribe - Generates incident reports
  385. ```
  386. ### In Action: Production Incident Response
  387. **You say:** "The checkout service is returning 503 errors and customers can't complete purchases"
  388. **Incident Coordinator responds:**
  389. ```
  390. I'll coordinate our SRE team to investigate this critical checkout service issue.
  391. INITIAL ASSESSMENT:
  392. - Service: checkout-service
  393. - Error: HTTP 503 (Service Unavailable)
  394. - Impact: Customers unable to complete purchases
  395. - Severity: SEV1 - Revenue impacting
  396. Delegating to specialist agents...
  397. [LOGS INVESTIGATION - @logs_investigator]
  398. ✅ Found error spike starting at 14:32 UTC
  399. - Pattern: "connection pool exhausted"
  400. - Frequency: 847 errors/minute
  401. - Stack trace: database connection timeout
  402. [METRICS ANALYSIS - @metrics_investigator]
  403. ✅ Database connection pool at 100% utilization
  404. - Normal: 40-60 connections
  405. - Current: 200 connections (maxed out)
  406. - Response time: 5000ms (normal: 200ms)
  407. [DEPLOYMENT CHECK - @change_detective]
  408. ✅ Recent deployment detected:
  409. - Service: checkout-service v2.3.0
  410. - Deployed: 14:15 UTC (17 minutes before incident)
  411. - Change: Added batch order processing
  412. ROOT CAUSE IDENTIFIED:
  413. New batch processing feature holding database connections
  414. longer than expected, exhausting the connection pool.
  415. RECOMMENDED ACTIONS:
  416. 1. IMMEDIATE: Increase connection pool to 400 (kubectl patch)
  417. 2. ROLLBACK: Revert to v2.2.0 if pool increase insufficient
  418. 3. LONG-TERM: Implement connection pooling in batch processor
  419. ```
  420. **[Screenshot needed: Web UI showing the incident coordinator agent run with delegations to specialist agents]**
  421. ### How Agents Are Built
  422. Agents are simple `.prompt` files using GenKit's dotprompt format:
  423. **Coordinator Agent** (delegates to other agents):
  424. ```yaml
  425. ---
  426. metadata:
  427. name: "incident_coordinator"
  428. description: "Orchestrates specialist agents to investigate production incidents"
  429. model: gpt-5-mini
  430. max_steps: 20
  431. agents:
  432. - "logs_investigator" # Delegate to logs specialist
  433. - "metrics_investigator" # Delegate to metrics specialist
  434. - "traces_investigator" # Delegate to traces specialist
  435. - "change_detective" # Check recent changes
  436. - "infra_sre" # Infrastructure analysis
  437. - "saas_dependency_analyst" # External dependencies
  438. - "runbook_recommender" # Find solutions
  439. - "scribe" # Generate reports
  440. ---
  441. {{role "system"}}
  442. You are an expert SRE incident coordinator. When presented with a production issue:
  443. 1. Assess severity and business impact
  444. 2. Delegate to relevant specialist agents using __agent_<name> tools
  445. 3. Synthesize findings into root cause
  446. 4. Provide clear remediation steps
  447. {{role "user"}}
  448. {{userInput}}
  449. ```
  450. **Specialist Agent** (uses MCP tools):
  451. ```yaml
  452. ---
  453. metadata:
  454. name: "logs_investigator"
  455. description: "Deep dive into logs to identify error patterns"
  456. model: gpt-5-mini
  457. max_steps: 8
  458. tools:
  459. - "__logs_query" # Query Datadog/Elasticsearch logs
  460. - "__search_query" # Search for patterns
  461. ---
  462. {{role "system"}}
  463. You analyze application logs to find root causes of incidents.
  464. Focus on error patterns, stack traces, and anomalies.
  465. {{role "user"}}
  466. {{userInput}}
  467. ```
  468. ### How You Interface: MCP Tools in Action
  469. Station provides 41 MCP tools directly in your AI assistant. Here's how you use them:
  470. **Creating the team:**
  471. ```
  472. You: Create an incident response team with coordinator and specialist agents
  473. Claude: I'll create the SRE incident response team for you.
  474. [Using tool: create_agent with name="incident_coordinator"...]
  475. ✅ Created incident_coordinator agent
  476. [Using tool: create_agent with name="logs_investigator"...]
  477. ✅ Created logs_investigator agent
  478. [Using tool: add_agent_as_tool with parent="incident_coordinator", child="logs_investigator"...]
  479. ✅ Added logs_investigator as tool for incident_coordinator
  480. [Continues for all 8 specialists...]
  481. Your SRE incident response team is ready! The coordinator can now delegate to all specialists.
  482. ```
  483. **Running investigations:**
  484. ```
  485. You: There's high memory usage on the payment service
  486. Claude: I'll have the incident coordinator investigate this.
  487. [Using tool: call_agent with agent_id="21", task="Investigate high memory usage on payment service"...]
  488. [Response shows full investigation with delegations to specialists]
  489. ```
  490. **[Screenshot needed: Claude/Cursor interface showing MCP tools being used]**
  491. ### The Stack: Real Infrastructure Tools + Simulated Data
  492. Each specialist has access to production-grade tool integrations:
  493. - **Datadog** - Metrics, APM, logs (via faker)
  494. - **AWS CloudWatch** - Infrastructure monitoring (via faker)
  495. - **Kubernetes** - Cluster diagnostics (via faker)
  496. - **GitHub** - Deployment history (via faker)
  497. - **Elasticsearch** - Log aggregation (via faker)
  498. - **Grafana** - Metric dashboards (via faker)
  499. - **StatusPage** - Service status (via faker)
  500. The Faker system generates realistic mock data during development:
  501. ```yaml
  502. datadog:
  503. command: stn
  504. args: ["faker", "--ai-instruction", "Generate production incident data: high CPU, memory leaks, error spikes"]
  505. ```
  506. This lets you build and test without production credentials.
  507. **[Screenshot needed: Faker generating realistic Datadog metrics]**
  508. ### Performance: LLM-as-Judge Evaluation
  509. Station automatically tested this team against 100+ production scenarios:
  510. **Team Performance: 7.5/10**
  511. - ✅ **Multi-agent coordination**: 8.5/10 - Excellent delegation
  512. - ✅ **Tool utilization**: 8.0/10 - Effective use of all tools
  513. - ✅ **Root cause analysis**: 7.5/10 - Identifies issues accurately
  514. - ⚠️ **Resolution speed**: 7.0/10 - Room for improvement
  515. - ⚠️ **Communication clarity**: 6.5/10 - Could be more concise
  516. **[Screenshot needed: Web UI showing team performance report with 7.5/10 score]**
  517. ---
  518. ## Deploy to Production
  519. ### One-Command Cloud Deploy
  520. Deploy your agent team to Fly.io and expose agents as consumable MCP tools:
  521. ```bash
  522. # Deploy the SRE team
  523. stn deploy station-sre --target fly
  524. ✅ Building Docker image with agents
  525. ✅ Deploying to Fly.io (ord region)
  526. ✅ Configuring secrets from variables.yml
  527. ✅ Starting MCP server on port 3030
  528. Your agents are live at:
  529. https://station-sre.fly.dev:3030
  530. ```
  531. **What you get:**
  532. - **MCP Endpoint**: All 9 SRE agents exposed as MCP tools
  533. - **Agent Tools**: Each agent becomes `__agent_<name>` tool
  534. - **Secure Access**: Authentication via deploy token
  535. - **Auto-Scaling**: Fly.io scales based on demand
  536. - **Global CDN**: Deploy to regions worldwide
  537. ### Connect Deployed Agents to Your AI Assistant
  538. Your deployed agents are now accessible as MCP tools from Claude, Cursor, or OpenCode:
  539. **Claude Desktop / Cursor configuration:**
  540. ```json
  541. {
  542. "mcpServers": {
  543. "station-sre-production": {
  544. "url": "https://station-sre.fly.dev:3030/mcp",
  545. "headers": {
  546. "Authorization": "Bearer YOUR_DEPLOY_TOKEN"
  547. }
  548. }
  549. }
  550. }
  551. ```
  552. **Available tools after connection:**
  553. ```
  554. __agent_incident_coordinator - Orchestrates incident response
  555. __agent_logs_investigator - Analyzes error patterns
  556. __agent_metrics_investigator - Identifies performance spikes
  557. __agent_traces_investigator - Examines distributed traces
  558. __agent_change_detective - Correlates with deployments
  559. __agent_infra_sre - Checks K8s/AWS infrastructure
  560. __agent_saas_dependency_analyst - Monitors external services
  561. __agent_runbook_recommender - Finds relevant docs
  562. __agent_scribe - Generates incident reports
  563. ```
  564. **Now you can call your agents from anywhere:**
  565. ```
  566. You: "Investigate the API timeout issue using my SRE team"
  567. Claude: [Calling __agent_incident_coordinator...]
  568. [Full incident investigation with multi-agent delegation]
  569. ```
  570. ---
  571. ### Build for Self-Hosted Infrastructure
  572. Create Docker images to run on your own infrastructure:
  573. **Step 1: Build the image**
  574. ```bash
  575. # Build with your environment embedded
  576. stn build env station-sre --skip-sync
  577. # Output: station-sre:latest Docker image
  578. ```
  579. **Step 2: Run with your environment variables**
  580. ```bash
  581. docker run -d \
  582. -p 3030:3030 \
  583. -e OPENAI_API_KEY=$OPENAI_API_KEY \
  584. -e AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID \
  585. -e AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY \
  586. -e PROJECT_ROOT=/workspace \
  587. -e AWS_REGION=us-east-1 \
  588. station-sre:latest
  589. ```
  590. **Environment Variables at Runtime:**
  591. - **AI Provider Keys**: `OPENAI_API_KEY`, `GEMINI_API_KEY`, etc.
  592. - **Cloud Credentials**: `AWS_*`, `GCP_*`, `AZURE_*` credentials
  593. - **Template Variables**: Any `{{ .VARIABLE }}` from your configs
  594. - **MCP Server Config**: Database URLs, API endpoints, etc.
  595. **Deploy anywhere:**
  596. - **Kubernetes** - Standard deployment with ConfigMaps/Secrets
  597. - **AWS ECS/Fargate** - Task definition with environment variables
  598. - **Google Cloud Run** - One-click deploy with secrets
  599. - **Azure Container Instances** - ARM templates
  600. - **Docker Compose** - Multi-container orchestration
  601. - **Your own servers** - Any Docker-capable host
  602. **Example: Kubernetes Deployment**
  603. ```yaml
  604. apiVersion: apps/v1
  605. kind: Deployment
  606. metadata:
  607. name: station-sre
  608. spec:
  609. replicas: 2
  610. template:
  611. spec:
  612. containers:
  613. - name: station
  614. image: your-registry/station-sre:latest
  615. ports:
  616. - containerPort: 3030
  617. env:
  618. - name: OPENAI_API_KEY
  619. valueFrom:
  620. secretKeyRef:
  621. name: station-secrets
  622. key: openai-api-key
  623. - name: AWS_ACCESS_KEY_ID
  624. valueFrom:
  625. secretKeyRef:
  626. name: aws-credentials
  627. key: access-key-id
  628. - name: AWS_SECRET_ACCESS_KEY
  629. valueFrom:
  630. secretKeyRef:
  631. name: aws-credentials
  632. key: secret-access-key
  633. - name: PROJECT_ROOT
  634. value: "/workspace"
  635. - name: AWS_REGION
  636. value: "us-east-1"
  637. ---
  638. apiVersion: v1
  639. kind: Service
  640. metadata:
  641. name: station-sre
  642. spec:
  643. type: LoadBalancer
  644. ports:
  645. - port: 3030
  646. targetPort: 3030
  647. selector:
  648. app: station-sre
  649. ```
  650. **Connect to your self-hosted MCP endpoint:**
  651. ```json
  652. {
  653. "mcpServers": {
  654. "station-sre-production": {
  655. "url": "https://your-domain.com:3030/mcp",
  656. "headers": {
  657. "Authorization": "Bearer YOUR_TOKEN"
  658. }
  659. }
  660. }
  661. }
  662. ```
  663. ---
  664. ### Advanced Deployment Options
  665. **Custom AI Provider Configuration:**
  666. ```bash
  667. # Build with specific model configuration
  668. stn build env station-sre \
  669. --provider openai \
  670. --model gpt-5-mini
  671. # Or use environment variables at runtime
  672. docker run -e STN_AI_PROVIDER=gemini \
  673. -e GEMINI_API_KEY=$GEMINI_API_KEY \
  674. station-sre:latest
  675. ```
  676. **Multiple Regions:**
  677. ```bash
  678. # Deploy to multiple Fly.io regions
  679. stn deploy station-sre --target fly --region ord # Chicago
  680. stn deploy station-sre --target fly --region syd # Sydney
  681. stn deploy station-sre --target fly --region fra # Frankfurt
  682. ```
  683. **Health Checks:**
  684. ```bash
  685. # Check MCP endpoint health
  686. curl https://station-sre.fly.dev:3030/health
  687. # Response
  688. {
  689. "status": "healthy",
  690. "agents": 9,
  691. "mcp_servers": 3,
  692. "uptime": "2h 15m 30s"
  693. }
  694. ```
  695. ### Bundle and Share
  696. Package your agent team for distribution:
  697. ```bash
  698. # Create a bundle from environment
  699. stn bundle create station-sre
  700. # Creates station-sre.tar.gz
  701. # Share with your team or install elsewhere
  702. stn bundle install station-sre.tar.gz
  703. ```
  704. **[Screenshot needed: Web UI showing bundle in registry]**
  705. ### Schedule Agents for Automation
  706. Run agents on a schedule for continuous monitoring:
  707. ```yaml
  708. # Set up daily cost analysis
  709. "Set a daily schedule for the cost analyzer agent to run at 9 AM"
  710. # Schedule incident checks every 5 minutes
  711. "Schedule the incident coordinator to check system health every 5 minutes"
  712. # Weekly compliance audit
  713. "Set up weekly compliance checks on Mondays at midnight"
  714. ```
  715. Station uses cron expressions with second precision:
  716. - `0 */5 * * * *` - Every 5 minutes
  717. - `0 0 9 * * *` - Daily at 9 AM
  718. - `0 0 0 * * 1` - Weekly on Monday midnight
  719. **View scheduled agents in Web UI:**
  720. **[Screenshot needed: Web UI showing scheduled agents with cron expressions]**
  721. Scheduled agents run automatically and store results in the runs history.
  722. ### Event-Triggered Execution (Webhooks)
  723. Trigger agent execution from external systems via HTTP webhook. Perfect for integrating with CI/CD pipelines, alerting systems, or any automation that can make HTTP requests.
  724. **Endpoint:** `POST http://localhost:8587/execute`
  725. ```bash
  726. # Trigger by agent name
  727. curl -X POST http://localhost:8587/execute \
  728. -H "Content-Type: application/json" \
  729. -d '{"agent_name": "incident_coordinator", "task": "Investigate the API timeout alert"}'
  730. # Trigger by agent ID
  731. curl -X POST http://localhost:8587/execute \
  732. -H "Content-Type: application/json" \
  733. -d '{"agent_id": 21, "task": "Check system health"}'
  734. # With variables for template rendering
  735. curl -X POST http://localhost:8587/execute \
  736. -H "Content-Type: application/json" \
  737. -d '{
  738. "agent_name": "cost_analyzer",
  739. "task": "Analyze costs for project",
  740. "variables": {"project_id": "prod-123", "region": "us-east-1"}
  741. }'
  742. ```
  743. **Response (202 Accepted):**
  744. ```json
  745. {
  746. "run_id": 120,
  747. "agent_id": 21,
  748. "agent_name": "incident_coordinator",
  749. "status": "running",
  750. "message": "Agent execution started"
  751. }
  752. ```
  753. **Integration Examples:**
  754. *PagerDuty Webhook:*
  755. ```bash
  756. # Auto-investigate when PagerDuty alert fires
  757. curl -X POST https://your-station:8587/execute \
  758. -H "Authorization: Bearer $STN_WEBHOOK_API_KEY" \
  759. -d '{"agent_name": "incident_coordinator", "task": "PagerDuty alert: {{alert.title}}"}'
  760. ```
  761. *GitHub Actions:*
  762. ```yaml
  763. - name: Run deployment analyzer
  764. run: |
  765. curl -X POST ${{ secrets.STATION_URL }}/execute \
  766. -H "Authorization: Bearer ${{ secrets.STATION_API_KEY }}" \
  767. -d '{"agent_name": "deployment_analyzer", "task": "Analyze deployment ${{ github.sha }}"}'
  768. ```
  769. **Authentication:**
  770. - **Local mode:** No authentication required
  771. - **Production:** Set `STN_WEBHOOK_API_KEY` environment variable for static API key auth
  772. - **OAuth:** Uses CloudShip OAuth when enabled
  773. **Configuration:**
  774. ```bash
  775. # Enable/disable webhook (default: enabled)
  776. export STN_WEBHOOK_ENABLED=true
  777. # Set static API key for authentication
  778. export STN_WEBHOOK_API_KEY="your-secret-key"
  779. ```
  780. [Webhook API Reference →](https://docs.cloudshipai.com/station/notifications)
  781. ---
  782. ## What Makes Station Special
  783. ### Declarative Agent Definition
  784. Simple `.prompt` files define intelligent behavior:
  785. ```yaml
  786. ---
  787. metadata:
  788. name: "metrics_investigator"
  789. description: "Analyze performance metrics and identify anomalies"
  790. model: gpt-5-mini
  791. max_steps: 8
  792. tools:
  793. - "__get_metrics" # Datadog metrics API
  794. - "__query_time_series" # Grafana queries
  795. - "__get_dashboards" # Dashboard snapshots
  796. - "__list_alerts" # Active alerts
  797. ---
  798. {{role "system"}}
  799. You investigate performance issues by analyzing metrics and time series data.
  800. Focus on: CPU, memory, latency, error rates, and throughput.
  801. {{role "user"}}
  802. {{userInput}}
  803. ```
  804. ### GitOps Workflow
  805. Version control your entire agent infrastructure:
  806. ```bash
  807. my-agents/
  808. ├── config.yaml # Station configuration
  809. ├── environments/
  810. │ ├── production/
  811. │ │ ├── agents/ # Production agents
  812. │ │ ├── template.json # MCP server configs
  813. │ │ └── variables.yml # Secrets and config
  814. │ └── development/
  815. │ ├── agents/ # Dev agents
  816. │ ├── template.json
  817. │ └── variables.yml
  818. └── reports/ # Performance evaluations
  819. ```
  820. ### Built-in Observability
  821. Every execution automatically traced:
  822. **[Screenshot needed: Jaeger showing multi-agent trace]**
  823. ```
  824. incident_coordinator (18.2s)
  825. ├─ assess_severity (0.5s)
  826. ├─ delegate_logs_investigator (4.1s)
  827. │ └─ __get_logs (3.2s)
  828. ├─ delegate_metrics_investigator (3.8s)
  829. │ └─ __query_time_series (2.9s)
  830. ├─ delegate_change_detective (2.4s)
  831. │ └─ __get_recent_deployments (1.8s)
  832. └─ synthesize_findings (1.2s)
  833. ```
  834. ### Template Variables for Security
  835. Never hardcode credentials:
  836. ```json
  837. {
  838. "mcpServers": {
  839. "aws": {
  840. "command": "aws-mcp",
  841. "env": {
  842. "AWS_REGION": "{{ .AWS_REGION }}",
  843. "AWS_PROFILE": "{{ .AWS_PROFILE }}"
  844. }
  845. }
  846. }
  847. }
  848. ```
  849. Variables resolved from `variables.yml` or environment.
  850. ### Production-Grade Integrations
  851. Connect to your actual infrastructure tools:
  852. - **Cloud**: AWS, GCP, Azure via official SDKs
  853. - **Monitoring**: Datadog, New Relic, Grafana
  854. - **Incidents**: PagerDuty, Opsgenie, VictorOps
  855. - **Kubernetes**: Direct cluster access
  856. - **Databases**: PostgreSQL, MySQL, MongoDB
  857. - **CI/CD**: Jenkins, GitHub Actions, GitLab
  858. ### Sandbox: Isolated Code Execution
  859. Agents can execute Python, Node.js, or Bash code in isolated Docker containers:
  860. **Compute Mode** - Ephemeral per-call (default):
  861. ```yaml
  862. ---
  863. metadata:
  864. name: "data-processor"
  865. sandbox: python # or: node, bash
  866. ---
  867. Use the sandbox_run tool to process data with Python.
  868. ```
  869. **Code Mode** - Persistent session across workflow steps:
  870. ```yaml
  871. ---
  872. metadata:
  873. name: "code-developer"
  874. sandbox:
  875. mode: code
  876. session: workflow # Share container across agents in workflow
  877. ---
  878. Use sandbox_open, sandbox_exec, sandbox_fs_write to develop iteratively.
  879. ```
  880. **Why Sandbox?**
  881. | Without Sandbox | With Sandbox |
  882. |-----------------|--------------|
  883. | LLM calculates (often wrong) | Python computes correctly |
  884. | Large JSON in context (slow) | Python parses efficiently |
  885. | Host execution (security risk) | Isolated container (safe) |
  886. **Enabling Sandbox:**
  887. ```bash
  888. # Compute mode (ephemeral per-call)
  889. export STATION_SANDBOX_ENABLED=true
  890. # Code mode (persistent sessions - requires Docker)
  891. export STATION_SANDBOX_ENABLED=true
  892. export STATION_SANDBOX_CODE_MODE_ENABLED=true
  893. ```
  894. [Sandbox Documentation →](https://docs.cloudshipai.com/station/sandbox)
  895. ---
  896. ## Try It Yourself
  897. Ready to build your own agent team? Here's how:
  898. ### 1. Create Your Team
  899. Ask your AI assistant:
  900. ```
  901. "Create an incident response team like the SRE example with coordinator and specialist agents"
  902. ```
  903. Station will:
  904. - Create the multi-agent hierarchy
  905. - Assign appropriate tools to each specialist
  906. - Set up the coordinator to delegate tasks
  907. - Configure realistic mock data for testing
  908. ### 2. Test with Real Scenarios
  909. ```
  910. "The API gateway is timing out and affecting all services"
  911. ```
  912. Watch as your coordinator:
  913. - Assesses the situation
  914. - Delegates to relevant specialists
  915. - Gathers data from multiple sources
  916. - Provides root cause analysis
  917. - Recommends specific fixes
  918. ### 3. Evaluate Performance
  919. ```
  920. "Generate a benchmark report for my incident response team"
  921. ```
  922. Get detailed metrics on:
  923. - Multi-agent coordination effectiveness
  924. - Tool utilization patterns
  925. - Response accuracy
  926. - Communication clarity
  927. - Areas for improvement
  928. ### 4. Deploy When Ready
  929. ```bash
  930. stn deploy my-team --target fly
  931. ```
  932. Your agents are now available as a production MCP endpoint.
  933. ---
  934. ## OpenAPI MCP Servers (Experimental)
  935. Station can automatically convert OpenAPI/Swagger specifications into MCP servers, making any REST API instantly available as agent tools.
  936. > ⚠️ **Experimental Feature** - OpenAPI to MCP conversion is currently in beta.
  937. **Turn any OpenAPI spec into MCP tools:**
  938. ```json
  939. {
  940. "name": "Station Management API",
  941. "description": "Control Station via REST API",
  942. "mcpServers": {
  943. "station-api": {
  944. "command": "stn",
  945. "args": [
  946. "openapi-runtime",
  947. "--spec",
  948. "environments/{{ .ENVIRONMENT_NAME }}/station-api.openapi.json"
  949. ]
  950. }
  951. },
  952. "metadata": {
  953. "openapiSpec": "station-api.openapi.json",
  954. "variables": {
  955. "STATION_API_URL": {
  956. "description": "Station API endpoint URL",
  957. "default": "http://localhost:8585/api/v1"
  958. }
  959. }
  960. }
  961. }
  962. ```
  963. **Template variables in OpenAPI specs:**
  964. ```json
  965. {
  966. "openapi": "3.0.0",
  967. "servers": [
  968. {
  969. "url": "{{ .STATION_API_URL }}",
  970. "description": "Station API endpoint"
  971. }
  972. ]
  973. }
  974. ```
  975. Station automatically:
  976. - ✅ **Converts OpenAPI paths to MCP tools** - Each endpoint becomes a callable tool
  977. - ✅ **Processes template variables** - Resolves `{{ .VAR }}` from `variables.yml` and env vars
  978. - ✅ **Supports authentication** - Bearer tokens, API keys, OAuth
  979. - ✅ **Smart tool sync** - Detects OpenAPI spec updates and refreshes tools
  980. **Example: Station Admin Agent**
  981. Create an agent that manages Station itself using the Station API:
  982. ```yaml
  983. ---
  984. metadata:
  985. name: "Station Admin"
  986. description: "Manages Station environments, agents, and MCP servers"
  987. model: gpt-5-mini
  988. max_steps: 10
  989. tools:
  990. - "__listEnvironments" # From station-api OpenAPI spec
  991. - "__listAgents"
  992. - "__listMCPServers"
  993. - "__createAgent"
  994. - "__executeAgent"
  995. ---
  996. {{role "system"}}
  997. You are a Station administrator that helps manage environments, agents, and MCP servers.
  998. Use the Station API tools to:
  999. - List and inspect environments, agents, and MCP servers
  1000. - Create new agents from user requirements
  1001. - Execute agents and monitor their runs
  1002. - Provide comprehensive overviews of the Station deployment
  1003. {{role "user"}}
  1004. {{userInput}}
  1005. ```
  1006. **Usage:**
  1007. ```bash
  1008. stn agent run station-admin "Show me all environments and their agents"
  1009. ```
  1010. The agent will use the OpenAPI-generated tools to query the Station API and provide a comprehensive overview.
  1011. [OpenAPI MCP Documentation →](https://docs.cloudshipai.com/station/openapi-mcp)
  1012. ---
  1013. ## Zero-Config Deployments
  1014. Deploy Station agents to production without manual configuration. Station supports zero-config deployments that automatically:
  1015. - Discover cloud credentials and configuration
  1016. - Set up MCP tool connections
  1017. - Deploy agents with production-ready settings
  1018. **Deploy to Docker Compose:**
  1019. ```bash
  1020. # Build environment container
  1021. stn build env production
  1022. # Deploy with docker-compose
  1023. docker-compose up -d
  1024. ```
  1025. Station automatically configures:
  1026. - AWS credentials from instance role or environment
  1027. - Database connections from service discovery
  1028. - MCP servers with template variables resolved
  1029. **Supported platforms:**
  1030. - Docker / Docker Compose
  1031. - AWS ECS
  1032. - Kubernetes
  1033. - AWS Lambda (coming soon)
  1034. [Deployment Guide →](https://docs.cloudshipai.com/station/docker)
  1035. ---
  1036. ## Observability & Distributed Tracing
  1037. Station includes built-in OpenTelemetry (OTEL) support for complete execution observability:
  1038. **What Gets Traced:**
  1039. - **Agent Executions**: Complete timeline from start to finish
  1040. - **LLM Calls**: Every OpenAI/Anthropic/Gemini API call with latency
  1041. - **MCP Tool Usage**: Individual tool calls to AWS, Stripe, GitHub, etc.
  1042. - **Database Operations**: Query performance and data access patterns
  1043. - **GenKit Native Spans**: Dotprompt execution, generation flow, model interactions
  1044. **Quick Start with Jaeger:**
  1045. ```bash
  1046. # Start Jaeger locally
  1047. make jaeger
  1048. # Configure Station
  1049. export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
  1050. stn serve
  1051. # Run agent and view traces
  1052. stn agent run my-agent "Analyze costs"
  1053. open http://localhost:16686
  1054. ```
  1055. **Team Integration Examples:**
  1056. - **Jaeger** - Open source tracing (local development)
  1057. - **Grafana Tempo** - Scalable distributed tracing
  1058. - **Datadog APM** - Full-stack observability platform
  1059. - **Honeycomb** - Advanced trace analysis with BubbleUp
  1060. - **New Relic** - Application performance monitoring
  1061. - **AWS X-Ray** - AWS-native distributed tracing
  1062. **Span Details Captured:**
  1063. ```
  1064. aws-cost-spike-analyzer (18.2s)
  1065. ├─ generate (17ms)
  1066. │ ├─ openai/gpt-5-mini (11ms) - "Analyze cost data"
  1067. │ └─ __get_cost_anomalies (0ms) - AWS Cost Explorer
  1068. ├─ generate (11ms)
  1069. │ └─ __get_cost_and_usage_comparisons (0ms)
  1070. └─ db.agent_runs.create (0.1ms)
  1071. ```
  1072. **Configuration:**
  1073. ```bash
  1074. # Environment variable (recommended)
  1075. export OTEL_EXPORTER_OTLP_ENDPOINT=http://your-collector:4318
  1076. # Or config file
  1077. otel_endpoint: "http://your-collector:4318"
  1078. ```
  1079. [Complete OTEL Setup Guide →](https://docs.cloudshipai.com/station/observability) - Includes Jaeger, Tempo, Datadog, Honeycomb, AWS X-Ray, New Relic, Azure Monitor examples
  1080. ---
  1081. ## Use Cases
  1082. **FinOps & Cost Optimization:**
  1083. - Cost spike detection and root cause analysis
  1084. - Reserved instance utilization tracking
  1085. - Multi-cloud cost attribution
  1086. - COGS analysis for SaaS businesses
  1087. **Security & Compliance:**
  1088. - Infrastructure security scanning
  1089. - Compliance violation detection
  1090. - Secret rotation monitoring
  1091. - Vulnerability assessments
  1092. **Deployment & Operations:**
  1093. - Automated deployment validation
  1094. - Performance regression detection
  1095. - Incident response automation
  1096. - Change impact analysis
  1097. [See Example Agents →](https://docs.cloudshipai.com/station/multi-agent-teams)
  1098. ---
  1099. ## CloudShip Integration
  1100. Connect your Station to [CloudShip](https://cloudshipai.com) for centralized management, OAuth authentication, and team collaboration.
  1101. ### Why CloudShip?
  1102. - **Centralized Management** - Manage multiple Stations from a single dashboard
  1103. - **OAuth Authentication** - Secure MCP access with CloudShip user accounts
  1104. - **Team Collaboration** - Share agents with your organization members
  1105. - **Audit Trail** - Track all Station connections and executions
  1106. ### Who Can Access Your Station?
  1107. With CloudShip OAuth enabled, only users who:
  1108. 1. Have a **CloudShip account**
  1109. 2. Are **members of your organization**
  1110. 3. Successfully **authenticate via OAuth**
  1111. ...can access your Station's agents through MCP. This lets you share powerful agents with your team while keeping them secure.
  1112. ### Quick Setup
  1113. 1. **Get a Registration Key** from your CloudShip dashboard at `Settings > Stations`
  1114. 2. **Configure your Station** (`config.yaml`):
  1115. ```yaml
  1116. cloudship:
  1117. enabled: true
  1118. registration_key: "your-registration-key"
  1119. name: "my-station" # Unique name for this station
  1120. tags: ["production", "us-east-1"]
  1121. ```
  1122. 3. **Start Station** - It will automatically connect to CloudShip:
  1123. ```bash
  1124. stn serve
  1125. # Output: Successfully registered with CloudShip management channel
  1126. ```
  1127. ### OAuth Authentication for MCP
  1128. When CloudShip OAuth is enabled, MCP clients (Claude Desktop, Cursor, etc.) authenticate through CloudShip before accessing your Station's agents.
  1129. **Setup (Station Admin):**
  1130. 1. Create an OAuth App in CloudShip (Settings > OAuth Apps)
  1131. 2. Configure Station with `oauth.enabled: true` and `oauth.client_id`
  1132. 3. Invite team members to your CloudShip organization
  1133. **Usage (Team Members):**
  1134. 1. Point MCP client to your Station's Dynamic Agent MCP URL (port 8587)
  1135. 2. Browser opens for CloudShip login
  1136. 3. Approve access → Done! Now you can use the agents.
  1137. **How it works:**
  1138. ```
  1139. MCP Client Station CloudShip
  1140. | | |
  1141. |------ POST /mcp --------->| |
  1142. |<----- 401 Unauthorized ---| |
  1143. | WWW-Authenticate: | |
  1144. | Bearer resource_metadata="..." |
  1145. | | |
  1146. |------- [OAuth Discovery] ------------------------------>|
  1147. |<------ [Authorization Server Metadata] -----------------|
  1148. | | |
  1149. |------- [Browser Login] -------------------------------->|
  1150. |<------ [Authorization Code] ----------------------------|
  1151. | | |
  1152. |------- [Token Exchange] ------------------------------->|
  1153. |<------ [Access Token] ----------------------------------|
  1154. | | |
  1155. |------ POST /mcp --------->| |
  1156. | Authorization: Bearer |------ Validate Token ------>|
  1157. | |<------ {active: true} ------|
  1158. |<----- MCP Response -------| |
  1159. ```
  1160. **Enable OAuth** (`config.yaml`):
  1161. ```yaml
  1162. cloudship:
  1163. enabled: true
  1164. registration_key: "your-key"
  1165. name: "my-station"
  1166. oauth:
  1167. enabled: true
  1168. client_id: "your-oauth-client-id" # From CloudShip OAuth Apps
  1169. ```
  1170. **MCP Client Configuration** (Claude Desktop / Cursor):
  1171. ```json
  1172. {
  1173. "mcpServers": {
  1174. "my-station": {
  1175. "url": "https://my-station.example.com:8587/mcp"
  1176. }
  1177. }
  1178. }
  1179. ```
  1180. > **Note:** Port 8587 is the Dynamic Agent MCP server. Port 8586 is the standard MCP server.
  1181. When the MCP client connects, it will:
  1182. 1. Receive a 401 with OAuth discovery URL
  1183. 2. Open CloudShip login in your browser
  1184. 3. After authentication, automatically retry with the access token
  1185. ### Configuration Reference
  1186. ```yaml
  1187. cloudship:
  1188. # Enable CloudShip integration
  1189. enabled: true
  1190. # Registration key from CloudShip dashboard
  1191. registration_key: "sk-..."
  1192. # Unique station name (required for multi-station support)
  1193. name: "production-us-east"
  1194. # Tags for filtering and organization
  1195. tags: ["production", "us-east-1", "sre-team"]
  1196. # CloudShip endpoints (defaults shown - usually no need to change)
  1197. endpoint: "lighthouse.cloudshipai.com:443" # TLS-secured gRPC endpoint
  1198. use_tls: true # TLS enabled by default
  1199. base_url: "https://app.cloudshipai.com"
  1200. # OAuth settings for MCP authentication
  1201. oauth:
  1202. enabled: false # Enable OAuth for MCP
  1203. client_id: "" # OAuth client ID from CloudShip
  1204. # These are auto-configured from base_url:
  1205. # auth_url: "https://app.cloudshipai.com/oauth/authorize/"
  1206. # token_url: "https://app.cloudshipai.com/oauth/token/"
  1207. # introspect_url: "https://app.cloudshipai.com/oauth/introspect/"
  1208. ```
  1209. ### Development Setup
  1210. For local development with a local Lighthouse instance:
  1211. ```yaml
  1212. cloudship:
  1213. enabled: true
  1214. registration_key: "your-dev-key"
  1215. name: "dev-station"
  1216. endpoint: "localhost:50051" # Local Lighthouse (no TLS)
  1217. use_tls: false # Disable TLS for local development
  1218. base_url: "http://localhost:8000" # Local Django
  1219. oauth:
  1220. enabled: true
  1221. client_id: "your-dev-client-id"
  1222. introspect_url: "http://localhost:8000/oauth/introspect/"
  1223. ```
  1224. For connecting to **production CloudShip** during development (recommended):
  1225. ```yaml
  1226. cloudship:
  1227. enabled: true
  1228. registration_key: "your-registration-key"
  1229. name: "dev-station"
  1230. # Uses defaults: endpoint=lighthouse.cloudshipai.com:443, use_tls=true
  1231. ```
  1232. ### Security Notes
  1233. - **Registration keys** should be kept secret - they authorize Station connections
  1234. - **OAuth tokens** are validated on every MCP request via CloudShip introspection
  1235. - **PKCE** is required for all OAuth flows (S256 code challenge)
  1236. - Station caches validated tokens for 5 minutes to reduce introspection calls
  1237. ---
  1238. ## Database Persistence & Replication
  1239. Station uses SQLite by default, with support for cloud databases and continuous backup for production deployments.
  1240. ### Local Development (Default)
  1241. ```bash
  1242. # Station uses local SQLite file
  1243. stn stdio
  1244. ```
  1245. Perfect for local development, zero configuration required.
  1246. ### Cloud Database (libsql)
  1247. For multi-instance deployments or team collaboration, use a libsql-compatible cloud database:
  1248. ```bash
  1249. # Connect to cloud database
  1250. export DATABASE_URL="libsql://your-db.example.com?authToken=your-token"
  1251. stn stdio
  1252. ```
  1253. **Benefits:**
  1254. - State persists across multiple deployments
  1255. - Team collaboration with shared database
  1256. - Multi-region replication
  1257. - Automatic backups
  1258. ### Continuous Backup (Litestream)
  1259. For single-instance production deployments with disaster recovery:
  1260. ```bash
  1261. # Docker deployment with automatic S3 backup
  1262. docker run \
  1263. -e LITESTREAM_S3_BUCKET=my-backups \
  1264. -e LITESTREAM_S3_ACCESS_KEY_ID=xxx \
  1265. -e LITESTREAM_S3_SECRET_ACCESS_KEY=yyy \
  1266. ghcr.io/cloudshipai/station:production
  1267. ```
  1268. **Benefits:**
  1269. - Continuous replication to S3/GCS/Azure
  1270. - Automatic restore on startup
  1271. - Point-in-time recovery
  1272. - Zero data loss on server failures
  1273. [Database Replication Guide →](https://docs.cloudshipai.com/station/database)
  1274. ---
  1275. ## GitOps Workflow
  1276. Version control your agent configurations, MCP templates, and variables in Git:
  1277. ```bash
  1278. # Create a Git repository for your Station config
  1279. mkdir my-station-config
  1280. cd my-station-config
  1281. # Initialize Station in this directory
  1282. export STATION_WORKSPACE=$(pwd)
  1283. stn init
  1284. # Your agents are now in ./environments/default/agents/
  1285. # Commit to Git and share with your team!
  1286. git init
  1287. git add .
  1288. git commit -m "Initial Station configuration"
  1289. ```
  1290. **Team Workflow:**
  1291. ```bash
  1292. # Clone team repository
  1293. git clone git@github.com:your-team/station-config.git
  1294. cd station-config
  1295. # Run Station with this workspace
  1296. export STATION_WORKSPACE=$(pwd)
  1297. stn stdio
  1298. ```
  1299. All agent `.prompt` files, MCP `template.json` configs, and `variables.yml` are version-controlled and reviewable in Pull Requests.
  1300. [GitOps Workflow Guide →](https://docs.cloudshipai.com/station/gitops)
  1301. ---
  1302. ## System Requirements
  1303. - **OS:** Linux, macOS, Windows
  1304. - **Memory:** 512MB minimum, 1GB recommended
  1305. - **Storage:** 200MB for binary, 1GB+ for agent data
  1306. - **Network:** Outbound HTTPS for AI providers
  1307. ---
  1308. ## Mission
  1309. **Make it easy for engineering teams to build and deploy infrastructure agents on their own terms.**
  1310. Station puts you in control:
  1311. - **Self-hosted** - Your data stays on your infrastructure
  1312. - **Git-backed** - Version control everything like code
  1313. - **Production-ready** - Deploy confidently with built-in evaluation
  1314. - **Team-owned** - No vendor lock-in, no data sharing
  1315. We believe teams should own their agentic automation, from development to production.
  1316. ---
  1317. ## Resources
  1318. - 📚 **[Documentation](https://docs.cloudshipai.com)** - Complete guides and tutorials
  1319. - 🐛 **[Issues](https://github.com/cloudshipai/station/issues)** - Bug reports and feature requests
  1320. - 💬 **[Discord](https://discord.gg/station-ai)** - Community support
  1321. ---
  1322. ## For Contributors
  1323. If you're interested in contributing to Station or understanding the internals, comprehensive architecture documentation is available in the [`docs/architecture/`](./docs/architecture/) directory:
  1324. - **[Architecture Index](./docs/architecture/ARCHITECTURE_INDEX.md)** - Quick navigation and key concepts reference
  1325. - **[Architecture Diagrams](./docs/architecture/ARCHITECTURE_DIAGRAMS.md)** - Complete ASCII diagrams of all major systems and services
  1326. - **[Architecture Analysis](./docs/architecture/ARCHITECTURE_ANALYSIS.md)** - Deep dive into design decisions and component organization
  1327. - **[Component Interactions](./docs/architecture/COMPONENT_INTERACTIONS.md)** - Detailed sequence diagrams for key workflows
  1328. These documents provide a complete understanding of Station's four-layer architecture, 43+ service modules, database schema, API endpoints, and execution flows.
  1329. ---
  1330. ## License
  1331. **Apache 2.0** - Free for all use, open source contributions welcome.
  1332. ---
  1333. **Station - AI Agent Orchestration Platform**
  1334. *Build, test, and deploy intelligent agent teams. Self-hosted. Git-backed. Production-ready.*

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.