On your machine · Pinecall Docs

The whole runtime on one computer, with one command. Nothing is sent to a cloud, no account is needed, and every secret is drawn on the machine and stays there. This is how you develop an agent against a runtime of your own, or try Pinecall without signing up.

What you get#

pinecall-runtime local up brings up everything a call needs and keeps it on your machine:

what	what it does	where
Postgres 17, with pgvector and pg_textsearch	every call's log, the orgs, the keys, the knowledge bases	Docker, `127.0.0.1:55433`
Redis	how the parts of the runtime tell each other what just happened	Docker, `127.0.0.1:56380`
LiveKit, in development mode	the audio of a call, and a browser's way in	Docker, `ws://127.0.0.1:7880`
the gateway, with the console	every route the CLI and the console use, for the sandbox and production	your machine, `http://127.0.0.1:8080`
a worker	runs the calls of the sandbox, four at a time	your machine

Building an agent does not need any of this. Pinecall Cloud runs the runtime for you: start with the Quickstart. Come back here when you want the runtime on your own hardware, or want to read how it works from the inside.

Before you start#

Docker. Docker Desktop on macOS or Windows, Docker Engine with the compose plugin on Linux. docker compose version tells you it is there.
uv, which installs Python 3.12 and the runtime with one command: docs.astral.sh/uv.
Node 24 or later, for the pinecall CLI your agent is run with.
A key for each vendor a call runs on: a model, speech-to-text and a voice. Or models on your own hardware, and no vendor at all.

Run it#

Install the runtime#

Terminal

uv tool install "pinecall-runtime[voice]"
pinecall-runtime --version

0.1.9

[voice] brings every speech vendor's plugin, which the worker needs to run a call. The runtime needs Python 3.12 or later; uv tool install fetches one if the machine has none, which is why it is the command here and not pip install.

Bring it up#

Terminal

pinecall-runtime local up

local · Postgres :55433 · Redis :56380 · LiveKit :7880 · settings in /Users/you/.pinecall-runtime/local/env
console   http://127.0.0.1:8080/sandbox/
  the first time, in another terminal:
    pinecall-runtime local init --email you@example.com --person "Your Name"
gateway and a sandbox worker running; Ctrl-C stops them, the services stay (local down)
gateway | INFO ...
worker  | INFO ...

The first run is slow, and only the first: Docker builds the Postgres image and pulls Redis and LiveKit, a few minutes. Then the schema is created, the machine's secrets are drawn once into ~/.pinecall-runtime/local/env (readable by you alone), and the gateway and a worker start, their lines prefixed so you can tell them apart. Leave this terminal open: it is the runtime.

Make your org and your account#

In a second terminal:

Terminal

pinecall-runtime local init --email you@example.com --person "Your Name"

org default is already there
m_7ffbfedd3c8e  you@example.com  admin  runs this box
  http://127.0.0.1:8080/invitations/inv_…

  Open the link above to set a password. Then, in the directory of an agent:

    pinecall login http://127.0.0.1:8080
    pinecall link
    pinecall start

init finds the org default, which up made when it minted the worker's key, invites you as its admin and makes you an operator of this runtime. Open the invitation link and set your password: that is your sign-in to the console, and the pinecall login the lines under it name.

Name the vendors#

A new runtime has no vendors yet, and no call starts until it has. Write a row that names one for each stage, then give the org a key for each vendor. The key is read from standard input, so it never lands in a shell's history:

row.json

{
  "defaults": {
    "llm": {"vendor": "openai"},
    "stt": {"vendor": "deepgram"},
    "tts": {"vendor": "cartesia"}
  }
}

Terminal

eval "$(pinecall-runtime local env)"
pinecall-runtime providers seed row.json
printf %s "$OPENAI_API_KEY"   | pinecall-runtime orgs provider-key set default openai
printf %s "$DEEPGRAM_API_KEY" | pinecall-runtime orgs provider-key set default deepgram
printf %s "$CARTESIA_API_KEY" | pinecall-runtime orgs provider-key set default cartesia

local env prints the line that loads the local settings into your shell, which every other pinecall-runtime verb reads. A vendor named alone runs its plugin's default model; the complete row, with voices and the embedder knowledge bases and memory need, is providers.json. Every vendor and what the row holds: The vendors.

Point your agent at it#

In your agent's project folder, sign the CLI in to your runtime instead of Pinecall Cloud, and link the project:

Terminal

pinecall login http://127.0.0.1:8080
pinecall link
pinecall chat

gateway  http://127.0.0.1:8080

open this to sign in:
http://127.0.0.1:8080/cli?c=cli_…

waiting…
signed in to http://127.0.0.1:8080 as Your Name
▸ front-desk · PINECALL_KEY written to .env

From here on every pinecall command in that folder — chat, test, start, the console — uses your machine. The console is http://127.0.0.1:8080/sandbox/.

Stop it, start it again#

Ctrl-C in the first terminal stops the gateway and the worker; the services keep running in Docker, and pinecall-runtime local up starts the two again in a second. To stop the services too:

Terminal

pinecall-runtime local down              # the database and the secrets are kept
pinecall-runtime local down --volumes    # the database deleted, to start from nothing

A phone#

A phone call needs LiveKit's SIP bridge on the machine's own network, which Docker on macOS and Windows does not have, so a phone call to your machine works on Linux only:

Terminal

docker compose -f ~/.pinecall-runtime/local/compose.yaml --profile phone up -d sip

The carrier must reach your machine's port 5060 from the internet: a router that forwards it, or a virtual machine with a public address running the same command. On a Mac, the web and WhatsApp channels work; for the phone, a server does.

Developing the runtime itself#

From a checkout of pinecall/runtime, make local brings the services up with the same verb and make local-gateway and make local-worker run the two processes from the sources, so a change is served the moment you save it.

Next steps#

Your own GPUOpen models on your hardware as the runtime's vendors: no cloud in the call. The runtime CLIEvery pinecall-runtime verb: orgs, keys, routes, the fleet. On KubernetesThe runtime on a cluster, to serve calls.