# Sylphx

> Sylphx is a developer platform (PaaS + BaaS) for shipping production apps on a single stack: Git-to-URL deploys, managed Postgres / Redis / object storage / search / realtime, scoped service tokens, OIDC federation, and a first-class CLI. Every resource is addressed by a TypeID (e.g. `proj_01hx…`, `env_01hx…`, `dpl_01hx…`). Every hostname is an immutable DNS-safe slug (e.g. `bold-river-a1b2c3.sylphx.app`).

This file is for AI coding agents and humans who want to orient fast. Paste the URL into Claude/Cursor/Zed and ask whatever you want. For the full text (all docs + every command's `--help` + OpenAPI as markdown), fetch `https://sylphx.com/llms-full.txt`.

## Start here

- [Overview](https://sylphx.com/docs): what Sylphx is, how it differs from Vercel / Railway / Render.
- [Quickstart](https://sylphx.com/docs/quickstart): install CLI, log in, deploy in < 3 minutes.
- [CLI install + quickstart](https://sylphx.com/docs/installation): install the `sylphx` command and deploy your first app.
- [Management API](https://sylphx.com/docs/api-reference): REST over HTTPS. OpenAPI at [openapi.json](https://api.sylphx.com/v1/openapi.json).
- [Full context in one file](https://sylphx.com/llms-full.txt): every doc page concatenated for single-fetch ingestion.

Operator and agent workflows use the `sylphx` CLI plus the Management API. Deployed customer apps use `@sylphx/sdk` against the BaaS plane.

## Auth — three modes

Management API base URL: `https://sylphx.com/api/v1`.

1. **OAuth / user session** — browser-backed interactive flow, CLI and web dashboard.
   ```
   sylphx login
   # opens browser → stores OAuth access + refresh pair in ~/.sylphx/config.json
   ```
   Access tokens are 15-minute RS256 JWTs with `aud=platform`; the CLI auto-refreshes.

2. **Service tokens** — scoped, revocable, for CI servers and long-running workloads.
   ```
   sylphx tokens create deploy-bot --scopes project:deploy --expires-in 90d
   # plaintext is printed ONCE; store it immediately
   curl -H "Authorization: Bearer svc_…" https://sylphx.com/api/v1/projects
   ```

   **Non-interactive CLI use (CI / agents).** Set `SYLPHX_TOKEN` and the
   CLI uses it as a Bearer token on every request — no browser, no
   `sylphx login`, no `~/.sylphx/config.json` write. The env var wins
   over any stored OAuth session and skips the refresh interceptor
   (service tokens are stateless; caller-managed JWTs are
   operator-rotated).
   ```
   export SYLPHX_TOKEN="svc_…"      # service token (recommended for CI)
   # or
   export SYLPHX_TOKEN="eyJ…"       # OAuth access JWT (short-lived)
   sylphx whoami                    # confirms "Auth: SYLPHX_TOKEN env var"
   sylphx deploy --env=production
   ```
   Agents authenticating to Sylphx MUST use `SYLPHX_TOKEN`. Do NOT
   attempt to drive the OAuth device flow programmatically and do NOT
   query the database directly.

3. **OIDC federation** — no long-lived secrets, exchange a provider JWT for a short-lived scoped Sylphx token. Works with GitHub Actions, GitLab CI, Bitbucket Pipelines, and custom issuers.
   ```
   curl -X POST https://sylphx.com/api/v1/auth/oidc/exchange \
     -H 'Content-Type: application/json' \
     -d '{"token":"<provider-id-token>","audience":"sylphx"}'
   ```

Legacy `slx_*` personal access tokens were eliminated on 2026-04-21 (ADR-059). They are not accepted.

## CLI quickstart

```
# 1. Install
curl -fsSL https://sylphx.com/install.sh | sh

# 2. Log in (OAuth device flow)
sylphx login

# 3. Link current directory to a project (creates one if needed)
sylphx init

# 4. Deploy HEAD
sylphx deploy

# 5. Stream logs (SSE)
sylphx logs --follow
```

Five commands to know:

- `sylphx deploy` — build + push + deploy HEAD to the current env.
- `sylphx logs` — SSE-streamed build + runtime logs.
- `sylphx env {set,rm,list}` — environment variables.
- `sylphx db {create,list,branch}` — managed Postgres lifecycle.
- `sylphx rollback` — redeploy the previous deployment ID.

Full list: `sylphx --help`. Every command supports `--help`.

## Canonical API endpoints

```
GET    /api/v1/projects                                     # list
POST   /api/v1/projects                                     # create
GET    /api/v1/projects/{proj_id}                           # get
POST   /api/v1/projects/{proj_id}/deploy                    # trigger deploy
GET    /api/v1/projects/{proj_id}/logs?stream=true          # SSE logs
POST   /api/v1/projects/{proj_id}/rollback                  # rollback
GET    /api/v1/projects/{proj_id}/env-vars                  # list secrets
POST   /api/v1/projects/{proj_id}/domains                   # attach custom domain
```

All request and response IDs are **TypeIDs** (`org_`, `proj_`, `env_`, `svc_`, `esvc_`, `user_`, `sess_`, `dpl_`, `dom_`, `sec_`, `run_`, `task_`, `sbx_`, `bkt_`, `vol_`, …). Raw UUIDs are rejected with `400 invalid_id` (ADR-055 §1, invariant #6).

All mutating endpoints accept an `Idempotency-Key` header. Retries with the same key return the first response verbatim.

## Anti-patterns

- **Don't** hand-SSH into the cluster or open the DB directly — there is a CLI or API endpoint for every operator task. If something's missing, that's a product gap; file an issue.
- **Don't** hard-code `*.sylphx.app` hostnames in app code — read the slug from `sylphx env` or the deployment response.
- **Don't** ship long-lived service tokens in CI — use OIDC federation.
- **Don't** assume registry images are public — `registry.sylphx.com` is private, per-project.
- **Don't** call `internal.sylphx.com` or other un-documented hostnames — those use SPIFFE SVID mTLS for platform-internal calls (ADR-068) and are not part of the public contract.
- **Don't** `RENAME COLUMN` or `DROP COLUMN` in the same migration as the code change — Sylphx enforces expand-and-contract (ADR-057). Use three migrations: ADD nullable → backfill + dual-write → DROP.

## Why no MCP server?

Sylphx deliberately does not ship an MCP (Model Context Protocol) server. The REST API + OpenAPI + CLI + this `llms.txt` already cover every agent workflow with zero new moving parts. MCP would add a runtime process, a second auth model, and a second schema that drifts from the real API. When an agent is asked to "deploy my app to Sylphx," we want it to run `sylphx deploy` — the same command users run, the same command our docs teach, the same command support debugs. If the industry consolidates on a meaningful MCP dialect, a small shim wrapping the CLI can ship without creating a second public API.

## Optional

- [Changelog](https://sylphx.com/changelog)
- [Status](https://status.sylphx.com)
- [API reference](https://sylphx.com/docs/api-reference)
- [OpenAPI JSON](https://api.sylphx.com/v1/openapi.json)

---

# Full documentation