rowboat-api

rowboat-api

The Rowboat desktop backend. Replaces the closed hosted backend (https://api.x.rowboatlabs.com) that the Electron desktop (apps/x) calls. It owns billing/credits, the LLM gateway, vendor proxies (voice, search), the Google OAuth broker, and the managed connector handshake.

See RFC 010 for the service-plane design, RFC 011 for auth boundaries, and RFC 012 for the connector broker protocol.

A note on the podinfo bootstrap

The plan calls for cloning stefanprodan/podinfo and stripping it. The end-of-bootstrap sanity check the plan defines is "zero references to stefanprodan/podinfo in any non-attribution file" — i.e. the scaffolding is meant to end up fully ours regardless. Rather than clone ~100 demo files and delete most of them, this service ships a clean, equivalent scaffold that satisfies every bullet of the plan's end-of-bootstrap state:

• compiles via go build ./..., passes go vet ./... and golangci-lint run
• boots via go run ./cmd/server and answers /healthz + /readyz with 200s
• emits one OTel span per request and structured JSON logs to stdout
• multi-stage distroless Dockerfile, Makefile, graceful shutdown, Prometheus metrics on a separate port — the operational scaffolding podinfo is prized for
• zero stefanprodan/podinfo references anywhere

This is the faithful realization of the plan's intent (a production-grade Go microservice skeleton) without carrying podinfo's demo surface.

Layout

cmd/server/        main.go + wire.go (composition root)
internal/
  appconfig/       env-driven Config (single config surface)
  openapidoc/      post-entoas OpenAPI enrichment for the mounted runtime API
  telemetry/       zap logging + OTel tracing
  server/          chi router, middleware chain, health probes, graceful shutdown
  version/         build-time version stamping (ldflags)
  ...              feature packages land per-milestone (config, billing, llm, …)
ent/               ent schemas → generated type-safe client (see ent/README)
charts/            Helm values live at repo-root charts/rowboat-api/

Run locally

make run                       # go run ./cmd/server
# or
make build && ./bin/rowboat-api

curl localhost:8080/healthz    # {"status":"ok"}
curl localhost:8080/readyz     # {"status":"ready"}
open http://localhost:8080/docs # Scalar API reference
curl localhost:8080/openapi.json
curl localhost:9090/metrics    # prometheus

All configuration has dev defaults; see internal/appconfig/config.go for the full env-var surface and .env.example for a starting point.

Local end-to-end with the desktop

Sign-in uses real WorkOS AuthKit, brokered by rowboat-api (WorkOS is a confidential client, so the code→token exchange runs server-side; no Ory Hydra — see AUTH.md). Vendor keys are read from the gitignored root .env, which docker compose auto-loads — no manual sourcing.

docker-compose.rowboat-api.yml brings up Postgres, Redis, Temporal, the API, and the Temporal worker. Assistant chat is a workflow on that worker. Without both, POST /v1/agent-sessions returns 503 temporal_unavailable and the composer never replies.

Chat calls live OpenRouter (https://openrouter.ai/api/v1). Put OPENROUTER_API_KEY in the root .env and leave OPENROUTER_BASE_URL unset. devstack is not on that path. Set ROWBOAT_COMPOSE_MOCK_LLM=1 only for an offline plumbing check; devstack then answers every turn with Hello from the mock LLM.

ACTIONS_ENABLED is on, matching the kind chart, so Agent approvals lists a real queue. No Act-seam URL is configured, so approving a proposal cannot execute it externally.

# root .env holds WORKOS_API_KEY, OPENROUTER_API_KEY, OPENAI_API_KEY,
# GOOGLE_CLIENT_ID, and GOOGLE_CLIENT_SECRET
docker compose -f docker-compose.rowboat-api.yml up --build -d
cd apps/x && API_URL=http://localhost:18080 npm run dev   # point the desktop at the local api

Then click “Sign in to Rowboat” in the desktop sidebar: the desktop asks rowboat-api for the WorkOS authorize URL, opens it in the browser (the real AuthKit login), and on callback hands the code to rowboat-api’s /v1/auth/workos/exchange, which completes the exchange server-side with the API key and returns tokens. rowboat-api verifies the returned WorkOS token on every call (TOKEN_ISSUER=https://api.workos.com, WorkOS JWKS). No tokens are injected.

Google OAuth. Compose maps GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET from the root .env onto GOOGLE_OAUTH_CLIENT_ID / GOOGLE_OAUTH_CLIENT_SECRET and leaves the token URL unset, so refresh uses https://oauth2.googleapis.com/token. The redirect URI registered on the Google client must be http://localhost:18080/oauth/google/callback.

Host ports: API 18080, gRPC 18081, API metrics 19090, worker metrics 19091, Temporal 7233, devstack 8090, Postgres 5433.

Local kind cluster with the Helm chart

Use this when you want to validate the Kubernetes deployment path locally. It deploys the real charts/rowboat-api chart into kind with local Postgres, Redis, and the devstack OIDC/WorkOS/LLM mocks:

scripts/rowboat-api-kind.sh up
scripts/rowboat-api-kind.sh desktop

The desktop runs with API_URL=http://localhost:18080. See docs/LOCAL_KIND_ROWBOAT_API.md for the full workflow and smoke-test coverage.

The Scalar API reference is available at http://localhost:18080/docs, backed by the embedded OpenAPI document at http://localhost:18080/openapi.json.

Fly.io deployment

Fly.io is supported as an alternative production target with one public API Machine in US East (iad) and one in US West (sjc). The default topology keeps the East API warm, lets the West API stop while idle, and runs one worker and one scheduler in the primary region. See docs/fly-io.md for provisioning, secrets, deployment, cost, and rollback guidance.

Public SDK contract

api/openapi.json is the public contract for generated REST SDKs. Ent schemas feed the OpenAPI components, cmd/openapi-enrich replaces the path surface with the mounted runtime API, and the TypeScript SDK in packages/rowboat-api-client-ts is generated from the resulting document.

Regenerate the SDK after changing public routes, request/response schemas, or OpenAPI enrichment:

make sdk-generate

Ports

Make targets

ent codegen extensions

The ent layer enables the full extension toolchain (make generate reproduces all of it):

CreditLedger (append-only) and OAuthPending (TTL'd) are intentionally excluded from history. History tables and sensitive token columns are excluded from the GraphQL/gRPC surfaces.

Milestone status

All plan milestones implemented (config, identity, LLM gateway, voice/exa, Google OAuth, managed connectors) plus the full ent extension toolchain. See the repo task list / commit history for details.