Installation

Clone and install

teaspill ships as a pnpm workspace — the platform, the SDKs, the CLI, and the reference deployment all live in one repository.

git clone https://github.com/everynow-dev/teaspill.git
cd teaspill
pnpm install

Build the packages and service bundles

The gateway and the reference deployment run in Docker from self-contained bundles, built once up front:

pnpm -r build
pnpm --filter @teaspill/gateway bundle
pnpm --filter @teaspill/reference-deployment bundle

Configure the environment

Every variable has a working default — .env only needs the dev API key, which lets services (and you) register and issue commands through the gateway:

cp .env.example .env
echo 'GATEWAY_BOOTSTRAP_API_KEY=tsp_local_dev_only' >> .env
echo 'TEASPILL_API_KEY=tsp_local_dev_only' >> .env
# optional — enables the demo agents:
echo 'ANTHROPIC_API_KEY=sk-ant-...' >> .env

The bootstrap key is a development convenience: it works before any real key exists. For anything beyond local dev, mint real keys with teaspill keys create and drop the bootstrap — the Auth & API keys guide covers both.

Boot the stack

The previous step built the teaspill CLI into the workspace. Alias it once per shell and point it at your dev key now — the richer boot loop below and the checks in the next step both use it:

alias teaspill="node $PWD/packages/cli/dist/index.js"
export TEASPILL_API_KEY=tsp_local_dev_only

The base compose file runs the infrastructure; the overlay adds the reference deployment's two services on top:

docker compose -f docker-compose.yml -f docker-compose.overlay.yml up -d --build

The first boot builds three images and pulls four, so it takes a few minutes. Prefer a richer dev loop? teaspill dev wraps the same boot with a gateway health wait, deployment registration with retries, and tailed logs:

export COMPOSE_FILE=docker-compose.yml:docker-compose.overlay.yml
teaspill dev --deployment http://agent-loop:9080 --deployment http://executor:9081

Check that it's up

Well done — the platform should now be running. The gateway answers on port 8787, and the teaspill alias you set above lists what's running:

curl http://localhost:8787/health
# {"ok":true}

teaspill agents ls

An empty list is the correct answer on a fresh stack — nothing has been spawned yet. If both commands succeed, everything is wired. (The CLI reference covers every command and flag.)