Content
# Station - AI Agent Orchestration Platform
[](./TESTING_PROGRESS.md) [](./.github/workflows/ci.yml)
**Build, test, and deploy intelligent agent teams. Self-hosted. Git-backed. Production-ready.**
[Quick Start](#quick-start) | [Real Example](#real-example-sre-incident-response-team) | [Deploy](#deploy-to-production) | [Documentation](https://docs.cloudshipai.com)
---
## Why Station?
Build multi-agent systems that coordinate like real teams. Test with realistic scenarios. Deploy on your infrastructure.
**Station gives you:**
- ✅ **Multi-Agent Teams** - Coordinate specialist agents under orchestrators
- ✅ **Built-in Evaluation** - LLM-as-judge tests every agent automatically
- ✅ **Git-Backed Workflow** - Version control agents like code
- ✅ **One-Command Deploy** - Push to production with `stn deploy`
- ✅ **Full Observability** - Jaeger traces for every execution
- ✅ **Self-Hosted** - Your data, your infrastructure, your control
---
## Quick Start (2 minutes)
### 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
```bash
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.
```bash
# 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.~~
```bash
# ❌ NOT WORKING - Anthropic OAuth disabled
# stn init --provider anthropic --ship
# stn auth anthropic login
```
</details>
<details>
<summary><b>OpenAI (API Key)</b></summary>
```bash
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>
```bash
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:
```bash
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>
```bash
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`:
```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):
```json
{
"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` |
```json
{
"mcpServers": {
"station": {
"command": "stn",
"args": ["stdio"],
"env": {
"OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4318"
}
}
}
}
```
</details>
**Optional GitOps:** Point to a Git-backed workspace:
```json
"command": ["stn", "--config", "/path/to/my-agents/config.yaml", "stdio"]
```
### 5. Install Editor Plugins (Optional)
Get skills, slash commands, and enhanced documentation for your AI editor:
<details>
<summary><b>Claude Code Plugin</b></summary>
Adds `/station` commands, skills for agent creation, and MCP server config.
```bash
# Add Station marketplace and install plugin
/plugin marketplace add cloudshipai/station
/plugin install station@cloudshipai-station
```
Or install from local clone:
```bash
/plugin install ./station/claude-code-plugin
```
</details>
<details>
<summary><b>OpenCode Skill</b></summary>
Adds Station CLI reference skill with agent, workflow, and deployment docs.
```bash
# Copy skill to your project
cp -r station/opencode-plugin/.opencode .
# Or install globally
cp -r station/opencode-plugin/.opencode ~/.config/opencode/
```
Restart OpenCode - skill auto-loads.
</details>
### 6. Start Building
Restart your editor. Station provides:
- ✅ **Web UI** at `http://localhost:8585` for configuration
- ✅ **Jaeger UI** at `http://localhost:16686` for traces
- ✅ **41 MCP tools** available in your AI assistant
**Try your first command:**
```
"Show me all Station MCP tools available"
```
<details>
<summary><b>Interactive Onboarding Guide (3-5 min tutorial)</b></summary>
Copy this prompt into your AI assistant for a hands-on tour:
```
You are my Station onboarding guide. Walk me through an interactive hands-on tutorial.
RULES:
1. Create a todo list to track progress through each section
2. At each section, STOP and let me engage before continuing
3. Use Station MCP tools to demonstrate - don't just explain, DO IT
4. Keep it fun and celebrate wins!
THE JOURNEY:
## 1. Hello World Agent
- Create a "hello-world" agent that greets users and tells a joke
- Call the agent and show the result
[STOP for me to try it]
## 2. Faker Tools & MCP Templates
- Explain Faker tools (AI-generated mock data for safe development)
- Note: Real MCP tools are added via Station UI or template.json
- Explain MCP templates - they keep credentials safe when deploying
- Create a "prometheus-metrics" faker for realistic metrics
[STOP to see the faker]
## 3. DevOps Investigation Agent
- Create a "metrics-investigator" agent using our prometheus faker
- Call it: "Check for performance issues in the last hour"
[STOP to review the investigation]
## 4. Multi-Agent Hierarchy
- Create an "incident-coordinator" that delegates to:
- metrics-investigator (existing)
- logs-investigator (new - create a logs faker)
- Show hierarchy structure in the .prompt file
- Call coordinator: "Investigate why the API is slow"
[STOP to see delegation]
## 5. Inspecting Runs
- Use inspect_run to show detailed execution
- Explain: tool calls, delegations, timing
[STOP to explore]
## 6. Workflow with Human-in-the-Loop
- Create a workflow: investigate → switch on severity → human_approval if high → report
- Make it complex (switch/parallel), not sequential
- Start the workflow
[STOP for me to approve/reject]
## 7. Evaluation & Reporting
- Run evals with evaluate_benchmark
- Generate a performance report
[STOP to review]
## 8. Grand Finale
- Direct me to http://localhost:8585 (Station UI)
- Quick tour: Agents, MCP servers, Runs, Workflows
- Celebrate!
## 9. Want More? (Optional)
Briefly explain these advanced features (no demo needed):
- **Schedules**: Cron-based agent scheduling
- **Sandboxes**: Isolated code execution (Python/Node/Bash)
- **Notify Webhooks**: Send alerts to Slack, ntfy, Discord
- **Bundles**: Package and share agent teams
- **Deploy**: `stn deploy` to Fly.io, Docker, K8s
- **CloudShip**: Centralized management and team OAuth
Start now with Section 1!
```
</details>
---
## Running Station with `stn up`
The easiest way to run Station is with `stn up` - a single command that starts Station in a Docker container with everything configured.
### Primary Use Case: Running Bundles
`stn up` is designed to make it trivial to run agent bundles from your CloudShip account or the community:
```bash
# Run a bundle from CloudShip (by ID or name)
stn up --bundle finops-cost-analyzer
# Run a bundle from URL
stn up --bundle https://example.com/my-bundle.tar.gz
# Run a local bundle file
stn up --bundle ./my-custom-agents.tar.gz
```
This is the recommended way for most users to get started - just pick a bundle and go.
### Secondary Use Case: Testing Local Configurations
Developers can also use `stn up` to test their local agent configurations in an isolated container environment:
```bash
# Test your local workspace in a container
stn up --workspace ~/my-agents
# Test with a specific environment
stn up --environment production
# Test with development tools enabled
stn up --develop
```
This lets you validate that your agents work correctly in the same containerized environment they'll run in production.
### Quick Commands
```bash
# Start Station (interactive setup on first run)
stn up
# Start with specific AI provider
stn up --provider openai --model gpt-5
# Check status
stn status
# View logs
stn logs -f
# Stop Station
stn down
# Stop and remove all data (fresh start)
stn down --remove-volume
```
### What `stn up` Provides
| Service | Port | Description |
|---------|------|-------------|
| Web UI | 8585 | Configuration interface |
| MCP Server | 8586 | Main MCP endpoint for tools |
| Agent MCP | 8587 | Dynamic agent execution |
| Jaeger UI | 16686 | Distributed tracing |
**[See Container Lifecycle](https://docs.cloudshipai.com/station/container-lifecycle) for detailed architecture.**
---
## AI Provider Authentication
Station supports multiple authentication methods for AI providers.
### API Keys (Default)
The simplest way to authenticate - set your API key as an environment variable:
```bash
# CloudShip AI (Recommended - auto-detected when registration key is set)
export CLOUDSHIPAI_REGISTRATION_KEY="csk-..."
# Or: export STN_CLOUDSHIP_KEY="csk-..."
# OpenAI
export OPENAI_API_KEY="sk-..."
# Google Gemini
export GEMINI_API_KEY="..."
# Anthropic (API billing)
export ANTHROPIC_API_KEY="sk-ant-api03-..."
```
### Anthropic OAuth (Claude Max/Pro Subscription) - ⚠️ DEPRECATED
> **⚠️ DEPRECATED: Anthropic OAuth is currently unavailable.**
>
> Anthropic has restricted third-party use of OAuth tokens. This authentication method is **not working until further notice**.
>
> **Use these alternatives instead:**
> - `OPENAI_API_KEY` for OpenAI models (recommended)
> - `GEMINI_API_KEY` for Google Gemini models
> - `ANTHROPIC_API_KEY` for Anthropic API (pay-per-token billing)
<details>
<summary>Previous OAuth documentation (for reference only)</summary>
~~Use your Claude Max or Claude Pro subscription instead of pay-per-token API billing.~~
**Setup (NOT WORKING):**
```bash
# ❌ DEPRECATED - Anthropic OAuth disabled
# stn auth anthropic login
```
**Authentication Priority:**
| Priority | Method | Description |
|----------|--------|-------------|
| 1 | `STN_AI_AUTH_TYPE=api_key` | Force API key mode (override) |
| ~~2~~ | ~~Station OAuth tokens~~ | ~~From `stn auth anthropic login`~~ **DEPRECATED** |
| ~~3~~ | ~~Claude Code credentials~~ | ~~From `~/.claude/.credentials.json`~~ **DEPRECATED** |
| 4 | `ANTHROPIC_API_KEY` env var | Standard API key (**USE THIS**) |
</details>
**For Anthropic models, use API key authentication:**
```bash
# Set Anthropic API key
export ANTHROPIC_API_KEY="sk-ant-api03-..."
# Or in Docker
docker run \
-e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
-e STN_AI_PROVIDER=anthropic \
station:latest
```
---
## How You Interface: MCP-Driven Platform
**Station is driven entirely through MCP tools in your AI assistant.** Natural language requests use 41+ available MCP tools.
### MCP Tool Categories
| Category | Tools | Key Functions |
|----------|-------|---------------|
| **Agent Management** | 11 | `create_agent`, `update_agent`, `add_agent_as_tool` |
| **Execution** | 4 | `call_agent`, `inspect_run`, `list_runs` |
| **Evaluation** | 7 | `evaluate_benchmark`, `batch_execute_agents` |
| **Reports** | 4 | `create_report`, `generate_report` |
| **Environments** | 3 | `create_environment`, `list_environments` |
| **MCP Servers** | 5 | `add_mcp_server_to_environment` |
| **Scheduling** | 3 | `set_schedule`, `remove_schedule` |
| **Faker/Bundles** | 2 | `faker_create_standalone`, `create_bundle` |
**Example interaction:**
```
You: "Create a logs analysis agent that uses Datadog and Elasticsearch"
Claude: [Using create_agent tool...] ✅ Created logs_investigator
You: "Run the incident coordinator on the API timeout issue"
Claude: [Using call_agent...] [Full investigation with multi-agent delegation]
```
**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)
---
## Real Example: SRE Incident Response Team
We built a complete SRE incident response team with 9 specialized agents that achieved a **7.5/10 performance score** in automated testing.
### The Team Structure
```
incident_coordinator (Orchestrator)
├── logs_investigator - Analyzes error patterns in application logs
├── metrics_investigator - Identifies performance spikes and anomalies
├── traces_investigator - Examines distributed trace slowdowns
├── change_detective - Correlates with recent deployments
├── infra_sre - Checks K8s, AWS, and infrastructure
├── saas_dependency_analyst - Monitors external service outages
├── runbook_recommender - Finds relevant documentation
└── scribe - Generates incident reports
```
### In Action: Production Incident Response
**You say:** "The checkout service is returning 503 errors and customers can't complete purchases"
**Incident Coordinator responds:**
```
I'll coordinate our SRE team to investigate this critical checkout service issue.
INITIAL ASSESSMENT:
- Service: checkout-service
- Error: HTTP 503 (Service Unavailable)
- Impact: Customers unable to complete purchases
- Severity: SEV1 - Revenue impacting
Delegating to specialist agents...
[LOGS INVESTIGATION - @logs_investigator]
✅ Found error spike starting at 14:32 UTC
- Pattern: "connection pool exhausted"
- Frequency: 847 errors/minute
- Stack trace: database connection timeout
[METRICS ANALYSIS - @metrics_investigator]
✅ Database connection pool at 100% utilization
- Normal: 40-60 connections
- Current: 200 connections (maxed out)
- Response time: 5000ms (normal: 200ms)
[DEPLOYMENT CHECK - @change_detective]
✅ Recent deployment detected:
- Service: checkout-service v2.3.0
- Deployed: 14:15 UTC (17 minutes before incident)
- Change: Added batch order processing
ROOT CAUSE IDENTIFIED:
New batch processing feature holding database connections
longer than expected, exhausting the connection pool.
RECOMMENDED ACTIONS:
1. IMMEDIATE: Increase connection pool to 400 (kubectl patch)
2. ROLLBACK: Revert to v2.2.0 if pool increase insufficient
3. LONG-TERM: Implement connection pooling in batch processor
```
**[Screenshot needed: Web UI showing the incident coordinator agent run with delegations to specialist agents]**
### How Agents Are Built
Agents are simple `.prompt` files using GenKit's dotprompt format:
**Coordinator Agent** (delegates to other agents):
```yaml
---
metadata:
name: "incident_coordinator"
description: "Orchestrates specialist agents to investigate production incidents"
model: gpt-5-mini
max_steps: 20
agents:
- "logs_investigator" # Delegate to logs specialist
- "metrics_investigator" # Delegate to metrics specialist
- "traces_investigator" # Delegate to traces specialist
- "change_detective" # Check recent changes
- "infra_sre" # Infrastructure analysis
- "saas_dependency_analyst" # External dependencies
- "runbook_recommender" # Find solutions
- "scribe" # Generate reports
---
{{role "system"}}
You are an expert SRE incident coordinator. When presented with a production issue:
1. Assess severity and business impact
2. Delegate to relevant specialist agents using __agent_<name> tools
3. Synthesize findings into root cause
4. Provide clear remediation steps
{{role "user"}}
{{userInput}}
```
**Specialist Agent** (uses MCP tools):
```yaml
---
metadata:
name: "logs_investigator"
description: "Deep dive into logs to identify error patterns"
model: gpt-5-mini
max_steps: 8
tools:
- "__logs_query" # Query Datadog/Elasticsearch logs
- "__search_query" # Search for patterns
---
{{role "system"}}
You analyze application logs to find root causes of incidents.
Focus on error patterns, stack traces, and anomalies.
{{role "user"}}
{{userInput}}
```
### How You Interface: MCP Tools in Action
Station provides 41 MCP tools directly in your AI assistant. Here's how you use them:
**Creating the team:**
```
You: Create an incident response team with coordinator and specialist agents
Claude: I'll create the SRE incident response team for you.
[Using tool: create_agent with name="incident_coordinator"...]
✅ Created incident_coordinator agent
[Using tool: create_agent with name="logs_investigator"...]
✅ Created logs_investigator agent
[Using tool: add_agent_as_tool with parent="incident_coordinator", child="logs_investigator"...]
✅ Added logs_investigator as tool for incident_coordinator
[Continues for all 8 specialists...]
Your SRE incident response team is ready! The coordinator can now delegate to all specialists.
```
**Running investigations:**
```
You: There's high memory usage on the payment service
Claude: I'll have the incident coordinator investigate this.
[Using tool: call_agent with agent_id="21", task="Investigate high memory usage on payment service"...]
[Response shows full investigation with delegations to specialists]
```
**[Screenshot needed: Claude/Cursor interface showing MCP tools being used]**
### The Stack: Real Infrastructure Tools + Simulated Data
Each specialist has access to production-grade tool integrations:
- **Datadog** - Metrics, APM, logs (via faker)
- **AWS CloudWatch** - Infrastructure monitoring (via faker)
- **Kubernetes** - Cluster diagnostics (via faker)
- **GitHub** - Deployment history (via faker)
- **Elasticsearch** - Log aggregation (via faker)
- **Grafana** - Metric dashboards (via faker)
- **StatusPage** - Service status (via faker)
The Faker system generates realistic mock data during development:
```yaml
datadog:
command: stn
args: ["faker", "--ai-instruction", "Generate production incident data: high CPU, memory leaks, error spikes"]
```
This lets you build and test without production credentials.
**[Screenshot needed: Faker generating realistic Datadog metrics]**
### Performance: LLM-as-Judge Evaluation
Station automatically tested this team against 100+ production scenarios:
**Team Performance: 7.5/10**
- ✅ **Multi-agent coordination**: 8.5/10 - Excellent delegation
- ✅ **Tool utilization**: 8.0/10 - Effective use of all tools
- ✅ **Root cause analysis**: 7.5/10 - Identifies issues accurately
- ⚠️ **Resolution speed**: 7.0/10 - Room for improvement
- ⚠️ **Communication clarity**: 6.5/10 - Could be more concise
**[Screenshot needed: Web UI showing team performance report with 7.5/10 score]**
---
## Deploy to Production
### One-Command Cloud Deploy
Deploy your agent team to Fly.io and expose agents as consumable MCP tools:
```bash
# Deploy the SRE team
stn deploy station-sre --target fly
✅ Building Docker image with agents
✅ Deploying to Fly.io (ord region)
✅ Configuring secrets from variables.yml
✅ Starting MCP server on port 3030
Your agents are live at:
https://station-sre.fly.dev:3030
```
**What you get:**
- **MCP Endpoint**: All 9 SRE agents exposed as MCP tools
- **Agent Tools**: Each agent becomes `__agent_<name>` tool
- **Secure Access**: Authentication via deploy token
- **Auto-Scaling**: Fly.io scales based on demand
- **Global CDN**: Deploy to regions worldwide
### Connect Deployed Agents to Your AI Assistant
Your deployed agents are now accessible as MCP tools from Claude, Cursor, or OpenCode:
**Claude Desktop / Cursor configuration:**
```json
{
"mcpServers": {
"station-sre-production": {
"url": "https://station-sre.fly.dev:3030/mcp",
"headers": {
"Authorization": "Bearer YOUR_DEPLOY_TOKEN"
}
}
}
}
```
**Available tools after connection:**
```
__agent_incident_coordinator - Orchestrates incident response
__agent_logs_investigator - Analyzes error patterns
__agent_metrics_investigator - Identifies performance spikes
__agent_traces_investigator - Examines distributed traces
__agent_change_detective - Correlates with deployments
__agent_infra_sre - Checks K8s/AWS infrastructure
__agent_saas_dependency_analyst - Monitors external services
__agent_runbook_recommender - Finds relevant docs
__agent_scribe - Generates incident reports
```
**Now you can call your agents from anywhere:**
```
You: "Investigate the API timeout issue using my SRE team"
Claude: [Calling __agent_incident_coordinator...]
[Full incident investigation with multi-agent delegation]
```
---
### Build for Self-Hosted Infrastructure
Create Docker images to run on your own infrastructure:
**Step 1: Build the image**
```bash
# Build with your environment embedded
stn build env station-sre --skip-sync
# Output: station-sre:latest Docker image
```
**Step 2: Run with your environment variables**
```bash
docker run -d \
-p 3030:3030 \
-e OPENAI_API_KEY=$OPENAI_API_KEY \
-e AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID \
-e AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY \
-e PROJECT_ROOT=/workspace \
-e AWS_REGION=us-east-1 \
station-sre:latest
```
**Environment Variables at Runtime:**
- **AI Provider Keys**: `OPENAI_API_KEY`, `GEMINI_API_KEY`, etc.
- **Cloud Credentials**: `AWS_*`, `GCP_*`, `AZURE_*` credentials
- **Template Variables**: Any `{{ .VARIABLE }}` from your configs
- **MCP Server Config**: Database URLs, API endpoints, etc.
**Deploy anywhere:**
- **Kubernetes** - Standard deployment with ConfigMaps/Secrets
- **AWS ECS/Fargate** - Task definition with environment variables
- **Google Cloud Run** - One-click deploy with secrets
- **Azure Container Instances** - ARM templates
- **Docker Compose** - Multi-container orchestration
- **Your own servers** - Any Docker-capable host
**Example: Kubernetes Deployment**
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: station-sre
spec:
replicas: 2
template:
spec:
containers:
- name: station
image: your-registry/station-sre:latest
ports:
- containerPort: 3030
env:
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: station-secrets
key: openai-api-key
- name: AWS_ACCESS_KEY_ID
valueFrom:
secretKeyRef:
name: aws-credentials
key: access-key-id
- name: AWS_SECRET_ACCESS_KEY
valueFrom:
secretKeyRef:
name: aws-credentials
key: secret-access-key
- name: PROJECT_ROOT
value: "/workspace"
- name: AWS_REGION
value: "us-east-1"
---
apiVersion: v1
kind: Service
metadata:
name: station-sre
spec:
type: LoadBalancer
ports:
- port: 3030
targetPort: 3030
selector:
app: station-sre
```
**Connect to your self-hosted MCP endpoint:**
```json
{
"mcpServers": {
"station-sre-production": {
"url": "https://your-domain.com:3030/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
}
}
}
}
```
---
### Advanced Deployment Options
**Custom AI Provider Configuration:**
```bash
# Build with specific model configuration
stn build env station-sre \
--provider openai \
--model gpt-5-mini
# Or use environment variables at runtime
docker run -e STN_AI_PROVIDER=gemini \
-e GEMINI_API_KEY=$GEMINI_API_KEY \
station-sre:latest
```
**Multiple Regions:**
```bash
# Deploy to multiple Fly.io regions
stn deploy station-sre --target fly --region ord # Chicago
stn deploy station-sre --target fly --region syd # Sydney
stn deploy station-sre --target fly --region fra # Frankfurt
```
**Health Checks:**
```bash
# Check MCP endpoint health
curl https://station-sre.fly.dev:3030/health
# Response
{
"status": "healthy",
"agents": 9,
"mcp_servers": 3,
"uptime": "2h 15m 30s"
}
```
### Bundle and Share
Package your agent team for distribution:
```bash
# Create a bundle from environment
stn bundle create station-sre
# Creates station-sre.tar.gz
# Share with your team or install elsewhere
stn bundle install station-sre.tar.gz
```
**[Screenshot needed: Web UI showing bundle in registry]**
### Schedule Agents for Automation
Run agents on a schedule for continuous monitoring:
```yaml
# Set up daily cost analysis
"Set a daily schedule for the cost analyzer agent to run at 9 AM"
# Schedule incident checks every 5 minutes
"Schedule the incident coordinator to check system health every 5 minutes"
# Weekly compliance audit
"Set up weekly compliance checks on Mondays at midnight"
```
Station uses cron expressions with second precision:
- `0 */5 * * * *` - Every 5 minutes
- `0 0 9 * * *` - Daily at 9 AM
- `0 0 0 * * 1` - Weekly on Monday midnight
**View scheduled agents in Web UI:**
**[Screenshot needed: Web UI showing scheduled agents with cron expressions]**
Scheduled agents run automatically and store results in the runs history.
### Event-Triggered Execution (Webhooks)
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.
**Endpoint:** `POST http://localhost:8587/execute`
```bash
# Trigger by agent name
curl -X POST http://localhost:8587/execute \
-H "Content-Type: application/json" \
-d '{"agent_name": "incident_coordinator", "task": "Investigate the API timeout alert"}'
# Trigger by agent ID
curl -X POST http://localhost:8587/execute \
-H "Content-Type: application/json" \
-d '{"agent_id": 21, "task": "Check system health"}'
# With variables for template rendering
curl -X POST http://localhost:8587/execute \
-H "Content-Type: application/json" \
-d '{
"agent_name": "cost_analyzer",
"task": "Analyze costs for project",
"variables": {"project_id": "prod-123", "region": "us-east-1"}
}'
```
**Response (202 Accepted):**
```json
{
"run_id": 120,
"agent_id": 21,
"agent_name": "incident_coordinator",
"status": "running",
"message": "Agent execution started"
}
```
**Integration Examples:**
*PagerDuty Webhook:*
```bash
# Auto-investigate when PagerDuty alert fires
curl -X POST https://your-station:8587/execute \
-H "Authorization: Bearer $STN_WEBHOOK_API_KEY" \
-d '{"agent_name": "incident_coordinator", "task": "PagerDuty alert: {{alert.title}}"}'
```
*GitHub Actions:*
```yaml
- name: Run deployment analyzer
run: |
curl -X POST ${{ secrets.STATION_URL }}/execute \
-H "Authorization: Bearer ${{ secrets.STATION_API_KEY }}" \
-d '{"agent_name": "deployment_analyzer", "task": "Analyze deployment ${{ github.sha }}"}'
```
**Authentication:**
- **Local mode:** No authentication required
- **Production:** Set `STN_WEBHOOK_API_KEY` environment variable for static API key auth
- **OAuth:** Uses CloudShip OAuth when enabled
**Configuration:**
```bash
# Enable/disable webhook (default: enabled)
export STN_WEBHOOK_ENABLED=true
# Set static API key for authentication
export STN_WEBHOOK_API_KEY="your-secret-key"
```
[Webhook API Reference →](https://docs.cloudshipai.com/station/notifications)
---
## What Makes Station Special
### Declarative Agent Definition
Simple `.prompt` files define intelligent behavior:
```yaml
---
metadata:
name: "metrics_investigator"
description: "Analyze performance metrics and identify anomalies"
model: gpt-5-mini
max_steps: 8
tools:
- "__get_metrics" # Datadog metrics API
- "__query_time_series" # Grafana queries
- "__get_dashboards" # Dashboard snapshots
- "__list_alerts" # Active alerts
---
{{role "system"}}
You investigate performance issues by analyzing metrics and time series data.
Focus on: CPU, memory, latency, error rates, and throughput.
{{role "user"}}
{{userInput}}
```
### GitOps Workflow
Version control your entire agent infrastructure:
```bash
my-agents/
├── config.yaml # Station configuration
├── environments/
│ ├── production/
│ │ ├── agents/ # Production agents
│ │ ├── template.json # MCP server configs
│ │ └── variables.yml # Secrets and config
│ └── development/
│ ├── agents/ # Dev agents
│ ├── template.json
│ └── variables.yml
└── reports/ # Performance evaluations
```
### Built-in Observability
Every execution automatically traced:
**[Screenshot needed: Jaeger showing multi-agent trace]**
```
incident_coordinator (18.2s)
├─ assess_severity (0.5s)
├─ delegate_logs_investigator (4.1s)
│ └─ __get_logs (3.2s)
├─ delegate_metrics_investigator (3.8s)
│ └─ __query_time_series (2.9s)
├─ delegate_change_detective (2.4s)
│ └─ __get_recent_deployments (1.8s)
└─ synthesize_findings (1.2s)
```
### Template Variables for Security
Never hardcode credentials:
```json
{
"mcpServers": {
"aws": {
"command": "aws-mcp",
"env": {
"AWS_REGION": "{{ .AWS_REGION }}",
"AWS_PROFILE": "{{ .AWS_PROFILE }}"
}
}
}
}
```
Variables resolved from `variables.yml` or environment.
### Production-Grade Integrations
Connect to your actual infrastructure tools:
- **Cloud**: AWS, GCP, Azure via official SDKs
- **Monitoring**: Datadog, New Relic, Grafana
- **Incidents**: PagerDuty, Opsgenie, VictorOps
- **Kubernetes**: Direct cluster access
- **Databases**: PostgreSQL, MySQL, MongoDB
- **CI/CD**: Jenkins, GitHub Actions, GitLab
### Sandbox: Isolated Code Execution
Agents can execute Python, Node.js, or Bash code in isolated Docker containers:
**Compute Mode** - Ephemeral per-call (default):
```yaml
---
metadata:
name: "data-processor"
sandbox: python # or: node, bash
---
Use the sandbox_run tool to process data with Python.
```
**Code Mode** - Persistent session across workflow steps:
```yaml
---
metadata:
name: "code-developer"
sandbox:
mode: code
session: workflow # Share container across agents in workflow
---
Use sandbox_open, sandbox_exec, sandbox_fs_write to develop iteratively.
```
**Why Sandbox?**
| Without Sandbox | With Sandbox |
|-----------------|--------------|
| LLM calculates (often wrong) | Python computes correctly |
| Large JSON in context (slow) | Python parses efficiently |
| Host execution (security risk) | Isolated container (safe) |
**Enabling Sandbox:**
```bash
# Compute mode (ephemeral per-call)
export STATION_SANDBOX_ENABLED=true
# Code mode (persistent sessions - requires Docker)
export STATION_SANDBOX_ENABLED=true
export STATION_SANDBOX_CODE_MODE_ENABLED=true
```
[Sandbox Documentation →](https://docs.cloudshipai.com/station/sandbox)
---
## Try It Yourself
Ready to build your own agent team? Here's how:
### 1. Create Your Team
Ask your AI assistant:
```
"Create an incident response team like the SRE example with coordinator and specialist agents"
```
Station will:
- Create the multi-agent hierarchy
- Assign appropriate tools to each specialist
- Set up the coordinator to delegate tasks
- Configure realistic mock data for testing
### 2. Test with Real Scenarios
```
"The API gateway is timing out and affecting all services"
```
Watch as your coordinator:
- Assesses the situation
- Delegates to relevant specialists
- Gathers data from multiple sources
- Provides root cause analysis
- Recommends specific fixes
### 3. Evaluate Performance
```
"Generate a benchmark report for my incident response team"
```
Get detailed metrics on:
- Multi-agent coordination effectiveness
- Tool utilization patterns
- Response accuracy
- Communication clarity
- Areas for improvement
### 4. Deploy When Ready
```bash
stn deploy my-team --target fly
```
Your agents are now available as a production MCP endpoint.
---
## OpenAPI MCP Servers (Experimental)
Station can automatically convert OpenAPI/Swagger specifications into MCP servers, making any REST API instantly available as agent tools.
> ⚠️ **Experimental Feature** - OpenAPI to MCP conversion is currently in beta.
**Turn any OpenAPI spec into MCP tools:**
```json
{
"name": "Station Management API",
"description": "Control Station via REST API",
"mcpServers": {
"station-api": {
"command": "stn",
"args": [
"openapi-runtime",
"--spec",
"environments/{{ .ENVIRONMENT_NAME }}/station-api.openapi.json"
]
}
},
"metadata": {
"openapiSpec": "station-api.openapi.json",
"variables": {
"STATION_API_URL": {
"description": "Station API endpoint URL",
"default": "http://localhost:8585/api/v1"
}
}
}
}
```
**Template variables in OpenAPI specs:**
```json
{
"openapi": "3.0.0",
"servers": [
{
"url": "{{ .STATION_API_URL }}",
"description": "Station API endpoint"
}
]
}
```
Station automatically:
- ✅ **Converts OpenAPI paths to MCP tools** - Each endpoint becomes a callable tool
- ✅ **Processes template variables** - Resolves `{{ .VAR }}` from `variables.yml` and env vars
- ✅ **Supports authentication** - Bearer tokens, API keys, OAuth
- ✅ **Smart tool sync** - Detects OpenAPI spec updates and refreshes tools
**Example: Station Admin Agent**
Create an agent that manages Station itself using the Station API:
```yaml
---
metadata:
name: "Station Admin"
description: "Manages Station environments, agents, and MCP servers"
model: gpt-5-mini
max_steps: 10
tools:
- "__listEnvironments" # From station-api OpenAPI spec
- "__listAgents"
- "__listMCPServers"
- "__createAgent"
- "__executeAgent"
---
{{role "system"}}
You are a Station administrator that helps manage environments, agents, and MCP servers.
Use the Station API tools to:
- List and inspect environments, agents, and MCP servers
- Create new agents from user requirements
- Execute agents and monitor their runs
- Provide comprehensive overviews of the Station deployment
{{role "user"}}
{{userInput}}
```
**Usage:**
```bash
stn agent run station-admin "Show me all environments and their agents"
```
The agent will use the OpenAPI-generated tools to query the Station API and provide a comprehensive overview.
[OpenAPI MCP Documentation →](https://docs.cloudshipai.com/station/openapi-mcp)
---
## Zero-Config Deployments
Deploy Station agents to production without manual configuration. Station supports zero-config deployments that automatically:
- Discover cloud credentials and configuration
- Set up MCP tool connections
- Deploy agents with production-ready settings
**Deploy to Docker Compose:**
```bash
# Build environment container
stn build env production
# Deploy with docker-compose
docker-compose up -d
```
Station automatically configures:
- AWS credentials from instance role or environment
- Database connections from service discovery
- MCP servers with template variables resolved
**Supported platforms:**
- Docker / Docker Compose
- AWS ECS
- Kubernetes
- AWS Lambda (coming soon)
[Deployment Guide →](https://docs.cloudshipai.com/station/docker)
---
## Observability & Distributed Tracing
Station includes built-in OpenTelemetry (OTEL) support for complete execution observability:
**What Gets Traced:**
- **Agent Executions**: Complete timeline from start to finish
- **LLM Calls**: Every OpenAI/Anthropic/Gemini API call with latency
- **MCP Tool Usage**: Individual tool calls to AWS, Stripe, GitHub, etc.
- **Database Operations**: Query performance and data access patterns
- **GenKit Native Spans**: Dotprompt execution, generation flow, model interactions
**Quick Start with Jaeger:**
```bash
# Start Jaeger locally
make jaeger
# Configure Station
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
stn serve
# Run agent and view traces
stn agent run my-agent "Analyze costs"
open http://localhost:16686
```
**Team Integration Examples:**
- **Jaeger** - Open source tracing (local development)
- **Grafana Tempo** - Scalable distributed tracing
- **Datadog APM** - Full-stack observability platform
- **Honeycomb** - Advanced trace analysis with BubbleUp
- **New Relic** - Application performance monitoring
- **AWS X-Ray** - AWS-native distributed tracing
**Span Details Captured:**
```
aws-cost-spike-analyzer (18.2s)
├─ generate (17ms)
│ ├─ openai/gpt-5-mini (11ms) - "Analyze cost data"
│ └─ __get_cost_anomalies (0ms) - AWS Cost Explorer
├─ generate (11ms)
│ └─ __get_cost_and_usage_comparisons (0ms)
└─ db.agent_runs.create (0.1ms)
```
**Configuration:**
```bash
# Environment variable (recommended)
export OTEL_EXPORTER_OTLP_ENDPOINT=http://your-collector:4318
# Or config file
otel_endpoint: "http://your-collector:4318"
```
[Complete OTEL Setup Guide →](https://docs.cloudshipai.com/station/observability) - Includes Jaeger, Tempo, Datadog, Honeycomb, AWS X-Ray, New Relic, Azure Monitor examples
---
## Use Cases
**FinOps & Cost Optimization:**
- Cost spike detection and root cause analysis
- Reserved instance utilization tracking
- Multi-cloud cost attribution
- COGS analysis for SaaS businesses
**Security & Compliance:**
- Infrastructure security scanning
- Compliance violation detection
- Secret rotation monitoring
- Vulnerability assessments
**Deployment & Operations:**
- Automated deployment validation
- Performance regression detection
- Incident response automation
- Change impact analysis
[See Example Agents →](https://docs.cloudshipai.com/station/multi-agent-teams)
---
## CloudShip Integration
Connect your Station to [CloudShip](https://cloudshipai.com) for centralized management, OAuth authentication, and team collaboration.
### Why CloudShip?
- **Centralized Management** - Manage multiple Stations from a single dashboard
- **OAuth Authentication** - Secure MCP access with CloudShip user accounts
- **Team Collaboration** - Share agents with your organization members
- **Audit Trail** - Track all Station connections and executions
### Who Can Access Your Station?
With CloudShip OAuth enabled, only users who:
1. Have a **CloudShip account**
2. Are **members of your organization**
3. Successfully **authenticate via OAuth**
...can access your Station's agents through MCP. This lets you share powerful agents with your team while keeping them secure.
### Quick Setup
1. **Get a Registration Key** from your CloudShip dashboard at `Settings > Stations`
2. **Configure your Station** (`config.yaml`):
```yaml
cloudship:
enabled: true
registration_key: "your-registration-key"
name: "my-station" # Unique name for this station
tags: ["production", "us-east-1"]
```
3. **Start Station** - It will automatically connect to CloudShip:
```bash
stn serve
# Output: Successfully registered with CloudShip management channel
```
### OAuth Authentication for MCP
When CloudShip OAuth is enabled, MCP clients (Claude Desktop, Cursor, etc.) authenticate through CloudShip before accessing your Station's agents.
**Setup (Station Admin):**
1. Create an OAuth App in CloudShip (Settings > OAuth Apps)
2. Configure Station with `oauth.enabled: true` and `oauth.client_id`
3. Invite team members to your CloudShip organization
**Usage (Team Members):**
1. Point MCP client to your Station's Dynamic Agent MCP URL (port 8587)
2. Browser opens for CloudShip login
3. Approve access → Done! Now you can use the agents.
**How it works:**
```
MCP Client Station CloudShip
| | |
|------ POST /mcp --------->| |
|<----- 401 Unauthorized ---| |
| WWW-Authenticate: | |
| Bearer resource_metadata="..." |
| | |
|------- [OAuth Discovery] ------------------------------>|
|<------ [Authorization Server Metadata] -----------------|
| | |
|------- [Browser Login] -------------------------------->|
|<------ [Authorization Code] ----------------------------|
| | |
|------- [Token Exchange] ------------------------------->|
|<------ [Access Token] ----------------------------------|
| | |
|------ POST /mcp --------->| |
| Authorization: Bearer |------ Validate Token ------>|
| |<------ {active: true} ------|
|<----- MCP Response -------| |
```
**Enable OAuth** (`config.yaml`):
```yaml
cloudship:
enabled: true
registration_key: "your-key"
name: "my-station"
oauth:
enabled: true
client_id: "your-oauth-client-id" # From CloudShip OAuth Apps
```
**MCP Client Configuration** (Claude Desktop / Cursor):
```json
{
"mcpServers": {
"my-station": {
"url": "https://my-station.example.com:8587/mcp"
}
}
}
```
> **Note:** Port 8587 is the Dynamic Agent MCP server. Port 8586 is the standard MCP server.
When the MCP client connects, it will:
1. Receive a 401 with OAuth discovery URL
2. Open CloudShip login in your browser
3. After authentication, automatically retry with the access token
### Configuration Reference
```yaml
cloudship:
# Enable CloudShip integration
enabled: true
# Registration key from CloudShip dashboard
registration_key: "sk-..."
# Unique station name (required for multi-station support)
name: "production-us-east"
# Tags for filtering and organization
tags: ["production", "us-east-1", "sre-team"]
# CloudShip endpoints (defaults shown - usually no need to change)
endpoint: "lighthouse.cloudshipai.com:443" # TLS-secured gRPC endpoint
use_tls: true # TLS enabled by default
base_url: "https://app.cloudshipai.com"
# OAuth settings for MCP authentication
oauth:
enabled: false # Enable OAuth for MCP
client_id: "" # OAuth client ID from CloudShip
# These are auto-configured from base_url:
# auth_url: "https://app.cloudshipai.com/oauth/authorize/"
# token_url: "https://app.cloudshipai.com/oauth/token/"
# introspect_url: "https://app.cloudshipai.com/oauth/introspect/"
```
### Development Setup
For local development with a local Lighthouse instance:
```yaml
cloudship:
enabled: true
registration_key: "your-dev-key"
name: "dev-station"
endpoint: "localhost:50051" # Local Lighthouse (no TLS)
use_tls: false # Disable TLS for local development
base_url: "http://localhost:8000" # Local Django
oauth:
enabled: true
client_id: "your-dev-client-id"
introspect_url: "http://localhost:8000/oauth/introspect/"
```
For connecting to **production CloudShip** during development (recommended):
```yaml
cloudship:
enabled: true
registration_key: "your-registration-key"
name: "dev-station"
# Uses defaults: endpoint=lighthouse.cloudshipai.com:443, use_tls=true
```
### Security Notes
- **Registration keys** should be kept secret - they authorize Station connections
- **OAuth tokens** are validated on every MCP request via CloudShip introspection
- **PKCE** is required for all OAuth flows (S256 code challenge)
- Station caches validated tokens for 5 minutes to reduce introspection calls
---
## Database Persistence & Replication
Station uses SQLite by default, with support for cloud databases and continuous backup for production deployments.
### Local Development (Default)
```bash
# Station uses local SQLite file
stn stdio
```
Perfect for local development, zero configuration required.
### Cloud Database (libsql)
For multi-instance deployments or team collaboration, use a libsql-compatible cloud database:
```bash
# Connect to cloud database
export DATABASE_URL="libsql://your-db.example.com?authToken=your-token"
stn stdio
```
**Benefits:**
- State persists across multiple deployments
- Team collaboration with shared database
- Multi-region replication
- Automatic backups
### Continuous Backup (Litestream)
For single-instance production deployments with disaster recovery:
```bash
# Docker deployment with automatic S3 backup
docker run \
-e LITESTREAM_S3_BUCKET=my-backups \
-e LITESTREAM_S3_ACCESS_KEY_ID=xxx \
-e LITESTREAM_S3_SECRET_ACCESS_KEY=yyy \
ghcr.io/cloudshipai/station:production
```
**Benefits:**
- Continuous replication to S3/GCS/Azure
- Automatic restore on startup
- Point-in-time recovery
- Zero data loss on server failures
[Database Replication Guide →](https://docs.cloudshipai.com/station/database)
---
## GitOps Workflow
Version control your agent configurations, MCP templates, and variables in Git:
```bash
# Create a Git repository for your Station config
mkdir my-station-config
cd my-station-config
# Initialize Station in this directory
export STATION_WORKSPACE=$(pwd)
stn init
# Your agents are now in ./environments/default/agents/
# Commit to Git and share with your team!
git init
git add .
git commit -m "Initial Station configuration"
```
**Team Workflow:**
```bash
# Clone team repository
git clone git@github.com:your-team/station-config.git
cd station-config
# Run Station with this workspace
export STATION_WORKSPACE=$(pwd)
stn stdio
```
All agent `.prompt` files, MCP `template.json` configs, and `variables.yml` are version-controlled and reviewable in Pull Requests.
[GitOps Workflow Guide →](https://docs.cloudshipai.com/station/gitops)
---
## System Requirements
- **OS:** Linux, macOS, Windows
- **Memory:** 512MB minimum, 1GB recommended
- **Storage:** 200MB for binary, 1GB+ for agent data
- **Network:** Outbound HTTPS for AI providers
---
## Mission
**Make it easy for engineering teams to build and deploy infrastructure agents on their own terms.**
Station puts you in control:
- **Self-hosted** - Your data stays on your infrastructure
- **Git-backed** - Version control everything like code
- **Production-ready** - Deploy confidently with built-in evaluation
- **Team-owned** - No vendor lock-in, no data sharing
We believe teams should own their agentic automation, from development to production.
---
## Resources
- 📚 **[Documentation](https://docs.cloudshipai.com)** - Complete guides and tutorials
- 🐛 **[Issues](https://github.com/cloudshipai/station/issues)** - Bug reports and feature requests
- 💬 **[Discord](https://discord.gg/station-ai)** - Community support
---
## For Contributors
If you're interested in contributing to Station or understanding the internals, comprehensive architecture documentation is available in the [`docs/architecture/`](./docs/architecture/) directory:
- **[Architecture Index](./docs/architecture/ARCHITECTURE_INDEX.md)** - Quick navigation and key concepts reference
- **[Architecture Diagrams](./docs/architecture/ARCHITECTURE_DIAGRAMS.md)** - Complete ASCII diagrams of all major systems and services
- **[Architecture Analysis](./docs/architecture/ARCHITECTURE_ANALYSIS.md)** - Deep dive into design decisions and component organization
- **[Component Interactions](./docs/architecture/COMPONENT_INTERACTIONS.md)** - Detailed sequence diagrams for key workflows
These documents provide a complete understanding of Station's four-layer architecture, 43+ service modules, database schema, API endpoints, and execution flows.
---
## License
**Apache 2.0** - Free for all use, open source contributions welcome.
---
**Station - AI Agent Orchestration Platform**
*Build, test, and deploy intelligent agent teams. Self-hosted. Git-backed. Production-ready.*
Connection Info
You Might Also Like
No recommendations available