How Pinecall works
Your code, the gateway, the worker and the console: what runs where, and what a call is made of.
Every call on Pinecall involves four parts: your code, the gateway, a worker and the console. Knowing which part does what tells you where your code runs, where a call is recorded, and what you can change without a deploy.
How it works#
Your code#
Your agent is a process that holds one socket open to the gateway. pinecall start runs it on
your machine or your own server; pinecall deploy uploads the project and Pinecall runs it in an
isolated container. Either way the process opens no port: it connects out, so it needs no public
address.
When a call opens, your process sends the prompt and the tools the model may use. When the model calls a tool, the call crosses the socket, the method runs in your process against your own systems, and the result goes back. When a tool changes a field, the view is rendered again.
Your code never touches audio, rooms or vendors. Which voice, which model and which language the agent uses are settings of the agent, kept by the gateway and changed without a deploy.
The gateway#
The gateway is the control plane, at cloud.pinecall.io:
- The API. Every verb of the CLI and every screen of the console is a request to the gateway. Each request acts in one org, taken from its key.
- The call's log. Every fact of a call (what was said, what the model read, each tool call and its answer, each latency) is an entry appended to that call's log in Postgres. Entries are never edited or deleted, except by an erasure. At hang-up the log is sealed: the summary, the price, what memory keeps and the judges' verdicts are written last.
- Written calls. A chat or a WhatsApp conversation runs on the gateway itself, with no audio.
- The console. The gateway serves the console: production's at the root, the sandbox's under
/sandbox/.
The worker#
A spoken call runs on a worker: a LiveKit agent that joins the call's room and runs three stages, the ears (speech to text), the model and the voice (text to speech). A small local model decides when the caller has finished their turn. Searches in your knowledge base and in memory start while the caller is still speaking, so their results are usually ready when the turn ends.
Workers come and go with the number of live calls. The sandbox and production each have a fleet of their own, so a sandbox call never runs on a production worker.
How a call travels#
- A caller dials a number your org owns, or presses the widget on a web page. The phone call arrives from the carrier over SIP. Both land in a LiveKit room.
- A worker of the sandbox's or production's fleet takes the room and asks the gateway to open the call. The gateway finds the process holding the agent and writes the call's first entry.
- Each turn, the worker hears the caller, asks the model and speaks the answer. It writes every turn, tool call and measure to the log.
- A tool call goes from the worker to the gateway, to your process, and back.
- At hang-up the worker asks the gateway to seal the log.
Sandbox and production#
Every org has a sandbox and a production on the same gateway, at the same address, with the same login.
| sandbox | production | |
|---|---|---|
| what it is for | building and testing | the calls your customers make |
| who holds the agent | each developer their own copy | the org: a deployed app or a server token |
| the agent's settings | yours, or the team's with --team |
one set, written with --prod |
| the console | cloud.pinecall.io/sandbox/ |
cloud.pinecall.io/ |
| from the CLI | every verb, by default | any verb with --prod |
Calls, bases, memory, settings and hosted apps all belong to the sandbox or to production. Nothing you do in the sandbox reaches production.
A person's key opens both the sandbox and production. Production accepts a person's
--prodonly while an admin has turned their production access on.
Pinecall Cloud or your own#
Pinecall Cloud runs the open-source Pinecall runtime for you, on Kubernetes. You can run the same runtime yourself: see Self-hosting. Your agent does not change: only the gateway's address does.