---
name: starsystem
description: >
  Operates the Starsystem infrastructure control plane (ss CLI + MCP server).
  Use when users ask to provision services, register domains, manage DNS records,
  deploy to Fly/Railway/Neon/Supabase/AWS/Cloudflare, browse the provider catalog,
  or manage vault credentials for infrastructure services.
---

# Starsystem

## Purpose

Starsystem (`ss`) is the infrastructure control plane. It reads `starsystem.yaml`, reconciles desired state against actual running state, and manages secrets via the vault. Use this skill whenever users want to:

- Deploy or provision cloud infrastructure (databases, apps, domains, CDN, storage)
- Register and manage domain names and DNS records
- Browse available providers and compare pricing
- Manage vault credentials for infrastructure services
- Start/stop/restart local processes

## Safety rules

- Never print vault secret values — use `ss vault list-keys` and masked commands only
- Never provision or destroy resources without the user confirming intent
- Always check `starsystem_read_system` or `ss provision --dry-run` before making changes
- Porkbun domain registration **charges money** — confirm domain + price before provisioning
- AWS S3/CloudFront creation may incur costs — confirm region and resource type first

---

## Standard workflows

### Check what's running

```bash
ss status                         # running services + PID + URL
ss provision --status             # health check all provisioned services
ss provision --dry-run            # show plan without executing
```

MCP equivalent:
```
starsystem_read_system
starsystem_provision_status
```

---

### Browse providers and pricing

```bash
ss catalog                        # all providers + SaaS services
ss catalog --category=dns         # domain/DNS providers
ss catalog --category=database    # databases with pricing tiers
ss catalog --category=auth        # auth providers (Clerk, Auth0)
ss catalog --json                 # machine-readable
```

MCP equivalent:
```
starsystem_catalog
starsystem_catalog category="dns"
```

---

### Provision infrastructure

1. **Set vault credentials** for the provider:
   ```bash
   ss vault set-key <provider> api_key <value>
   # e.g.: ss vault set-key neon api_key <token>
   # e.g.: ss vault set-key porkbun api_key <pk1_...>
   # e.g.: ss vault set PORKBUN_SECRET_KEY <sk1_...>
   ```

2. **Add the service** to `starsystem.yaml`:
   ```bash
   ss provision --dry-run          # preview what will happen
   ss provision                    # execute
   ```

3. **Verify**:
   ```bash
   ss provision --status
   ```

MCP workflow:
```
starsystem_catalog category="<type>"      # discover provider + example YAML
starsystem_read_yaml                      # read current config
starsystem_validate_yaml yaml="..."       # validate proposed changes
starsystem_apply_yaml yaml="..."          # apply changes
starsystem_provision_service service_id="<id>"  # provision the new service
starsystem_provision_status               # verify health
```

---

### Register a domain and wire DNS (Porkbun)

**Prerequisites:**
```bash
ss vault set-key porkbun api_key pk1_...
ss vault set PORKBUN_SECRET_KEY sk1_...
```

**YAML pattern** (add to `starsystem.yaml`):
```yaml
services:
  domain:
    type: dns
    name: My Domain
    depends_on: [api]               # ensures api is provisioned first
    provision:
      provider: porkbun
      domain: myapp.io
      auto_renew: true
      records:
        - type: A
          name: "@"
          content: "{{ vault('api.FLY_IP') }}"   # resolves at deploy time
        - type: CNAME
          name: www
          content: myapp.io
        - type: TXT
          name: "@"
          content: "v=spf1 include:_spf.google.com ~all"
    credential_env: DOMAIN_NAME
```

**Record name convention:** `"@"` = root domain, `"www"` = www subdomain.

**Vault ref syntax:** `{{ vault('serviceId.ENV_VAR') }}` — resolves the vault value stored by another service. Use `depends_on` to guarantee the other service provisions first.

---

### Deploy to Fly.io

```bash
ss vault set-key fly api_key <fly-token>
```

```yaml
services:
  api:
    type: app
    provision:
      provider: fly
      image: ghcr.io/my-org/api:latest
      region: iad
    credential_env: API_URL
```

```bash
ss provision --service=api
```

---

### Deploy to AWS (S3 + CloudFront)

```bash
ss vault set-key aws access_key_id <AKIA...>
ss vault set AWS_SECRET_ACCESS_KEY <secret>
```

```yaml
services:
  docs-cdn:
    type: storage
    provision:
      provider: aws
      resource: s3-cloudfront       # s3-bucket | cloudfront | s3-cloudfront
      bucket: my-docs-bucket
      region: us-east-1
      public: true
      website: true
```

---

### Cloudflare (Pages, R2, DNS, Workers KV)

```bash
ss vault set-key cloudflare api_key <cf-token>
```

```yaml
services:
  site:
    type: web
    provision:
      provider: cloudflare
      resource: pages-project        # pages-project | r2-bucket | dns-zone | workers-kv
      project: my-site
      custom_domains: [myapp.io]
```

---

## Vault credential reference

| Provider | Vault key command |
|---|---|
| Neon | `ss vault set-key neon api_key <token>` |
| Supabase | `ss vault set-key supabase api_key <token>` |
| Fly.io | `ss vault set-key fly api_key <token>` |
| Railway | `ss vault set-key railway api_key <token>` |
| Cloudflare | `ss vault set-key cloudflare api_key <token>` |
| AWS | `ss vault set-key aws access_key_id <AKIA...>` + `ss vault set AWS_SECRET_ACCESS_KEY <s>` |
| Porkbun | `ss vault set-key porkbun api_key <pk1_...>` + `ss vault set PORKBUN_SECRET_KEY <sk1_...>` |

Run `ss catalog` to see the full list with descriptions.

---

## Service types in YAML

| `type:` value | Used for |
|---|---|
| `database` | Postgres, Redis, SQLite, vector DBs |
| `app` / `container` | Web services, workers |
| `web` | Frontend / static sites |
| `dns` | Domain registration + DNS records (Porkbun) |
| `tls` | TLS certificates via Caddy / ACME |
| `storage` | Object storage (S3, R2) |
| `auth` | Auth provider (Clerk, Auth0) |
| `email` | Email sending (Resend, Postmark) |
| `queue` | Job queues (Upstash, Inngest) |
| `observability` | Monitoring, error tracking |
| `external` | Any SaaS with an API key — no provisioning |
| `process` | Arbitrary shell command |

---

## MCP tools quick reference

| Tool | Purpose |
|---|---|
| `starsystem_read_system` | Full system snapshot — call first |
| `starsystem_read_yaml` | Raw YAML content |
| `starsystem_validate_yaml` | Validate before applying |
| `starsystem_apply_yaml` | Apply config changes |
| `starsystem_add_service` | Add a new service |
| `starsystem_provision_service` | Provision one service immediately |
| `starsystem_provision` | Provision all services |
| `starsystem_provision_status` | Health check all provisioned services |
| `starsystem_catalog` | Browse providers + pricing |
| `starsystem_credentials_status` | Check which credentials are set |
| `starsystem_credentials_set` | Store credentials (only with user-provided values) |
| `starsystem_start_service` | Start a local service |
| `starsystem_stop_service` | Stop a local service |
| `starsystem_tail_logs` | Read recent log lines |
| `starsystem_test_connection` | Verify a service is reachable |