Lina Live developer Quickstart
Lina Live Hosted, API 0.3. Resolve relative paths against the API origin shown in the console. Hosted voice requires payment, provider provisioning, operator capacity and DNS verification; read account.get and applications.check for the current state.
App model
An app is one configured interaction context: audience, an explicit instance profile, allowed origins, tools and memory/archive policies. It can handle many workflows. A public property app can search listings, request viewings and handle seller enquiries with different customer-owned tools. Create separate apps for distinct audiences, instructions or access boundaries, e.g. public website, authenticated customer area and internal operations. Existing apps should be inspected and updated rather than duplicated per task. Guest and account identities still need backend authorization even inside one app.
Erfindergeist operates the Lina servers: voice, model access, orchestration, Liveboard and platform storage. Customer setup integrates the website SDK and a session handler into the existing website/backend. The downloadable starter is for that website integration. The customer owns business systems, credentials, data authorization and tool semantics. No customer OpenAI key is needed. The instance profile selects frontend/backend models, voice, startup inputs and supported Live Responses parameters. Credentials, visitor authorization and business write permissions remain server-side.
Developer access
Read GET /v1/live/developer.json for capabilities and the operation index. Read GET /v1/live/openapi.json for exact inputs, outputs and scopes. Both are public static reference endpoints without account data. Schemas, not guessed fields, define the contract.
Create an API key in the authenticated console. Setup scopes are apps:read and apps:write; apps:publish permits explicit release selection. The existing default developer key includes all three. Use a different backend key with sessions:create only, created in Developer access by an authorized Organization member. New backend keys use kind=runtime and belong to the Organization; personal developer keys use kind=personal (the API default). Runtime keys accept only sessions:create and context:* scopes. Existing keys remain personal until explicitly replaced; their kind is shown in the key list. A management MCP key cannot create more keys. If the backend key is missing, request it rather than reusing the developer key. Context and transcript access require separate context:* / activity:* scopes; setup keys do not include those rights. Keys expire and can be revoked. API keys are tenant bound; do not submit a tenant override in an operation input.
Supply LINA_LIVE_API_KEY in the environment of the client process. Keep its value out of project config, chat, logs and browser code. Setting it in a child shell does not update an already running parent client. Merge the following configuration into the selected client’s existing config; do not overwrite unrelated servers. These are fixed bearer-key connections, not an OAuth login or an automatically installed integration.
Codex
Merge into the selected user/project config.toml; project configuration is subject to local trust and policy. Replace the example API origin if your console uses a different one.
[mcp_servers.lina_live]
url = "https://app.erfindergeist.ai/v1/live/mcp"
bearer_token_env_var = "LINA_LIVE_API_KEY"
startup_timeout_sec = 20
tool_timeout_sec = 75Claude Code
Merge the server into .mcp.json and use the client’s project trust/approval flow. The token variable must be available in the Claude Code process. The timeout below is milliseconds; Codex timeouts above are seconds.
{
"mcpServers": {
"lina_live": {
"type": "http",
"url": "https://app.erfindergeist.ai/v1/live/mcp",
"headers": {
"Authorization": "Bearer ${LINA_LIVE_API_KEY}"
},
"timeout": 75000
}
}
}MCP uses Streamable HTTP. tools/list returns only operations allowed by the current key. For example applications.get maps to lina_live_applications_get. HTTP uses POST /v1/live/ops/applications.get with Authorization: Bearer
Configure an app
- Read applications.list, applications.get and applications.version before modifying existing state. Read account.get and usage.get for hosted provisioning and usage policy. Use existing repository/business context and clarify missing decisions; a single-workflow intake form is not required.
- Create a draft only if needed. applications.create accepts id, name and config. Example config:
{"profile":{"schemaVersion":1,"frontend":{"model":"gpt-live-1","voice":"nuri","instructions":"Help buyers and sellers using our approved tools. Delegate research, business actions and Liveboard changes. Report only confirmed results.","input":[{"role":"developer","text":"Greet the visitor: Hello! How can I help?"}],"greetingInput":0,"contextInsertionIndex":0},"backend":{"model":"gpt-6-luna","instructions":"Use approved business tools for current data and actions. Use show_on_screen for relevant visuals. Return verified facts and execution status to the frontend.","reasoning":{"effort":"medium"},"service_tier":"auto","tool_choice":"auto","parallel_tool_calls":false},"execution":{"taskTracking":"provider","unansweredInputRecovery":false}},"origins":["https://www.customer.com"],"tools":[],"memory":{"mode":"hosted","retentionDays":30,"allowProfileUpdates":true},"monitoring":{"retentionDays":30}}The profile is explicit: frontend.instructions is the complete Live instruction string; frontend.input is the ordered startup text with developer/user/assistant roles. greetingInput references one developer input for the one-time opening commentary, or null for listen-first. contextInsertionIndex chooses where authorized session data/history are inserted; configured startup messages are not truncated. backend.instructions is separate from frontend instructions; model and supported reasoning, text, max_output_tokens, service_tier, tool_choice and parallel_tool_calls settings go directly to Live Responses delegation. Unset optional parameters are omitted. No platform personality, sales knowledge, shared-session instructions or generic backend prompt is appended. GPT-Live leads the conversation and native Responses delegation runs the configured backend. execution.unansweredInputRecovery selects the optional recovery of unanswered input. execution.taskTracking is retained only for reading existing profiles: use provider in new profiles. The legacy reported value no longer enables a semantic task state machine or automatic routing of later speech to an old question. Existing reported profiles retain a no-op report_task_status tool only so their unchanged instructions remain executable; do not request that tool in new instructions. Conversation goals and missing information are model context, while actual business actions are confirmed by their tool results. The runtime also supplies show_on_screen and, when authorized memory is enabled, recall_context/remember_context. Business tool descriptions and connections are the declared config.tools, with server-enforced permissions. The former top-level instructions/greeting fields are rejected; there is no implicit legacy translation.
Official parameter references (checked 2026-10-24): https://developers.openai.com/api/docs/guides/live-delegation and https://developers.openai.com/api/reference/resources/live/methods/create. Live accepts a subset of standalone Responses settings. Model/project access and parameter support are validated by OpenAI; schema validity alone does not prove runtime availability. The supported contract intentionally excludes temperature, reasoning.mode and effort max because they are not in the checked Live session schema. Known GPT-6 effort restrictions are validated locally.
The 30-day policy is illustrative. Agree retention for this project; do not silently replace existing memory with session-only context. Hosted memory supports history, resumed threads and curated long-term context. External/session modes are also supported. A separate monitoring policy enables hosted transcripts even with external context; otherwise hosted memory supplies its archive retention, and external/session modes do not archive content by default.
- Register customer-owned connections with connections.configure, pinning id, version, HTTPS/MCP kind, endpoint and auth. Each tool declares name, description, inputSchema, resultSchema, read/write effect, timeout and the connection version; optional remoteName maps the upstream tool. Use connections.inspect for MCP metadata. applications.configure appends a config version and requires expectedRevision. Preserve the other tools and policies when adding a workflow. No universal Gmail/CRM OAuth connector is implied: the customer owns upstream authentication.
- Publish a reviewed immutable version with applications.publish and its current expectedRevision. Configuration and release selection are separate. Publishing does not start a call. Lost mutation responses require reading current state, not a blind duplicate create. Unpublishing/revoking is explicit.
- Request domains.request for the exact HTTPS origin, install its TXT record, then call domains.verify. DNS changes remain the customer’s deployment responsibility. applications.check reports release, DNS, tools, model access and capacity blockers without opening a session. A successful app config alone is not readiness. Operator/provider budgets cannot be raised with a customer key.
Customer tool contract and Liveboard
Two MCP directions are separate: this management server configures the platform; registered customer MCP connections provide business functions to the voice runtime. Choose the business tools the app needs. Access is checked on the backend, never granted by a spoken claim or a campaign label.
For HTTPS tools, the runtime POSTs {“version”:“1”,“requestId”:“
Return HTTP 200 JSON, e.g. {“status”:“succeeded”,“result”:{“items”:[]}} matching resultSchema. Other outcomes are needs_input with fields, pending with optional operationId, failed with code, or uncertain with code. pending is not success and has no automatic polling: expose an explicit read tool if needed. uncertain requires reconciliation with the business system before retrying. tools.test is a real external invocation, not a sandbox; writes additionally need allowWrite:true and all tests need explicit authorization. Reuse the same requestId for a retry of the same operation; do not blindly duplicate a possibly completed write.
The runtime provides show_on_screen for validated Liveboard scenes. Customer tools return business data; they do not register or override this reserved platform tool. Scenes use fixed components: layout Column, Row, Grid and Tabs; content Text, Stat, Card, Facts, Table, Bars, Score, Image, Website, List, Tags, Compare, Steps, Timeline and Callout; interaction Choice, Field and Button; navigation Link. Read liveboard.components in developer.json for the exact fields and limits. A scene is a flat components array with a root container and child IDs. A tap on a Button, a selectable Card or a Choice option, and a short Field entry, return to the conversation; any resulting business action must still pass backend permissions. Link opens an explicit HTTPS URL in a new tab; opening it is not a confirmed business action or payment. Images/website previews depend on available source data. Speaking about a result does not display it; the runtime must use show_on_screen. Instance-specific offers use the same generic components. No arbitrary generated JavaScript/HTML executes on the Board.
Backend identity, session grants and embedding
Public Hosted instances share server-enforced inactivity warnings/closure and conversation guardrails. Configure config.security through a reviewed, published app version: idleSeconds (default 180), idleWarningSeconds (default 20), guard.scope, guard.warnings (default 1) and guard.enabled. These choices are editable in the customer app configuration. Empty scope uses the frontend instruction text. Active backend work and Lina’s speech are not idle time. Customer HTTPS/MCP tool timeoutMs defaults to 30000 and can be 1000–60000; a tool failure does not end the conversation. Hosted usage is billed in conversation seconds against included/prepaid minutes, not a backend-token allowance. There is no cumulative token, tool, delegation or guard-check allowance that ends a conversation. Erfindergeist fixes application work protection at 180 seconds and 120 tool calls per backend run, plus serialized guard checks at most once per five seconds and 60 browser requests per minute. Run protection withdraws local tool authority, aborts cancellable requests and marks the run failed while speech stays connected; already dispatched writes may still execute and require verification before any retry. Live Responses delegation has no documented individual provider-cancel event: provider work may drain and late usage remains counted. Deprecated security work-counter fields are accepted for old configuration history but ignored. Access, schema, identity and write permissions always remain enforced. The customer’s session backend must still validate visitor admission and bot protection before creating a grant; Origin alone is not authentication. A failed or outdated conversation check cannot authorize a tool action.
Implement a same-origin POST /api/lina-live/session on the customer’s backend. It validates visitor admission, bot/cost policy, existing login or trusted guest association, allowed memory scope and write consent. Fix application/origin in server configuration; ignore browser attempts to override these or identity/write rights.
Set limits and complete the public visitor checks
Explain these three responsibilities during setup, including when a coding assistant performs the integration:
- Erfindergeist enforces workspace isolation, credentials, tool permissions, runtime/provider capacity, funded usage and shared technical conversation guardrails.
- The customer chooses business limits. Read usage.get, then call usage.configure with expectedRevision from settings.revision and config:{limits:{maxSessionSeconds,concurrentSessions,dailySessions,dailySeconds,monthlySeconds},publicAdmission:{startsPerIpPerDay}}. Limits are optional overrides within the capacity returned by usage.get; seconds are used for durations and allowances. Empty limits inherit available capacity and available credit remains required. The same settings are editable under Usage in the customer area. Changes affect new conversations; old unclaimed grants are revoked. Existing active conversations retain their issued duration/reservation. This cannot change tariffs, payment state, provider caps or credit. The IP daily limit defaults to 0 (disabled); explicit existing customer choices remain unchanged. Application-specific topic/idle choices remain in versioned config.security; provider work limits are not customer settings.
- The customer’s website backend must implement actual visitor admission. Verify bot tokens server-side before sessions.create; check expected host/action, expiry/replay and fail closed on invalid proof. Origin/CORS and a browser identifier do not authenticate a visitor. Use trusted proxy metadata for client IP. With the separate sessions:create runtime key, admission.get returns only revision/publicAdmission for applying the chosen visitor rules. Enforce the daily IP rule with durable atomic counters; add appropriate short IP/visitor limits. Do not use a setup/developer key in the runtime backend. Multiple backend processes must share counters. Rotating VPN IPs require the shared instance usage limits as well; office/mobile networks may share an IP. Reading a policy does not enforce it automatically. Keep the public grant route closed until these checks are in place.
Call sessions.create using the separate backend key, e.g. {“application”:“public-site”,“origin”:“https://www.customer.com","allowWrites":false}. Optional context binds identity:{kind:“user”|“guest”,id}, optional authorized scope, conversation UUID and supplied data:{text,state}. Choose those references from trusted backend state. Store the returned conversation before returning the grant, then supply it on a later authorized call to resume. Never reuse another account’s scope/thread. A scope is not the same as a participant or a conversation. Existing users and external memory do not need to be migrated to Lina Live.
Return only {“session”:response.session} to the browser. Grants are short lived, single use and bind app/version/origin; provider and management credentials stay on servers. Optional entry:{channel:“embed”|“link”,source:“instagram”,campaign:“autumn”,link:“bio”} carries backend-asserted attribution labels, not click proof, identity or permissions. A link can target the customer’s embedded page; a separate hosted share room is deferred.
SDK 0.6.1 is publicly available as a standalone ES module and an independent Node 22+ starter. The pinned URLs below are published; downloading them does not activate hosted usage. No private repository access or npm package is required.
Pinned manifest: https://app.erfindergeist.ai/sdk/lina-live/0.6.1/manifest.json Starter: https://app.erfindergeist.ai/sdk/lina-live/0.6.1/starter.194960c9e861a2f2d876c9047bec75b2b3558c0aecc654ce027bb73ef294af02.tar.gz Starter SHA-256: 194960c9e861a2f2d876c9047bec75b2b3558c0aecc654ce027bb73ef294af02 Module: https://app.erfindergeist.ai/sdk/lina-live/0.6.1/lina-live.2e42241ae46975a94e2b7132852aad2a9e7bf3872976213e8630c2bef24e16b7.js Module SHA-256: 2e42241ae46975a94e2b7132852aad2a9e7bf3872976213e8630c2bef24e16b7
Download the starter, verify its SHA-256, extract it and read README.md. Hosted uses the stable bootstrap https://app.erfindergeist.ai/sdk/lina-live/hosted-v1.js by default. It reads the active runtime release once per page and imports that runtime’s immutable SDK, matching its Liveboard tool contract. Runtime updates reach Hosted embeds on the next page load. An already loaded page keeps its version; if the runtime changed before a new call, reload the page. Loading does not start a session/model. Implement auth.mjs using trusted visitor admission and thread persistence; the default denies every visitor. The starter has no npm dependencies or credentials. Optional manual pinning: run node download-sdk.mjs, verify the pinned module in public/assets, and select LINA_LIVE_SDK_MODE=pinned. Pinned embeds require coordinated manual SDK updates. Historical versioned assets remain available. Minimal embedding:
const { mountLinaLive } = await import('https://app.erfindergeist.ai/sdk/lina-live/hosted-v1.js');
const lina = await mountLinaLive(document.querySelector('#lina'), {
session: async () => {
const response = await fetch('/api/lina-live/session', {
method:'POST', headers:{'Content-Type':'application/json'}, body:'{}'
});
if (!response.ok) throw new Error('session_unavailable');
return (await response.json()).session;
}
});
document.querySelector('#start').addEventListener('click', () => lina.start());
// Stop: lina.stop(). Give lina-live a block height, e.g. 600px.HTTPS and microphone permission are required. Start directly from the user’s gesture; do not open voice on page load or link previews. The backend endpoint must be secured before exposing it publicly. The session callback must obtain a backend-authorized grant; a real session consumes hosted usage. Use memory subject/conversation operations for separately authorized history and deletion, and activity.list/stats/get for scoped monitoring. Archive events show speech, supplied Board scenes and authoritative tool receipts; confirmed writes, pending jobs and uncertain outcomes remain distinct.
Completion report
Report app ID, current revision, target release, registered tools/connections, trusted identity/memory design, backend and embed file changes, DNS record and readiness blockers. Separate configured state from verified effects. No automatic paid voice/model tests, business actions or deployment. A real voice test and publishing need the customer’s explicit instruction. Hosted usage requires an active entitlement, completed provisioning and available capacity; no customer key can bypass these checks.
Client configuration sources (checked 2026-10-20):