Frequently Asked Questions
This FAQ targets engineers operating redactor-svc locally—pairing, testing auth, and validating the Chrome extension before Lovable takes over.
Need to know how the appliance, extension, and orchestrator interact? Start with these answers.
What is this appliance?
It’s a standalone redactor-svc instance meant for local racks, labs, or CI environments. You use it to configure pairing, test auth flows, mint local users, and validate credits before Lovable orchestrates the production fleet.
How do I pair it with Lovable?
Sign in, open Admin ▸ Pairing, paste the token from Lovable, and click Generate challenge. Give the challenge code to the orchestrator so it can call
POST /admin/local/pairing/credentials with the same token. Once the orchestrator responds with signed credentials, the UI will show the bundle you can export to extensions.
How do local test users work?
Under Admin ▸ Users you can quick-create sample identities, assign roles/labels, and mint bearer tokens. These tokens are accepted whenever
AUTH_MODE=local and are perfect for extension developer mode.
What authentication modes exist?
Set
AUTH_MODE=local to bypass OIDC and rely on local tokens. In production the orchestrator provisions an IdP client and the extension uses Authorization Code + PKCE. Either way you must set DEV_SHARED_SECRET so /dev/instance/metadata stays protected.
How does the Chrome extension connect?
Download it from /extension, then import the pairing bundle (preferred) or enable Developer mode and paste a local token + issuer. Manual settings are hidden again once you turn Developer mode off.
How do I handle credits while testing?
The Credits tab lets you select any test user, switch their plan, or grant/revoke balances. Calls hit the same internal APIs the orchestrator would use, so your scripts can mimic them via REST.
Which APIs does the orchestrator call?
Pairing lives under
/admin/local/pairing/*. Health/metadata is exposed via /dev/instance/metadata (use X-Dev-Shared-Secret). Standard redact/unredact/credits APIs live under /{realm}/.
How do I reset the local admin password?
Delete the
local_admin_secrets row in Postgres (or wipe the database volume) and restart the service. On next load the UI will prompt for a new password. Remember to clear all browser cookies for the old session.
Where are the architecture docs?
See the repository’s
docs/orchestrator-guide.md for the full pairing lifecycle, docs/pairing-bundle.md for the bundle schema, and the OpenAPI spec at /docs for endpoint details.
Need more help?
Check the Admin tabs (Pairing, Users, Credits) for in-product hints, review the repository docs, or inspect the API schema at /docs. Most workflows we expect orchestrators to automate are exposed there.
Reference links
Handy touchpoints while you’re wiring up an orchestrator or running local QA:
- OpenAPI schema – redact/unredact, credits, and metadata endpoints.
docs/orchestrator-guide.md– control-plane responsibilities and pairing flow.docs/pairing-bundle.md– bundle schema for extension provisioning.- Extension options – bundle import/export and developer mode.
Keep these links handy when onboarding a new appliance; they mirror what Lovable expects from each environment.