station

Station - AI Agent Orchestration Platform

Build, test, and deploy intelligent agent teams. Self-hosted. Git-backed. Production-ready.

Quick Start | Real Example | Deploy | Documentation

---

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

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

2. Initialize Station

Choose your AI provider:

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

⚠️ 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

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

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

This sets up:

• ✅ Your chosen AI provider
• ✅ Ship CLI 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 for viewing agent execution traces.

4. Connect Your MCP Client

Choose your editor and add Station:

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

Verify with claude mcp list.

Add to opencode.jsonc:

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

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"
      }
    }
  }
}

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"
      }
    }
  }
}

Optional GitOps: Point to a Git-backed workspace:

"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:

Adds /station commands, skills for agent creation, and MCP server config.

# Add Station marketplace and install plugin
/plugin marketplace add cloudshipai/station
/plugin install station@cloudshipai-station

Or install from local clone:

/plugin install ./station/claude-code-plugin

Adds Station CLI reference skill with agent, workflow, and deployment docs.

# 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.

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"

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!

---

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:

# 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:

# 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

# 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 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:

# 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)

Use your Claude Max or Claude Pro subscription instead of pay-per-token API billing.

Setup (NOT WORKING):

# ❌ 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)

For Anthropic models, use API key authentication:

# 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 →

---

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):

---
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):

---
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:

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:

# 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:

{
  "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

# 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

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

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:

{
  "mcpServers": {
    "station-sre-production": {
      "url": "https://your-domain.com:3030/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

---

Advanced Deployment Options

Custom AI Provider Configuration:

# 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:

# 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:

# 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:

# 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:

# 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

# 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):

{
  "run_id": 120,
  "agent_id": 21,
  "agent_name": "incident_coordinator",
  "status": "running",
  "message": "Agent execution started"
}

Integration Examples:

PagerDuty Webhook:

# 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:

- 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:

# 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 →

---

What Makes Station Special

Declarative Agent Definition

Simple .prompt files define intelligent behavior:

---
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:

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:

{
  "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):

---
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:

---
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:

# 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 →

---

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

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:

{
  "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:

{
  "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:

---
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:

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 →

---

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:

# 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 →

---

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:

# 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:

# 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 → - 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 →

---

CloudShip Integration

Connect your Station to CloudShip 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):

   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:

   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):

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):

{
  "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

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:

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):

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)

# 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:

# 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:

# 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 →

---

GitOps Workflow

Version control your agent configurations, MCP templates, and variables in Git:

# 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:

# Clone team repository
git clone [email protected]: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 →

---

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 - Complete guides and tutorials
• 🐛 Issues - Bug reports and feature requests
• 💬 Discord - 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/ directory:

• Architecture Index - Quick navigation and key concepts reference
• Architecture Diagrams - Complete ASCII diagrams of all major systems and services
• Architecture Analysis - Deep dive into design decisions and component organization
• Component Interactions - 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.