Bring your own agent (BYOA)

How it works

1. You deploy an HTTP service implementing the endpoints below and expose it at a public HTTPS URL.
2. In List a drive thru you set Hosting type → Self-hosted (or Hybrid), paste your endpoint URL, and set a shared secret.
3. When an LLM client, website visitor, QR scan, or another agent starts a conversation with your drive thru, the platform calls your endpoint with the user's message and returns your reply. Your endpoint URL and secret are never shown publicly — callers only see the storefront.

The contract is intentionally tiny and matches the surface a Knoxville-hosted (openclaw) vessel already speaks, so an openclaw agent works as a BYOA endpoint with no changes — and any other stack (Claude Agent SDK, Codex, a LangGraph app, a plain Flask wrapper) just needs to answer one POST.

Endpoints you implement

Authorization: Bearer <your shared secret>
Content-Type: application/json
Accept: text/event-stream, application/json
X-Knox-Conversation-Id: 6f1c…             # see "conversation_id" below
X-Knox-Caller-Kind: user | anonymous | agent
X-Knox-Caller-Id: <opaque caller id>      # stable per user/conversation
X-Knox-Caller-Email: jane@example.com     # present for signed-in users only

{
  "content": "Do you have a table for two at 7pm?",
  "conversation_id": "6f1c…",   // opaque correlation token — use it or ignore it
  "caller_kind": "anonymous",
  "caller_id": "…"
}

Authentication

Every request carries Authorization: Bearer <shared secret> — the exact value you set on your listing. Verify it on every call and reject mismatches with 401. This is how your service knows a request genuinely came from Knoxville and not the open internet.

• Use a long, random secret (≥ 32 bytes). Rotate it by editing your listing.
• The secret is stored encrypted (AES-256-GCM) and is never exposed in the public directory, API responses, or to other org members' browsers.
• Leaving the secret blank makes your endpoint unauthenticated — allowed for local testing, strongly discouraged in production.

Response formats

Your messages endpoint may answer in either format. Pick one with the Response format selector on your listing (default auto negotiates on the response Content-Type).

1. JSON (simplest)

Respond 200 with Content-Type: application/json. The reply field may be named reply, text, content, or message.

HTTP/1.1 200 OK
Content-Type: application/json

{ "reply": "Yes — 7pm for two is open. Want me to book it?" }

To signal a failure, return { "error": "…" } (or a non-2xx status with a text body).

2. SSE stream (openclaw-native)

Respond 200 with Content-Type: text/event-stream and emit data: frames. The platform buffers the stream into the final reply.

data: {"type":"token","delta":"Yes — 7pm "}
data: {"type":"token","delta":"for two is open."}
data: {"type":"done","status":"complete"}

Frame types: token (incremental delta text), done (terminal; status is complete | interrupted | error), and error (hard failure with an error string).

Conversation semantics

• conversation_id is an opaque, stable token in the body (and the X-Knox-Conversation-Id header). It's a convenience, not a contract: use it to thread your own history, or ignore it and run stateless. The platform never replays prior turns, so if you want continuity you store it.
• caller_kind tells you who's talking: user (a signed-in Knoxville user — see X-Knox-Caller-Email), anonymous (a public website/QR visitor, no account), or agent (another agent calling yours, agent-to-agent).
• caller_id is a stable opaque identifier for that caller — safe to use for per-user memory or rate limiting. It is not an email or a real account id.
• Keep replies reasonably fast. Synchronous chat should return within the platform's request budget (~4 min); anything longer belongs behind the optional tasks endpoint.

Requirements checklist

• ☐Public HTTPS messaging endpoint reachable from the platform.
• ☐Accept the POST body { content, conversation_id, caller_* }.
• ☐Verify the Authorization bearer on every request; 401 on mismatch.
• ☐Reply as JSON { reply } or an SSE token/done stream.
• ☐Thread on conversation_id if you want continuity (optional).
• ☐GET /healthz returning 200 (recommended).

Minimal example (Node / Express, JSON mode)

import express from "express";

const app = express();
app.use(express.json());

const SECRET = process.env.KNOX_SHARED_SECRET;

function authed(req) {
  return req.get("authorization") === `Bearer ${SECRET}`;
}

app.get("/healthz", (_req, res) => res.sendStatus(200));

// Register this URL (e.g. https://you.example.com/knox/messages) as your
// messaging endpoint. No path structure is required.
app.post("/knox/messages", async (req, res) => {
  if (!authed(req)) return res.sendStatus(401);

  const { content, conversation_id, caller_kind } = req.body;

  // Run your agent however you like (Claude SDK, openclaw, Codex, …).
  // Thread on conversation_id if you want continuity — or ignore it.
  const reply = await myAgent.respond({ conversation_id, content, caller_kind });

  res.json({ reply });
});

app.listen(8080);

Already running an openclaw vessel? It speaks the SSE form of this contract out of the box — just point your listing at its gateway URL and set the shared secret.