> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudshipai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bundles

> Package and distribute agent configurations

## What are Bundles?

Bundles are portable packages containing complete Station environment configurations:

* MCP server definitions
* Agent prompts
* Variable schemas
* Documentation

Bundles enable:

* **Sharing** configurations between teams
* **Deploying** pre-configured agents instantly
* **Version control** for agent configurations

## Bundle Structure

```
my-bundle.tar.gz/
├── manifest.json          # Bundle metadata
├── template.json          # MCP server configurations
├── variables.schema.json  # Variable validation schema
├── README.md              # Documentation
├── examples/
│   └── development.vars.yml
└── agents/
    ├── analyst.prompt
    └── reviewer.prompt
```

## Creating Bundles

### Via MCP Tool

```
"Create a bundle from the production environment"
```

Station uses the `create_bundle_from_environment` tool to package your environment.

### Via CLI

```bash theme={null}
# Create bundle from default environment
stn bundle create default --output my-bundle.tar.gz

# Create from specific environment
stn bundle create production --output prod-bundle.tar.gz
```

### Bundle Contents

The created bundle includes:

* All MCP servers from `template.json`
* All agents from `agents/*.prompt`
* Variable schema from `variables.schema.json`
* Environment documentation

## Installing Bundles

### From CloudShip

```bash theme={null}
# Install by bundle UUID
stn bundle install e26b414a-f076-4135-927f-810bc1dc892a my-environment
```

### From URL

```bash theme={null}
# Install from GitHub release
stn bundle install https://github.com/org/repo/releases/download/v1.0/bundle.tar.gz my-env
```

### From Local File

```bash theme={null}
# Install from local file
stn bundle install ./my-bundle.tar.gz my-environment
```

### With `stn up`

Install bundle when starting Docker container:

```bash theme={null}
stn up --bundle e26b414a-f076-4135-927f-810bc1dc892a
```

## Sharing Bundles

### Upload to CloudShip

```bash theme={null}
# Share environment as bundle
stn bundle share production

# Share existing bundle file
stn bundle share ./my-bundle.tar.gz
```

After sharing, you'll receive a bundle UUID for distribution.

### Self-Hosted Distribution

Host bundles on any HTTP server:

```bash theme={null}
# Upload to your server
scp my-bundle.tar.gz user@server:/var/www/bundles/

# Install from URL
stn bundle install https://server/bundles/my-bundle.tar.gz my-env
```

## Bundle Manifest

The `manifest.json` describes the bundle:

```json theme={null}
{
  "name": "security-scanner",
  "version": "1.0.0",
  "description": "Security scanning agents with vulnerability detection",
  "author": "CloudShip AI",
  "created": "2024-01-15T10:00:00Z",
  "station_version": ">=0.1.0",
  "variables": [
    {
      "name": "GITHUB_TOKEN",
      "description": "GitHub API token for repository access",
      "required": true
    }
  ]
}
```

## Variable Handling

### Defining Variables

In `variables.schema.json`:

```json theme={null}
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "GITHUB_TOKEN": {
      "type": "string",
      "description": "GitHub API token"
    },
    "SLACK_WEBHOOK": {
      "type": "string",
      "description": "Slack webhook URL"
    }
  },
  "required": ["GITHUB_TOKEN"]
}
```

### Providing Variables

When installing, Station prompts for required variables:

```bash theme={null}
stn bundle install ./bundle.tar.gz my-env
# Enter value for GITHUB_TOKEN: ghp_xxxxx
# Enter value for SLACK_WEBHOOK (optional): https://hooks.slack.com/...
```

Or provide via file:

```bash theme={null}
stn bundle install ./bundle.tar.gz my-env --vars ./my-vars.yml
```

## Demo Bundles

Station includes demo bundles for testing:

```bash theme={null}
# List available demos
stn mock list

# Run a demo MCP server
stn mock cloudquery
stn mock aws-cost-explorer
```

## Best Practices

<AccordionGroup>
  <Accordion title="Version your bundles">
    Use semantic versioning in manifest:

    ```json theme={null}
    {
      "version": "1.2.3"
    }
    ```
  </Accordion>

  <Accordion title="Document variables">
    Always include descriptions for required variables:

    ```json theme={null}
    {
      "GITHUB_TOKEN": {
        "description": "GitHub API token with repo and read:org scopes"
      }
    }
    ```
  </Accordion>

  <Accordion title="Include examples">
    Add example variable files:

    ```yaml theme={null}
    # examples/development.vars.yml
    GITHUB_TOKEN: ghp_your_dev_token
    SLACK_WEBHOOK: ""  # Optional in dev
    ```
  </Accordion>

  <Accordion title="Test before sharing">
    Install your bundle in a fresh environment before sharing:

    ```bash theme={null}
    rm -rf ~/.config/station/environments/test
    stn bundle install ./my-bundle.tar.gz test
    stn sync test
    ```
  </Accordion>
</AccordionGroup>