Hybrid development
Hybrid CLI routing and checks exist. Use requires a provisioned development Legal API and provider credentials.
Code and tests
Hybrid development keeps product code and private product data local while routing legal requests through the deployed development Legal API.
./bin/kesita dev up app --hybrid./bin/kesita dev up app --hybrid --mode container --detachArchitecture
Section titled “Architecture”flowchart LR
subgraph Local[Developer machine]
App[Kesita app]
Product[Product API and worker]
Parser[Document parser]
ProductData[(Product PostgreSQL<br/>and Azurite)]
App --> Product
Product --> ProductData
Product --> Parser
end
subgraph Azure[Azure development]
Legal[Legal API]
LegalDB[(Legal PostgreSQL<br/>and pgvector)]
Corpus[(Corpus originals)]
Legal --> LegalDB
Legal --> Corpus
Legal --> Voyage[Voyage]
end
Product -->|HTTPS + workload JWT| Legal
Product -->|real model calls| Anthropic[Anthropic]
The local stack does not start Legal Core, legal migrations, corpus workers, or legal fixtures. The deployed Legal API is the only path to the shared corpus and owns its database, Blob, and embedding credentials.
Authentication boundary
Section titled “Authentication boundary”sequenceDiagram
participant User
participant App as Local Kesita app
participant Product as Local product service
participant Legal as Development Legal API
participant Corpus as Legal data
User->>App: Clerk session
App->>Product: authenticated product request
Product->>Product: mint short-lived workload JWT
Product->>Legal: Legal API request + JWT
Legal->>Legal: verify issuer, audience, key ID,<br/>expiry, service, scope and policy
Legal->>Corpus: read using deployed identity
Corpus-->>Legal: authorized result
Legal-->>Product: contract response
Clerk authenticates the human. The workload JWT authenticates the Kesita service and carries organization, user, scope, and content policy. The remote API trusts only the public key configured for the development environment. The private key stays in the ignored local key file.
Local developers do not receive PostgreSQL, Blob, Voyage, or Azure service-principal credentials.
Configure
Section titled “Configure”Generate the local workload key pair through the normal setup, then register its public half and key ID with the development Legal API. Copy the ignored template:
cp infra/env/hybrid.env.example infra/env/hybrid.envConfigure:
- the HTTPS development Legal API URL;
- private and public workload key file paths;
- the matching workload key ID;
- an Anthropic key and model available to the development account.
Then start and verify the loop:
./bin/kesita dev up app --hybrid./bin/kesita dev doctor --hybridThe doctor performs a real semantic search and original download through the Legal API, plus a small billable Anthropic request. It never prints corpus or provider bodies.
Safety
Section titled “Safety”Hybrid mode is explicit and accepts only a remote HTTPS Legal API URL. Product database URLs must remain local. The CLI reads key files without placing their contents in the committed environment file.
Hermit remains the deterministic test gate and uses isolated simulations. Hybrid mode is a realistic integration check, not a replacement for automated tests.
./bin/kesita dev reset always rebuilds local simulated data and never modifies Azure resources.