Agent-Skills.md

Agent Skills: TrailBase

TrailBase project guide for installing and running the single-executable backend, configuring traildepot/config.textproto and migrations, exposing Record APIs, using auth and token flows, integrating first-party SDKs for TypeScript/JavaScript, Dart/Flutter, Rust, C#/.NET, Swift, Kotlin, Go, and Python, calling HTTP APIs directly, implementing WASM custom endpoints, and locating relevant source/docs in the trailbase repository. Use when Codex needs to answer or implement TrailBase setup, SDK, REST/HTTP API, auth, realtime, configuration, migration, deployment, or custom endpoint work.

UncategorizedID: lollipopkit/cc-skills/trailbase

Repository

lollipopkit/cc-skills
lollipopkit
2

Install this agent skill to your local

pnpm dlx add-skill https://github.com/lollipopkit/agent-skills/tree/HEAD/trailbase

Skill Files

Browse the full folder contents for trailbase.

Download Skill

Loading file tree…

trailbase/SKILL.md

Skill Metadata

Name
trailbase
Description
TrailBase project guide for installing and running the single-executable backend, configuring traildepot/config.textproto and migrations, exposing Record APIs, using auth and token flows, integrating first-party SDKs for TypeScript/JavaScript, Dart/Flutter, Rust, C#/.NET, Swift, Kotlin, Go, and Python, calling HTTP APIs directly, implementing WASM custom endpoints, and locating relevant source/docs in the trailbase repository. Use when Codex needs to answer or implement TrailBase setup, SDK, REST/HTTP API, auth, realtime, configuration, migration, deployment, or custom endpoint work.

TrailBase

Use this skill to work with TrailBase as an application platform: install it, start it, configure traildepot, expose data through Record APIs, call HTTP APIs directly, or integrate a first-party SDK.

Prefer current repo files over memory. If the user asks about the public/latest release, package version, Docker tag, or external docs, verify online or from the package registry before giving version-specific advice.

Workflow

  1. Identify the task surface:
    • Install/run/deploy: read references/install-run.md.
    • config.textproto, migrations, Record API setup, ACLs: read references/config-and-migrations.md.
    • Direct HTTP/Auth/Record API calls: read references/http-api.md.
    • OAuth, OIDC, PKCE, or "TrailBase as SSO" questions: read references/oauth-sso.md.
    • SDK integration: read references/sdk.md, then inspect the language-specific client source if precision matters.
    • WASM custom endpoints: read references/custom-wasm-apis.md.
    • Repo navigation or implementation changes: read references/source-map.md.
  2. Verify against source for nontrivial answers. TrailBase has generated docs and multiple clients; source can drift from docs.
  3. For code examples, use localhost http://localhost:4000 unless the user gives another base URL.
  4. For auth-sensitive examples, never invent tokens. Show placeholders such as ${AUTH_TOKEN} or obtain tokens from a real login command if credentials are provided.

Core Facts

  • TrailBase is a single executable named trail; trail run starts a local server on localhost:4000 and bootstraps ./traildepot.
  • Admin UI is at /_/admin/; optional auth UI is added with trail components add trailbase/auth_ui and then lives under /_/auth/login.
  • Record APIs expose STRICT SQLite TABLEs or VIEWs with an INTEGER, UUIDv4, or UUIDv7 primary key.
  • Main public Record API path is /api/records/v1/<api-name>.
  • Main auth path is /api/auth/v1.
  • Auth tokens are sent with Authorization: Bearer <auth_token>; refresh and CSRF tokens may also be represented as Refresh-Token and CSRF-Token headers by SDKs.
  • TrailBase can broker sign-in through configured external OAuth/OIDC providers and supports an auth-code + PKCE handoff to native or different-origin apps. Do not describe it as a full OAuth/OIDC identity provider unless the current source has added standard IdP endpoints such as authorization, discovery, JWKS, and userinfo.
  • Realtime subscriptions are exposed under /api/records/v1/<api-name>/subscribe/<id-or-*>.

Validation

When changing a TrailBase repo checkout, prefer focused validation:

cargo test -p trailbase-client
pnpm --filter trailbase test
trail help
trail run

Pick commands that match the files touched. If commands require missing dependencies, report the exact blocker and still provide source-backed reasoning.