# Sylphx

> Sylphx is a developer platform (PaaS + BaaS) for shipping production apps on a single stack: Git-to-URL deploys, managed Postgres / cache / 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 expanded public context, 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).
- [Expanded public context](https://sylphx.com/llms-full.txt): audited customer-facing docs 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://api.sylphx.com/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 90
   # plaintext is printed ONCE; store it immediately
   curl -H "Authorization: Bearer svc_…" https://api.sylphx.com/v1/projects
   ```

   **Non-interactive CLI use (CI / agents).** Set `SYLPHX_TOKEN=svc_…`
   for stateless service-token auth, or inject `SYLPHX_ACCESS_TOKEN`
   plus `SYLPHX_REFRESH_TOKEN` for a managed OAuth agent session. OAuth
   pairs are imported into the normal CLI refresh chain and use the
   cross-process refresh lock; service-token sources skip refresh.
   `SYLPHX_TOKEN_FILE` can hold either a raw service token /
   `SYLPHX_TOKEN=svc_…` file or an access+refresh OAuth pair.
   ```
   export SYLPHX_TOKEN="svc_…"      # service token (recommended for CI)
   # or
   export SYLPHX_ACCESS_TOKEN="eyJ…"
   export SYLPHX_REFRESH_TOKEN="..."
   sylphx whoami                    # confirms refreshable OAuth env auth

   printf '%s\n' 'SYLPHX_TOKEN=svc_…' > ~/.sylphx/agent-token.env
   chmod 600 ~/.sylphx/agent-token.env
   export SYLPHX_TOKEN_FILE=~/.sylphx/agent-token.env
   sylphx whoami                    # confirms "Auth: SYLPHX_TOKEN_FILE (...)"
   sylphx deploy --env=production
   ```
   Agents authenticating to Sylphx MUST use a scope-limited service token
   for long-running automation, or inject both OAuth access and refresh
   tokens when a credential broker owns the session. Do NOT attempt to
   drive the OAuth device flow programmatically, do NOT copy
   `~/.sylphx/config.json` between machines, 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://api.sylphx.com/v1/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 the CLI
bun add -g @sylphx/cli
# npm: npm install -g @sylphx/cli

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

Beyond the basics (all verified against the shipped CLI):

- `sylphx tasks {list,get,create}` — durable background tasks: one-off jobs, cron schedules, or long-running services.
- `sylphx backup {create,list,restore}` — managed database backups (restore is destructive and confirms first).
- `sylphx db branch` — copy-on-write database branches for previews and experiments.
- `sylphx tokens {create,list,rotate,revoke}` — scoped `svc_*` service tokens for CI and agents.
- `sylphx health verify --file <chain.json>` — verify an exported audit-grade health history chain.
- Pull requests get isolated preview environments automatically; `sylphx previews` shows per-PR cost.

Full list: `sylphx --help`. Every command supports `--help`, and list/inspect commands support `--output json` for machine parsing.

## Canonical API endpoints

```
GET    https://api.sylphx.com/v1/projects                                     # list
POST   https://api.sylphx.com/v1/projects                                     # create
GET    https://api.sylphx.com/v1/projects/{proj_id}                           # get
POST   https://api.sylphx.com/v1/projects/{proj_id}/deploy                    # trigger deploy
GET    https://api.sylphx.com/v1/projects/{proj_id}/logs?limit=100            # build logs
GET    https://api.sylphx.com/v1/environments/{env_id}/logs?type=runtime&stream=true  # SSE runtime logs
POST   https://api.sylphx.com/v1/projects/{proj_id}/rollback                  # rollback
GET    https://api.sylphx.com/v1/projects/{proj_id}/env-vars                  # list secrets
POST   https://api.sylphx.com/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** bypass the CLI or API for platform operations. 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** expose platform-owned build artifact references; they are not part of the public contract.
- **Don't** call undocumented platform hostnames; they 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. Any instruction the CLI, Management SDK, BaaS SDK, or OpenAPI cannot express is a product gap to fix in those first-class surfaces, not a reason to add an MCP wrapper.

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