Install Glove Foundry

Let the setup wizard guide you from an empty folder to your first agent run. The generated project is ordinary TypeScript that you own.

Requirements

• Node.js 22+; use 22.13+ for SQLite memory
• pnpm, npm, yarn, or bun
• No API key needed for the guided demo; the minimal starter and live runs need a provider key

1. Follow the setup wizard

npx glove-foundry init

The Clack-powered terminal UI guides you through these choices. Use arrow keys to move, Enter to select, and Ctrl+C to cancel.

1. Directory: a new folder, or your existing Next.js app.
2. Project: standalone runtime and inspector, or colocated Next.js integration.
3. Starter: guided travel concierge (keyless demo) or a minimal agent and tool.
4. Package manager: existing lockfiles are detected; choose pnpm, npm, yarn, or bun.
5. Installation: enabled by default. After confirmation, Foundry runs the selected package manager's install command in your new project. Opt out to install later.
6. Review: confirm the plan before project files are written.

Cancellation before confirmation creates no files. Existing app files are never silently overwritten. If dependency installation fails, the generated project remains available and the CLI prints retry steps. No secrets are requested by the wizard.

Repeatable setup without prompts

npx glove-foundry init my-agent-system --template travel-concierge --package-manager pnpm --yes --install
cd my-agent-system

Once glove-foundry is installed in a project, the equivalent framework command is glove foundry. The explicit package form above also works before a local glove binary exists.

2. Configure a provider when you are ready

The guided example works before this step. Copy .env.example to .env.local, add your key yourself, and restart the dev server. The minimal starter requires this key. Demo calendars and messengers do not become real integrations just because a model key is present.

OPENROUTER_API_KEY=your_key_here
# optional
OPENROUTER_MODEL=openai/gpt-4.1-mini

3. Run

pnpm dev

  Glove Foundry

  Local:    http://127.0.0.1:4141
  Agents:   1
  Runtime:  ready
  Types:    .foundry/routes.d.ts

Development mode discovers agents/, generates route types, starts the Effect runtime and HTTP API, opens the inspection surface, and restarts when agent or configuration files change.

Open http://127.0.0.1:4141, choose Start a run, select concierge, and ask “Find a flight to Nairobi.” Open the run to follow its tool calls and result. Edit agents/concierge/agent.ts and save to try a change.

What was created

The guided travel-concierge template contains one example of every convention:

agents/concierge/
  agent.ts                                 the definition — start here
  composition.ts                           composeAgent(...): the installable catalogue
  flights.ts                               find_flights: an always-on tool
  tools/convert-currency.tool.ts           an installable shared tool (defineSharedTool)
  apps/calendar.app.ts                     an installable application (defineApp)
  instances.ts                             the seeded concierge-demo instance and its binding
  transmissions/messaging.transmission.ts  a chat transport (defineTransmission)
  events/message-received.event.ts         inbound event
  events/message-sent.event.ts             outbound event
  predicates/mentions-trip.predicate.ts    inbound match rule
  actions/reply.action.ts                  playbook action
  memory/traveller.memory.ts               memory profile (defineMemory)
  layers/trip-context.layer.ts             native Glove setup (defineLayer)
  subscribers/usage.subscriber.ts          observer (defineSubscriber)
  schedules/trip-countdown.ts              a schedule value (imported, not discovered)
  workbench.ts                             VFS + JavaScript REPL
  topology.ts                              accounts and routes (runtime data)
foundry.application.ts                     file data adapter, accounts, routes, bindings
foundry.config.ts                          port and execution policy
lib/demo-model.ts                          keyless demo model
lib/file-store.ts, lib/file-context.ts     durable transcripts and traveller memory
.data/                                     runtime state on disk (git-ignored)
src/client.ts                              a runnable typed client
.foundry/routes.d.ts                       generated — do not edit

The minimal template is agents/assistant/agent.ts with one always-on tool, lib/file-store.ts, and the two root files. Project structure explains every convention.

4. Create an instance and send a message

import { createFoundryClient } from "glove-foundry/client";
import type { FoundryRoutes } from "../.foundry/routes.js";

const foundry = createFoundryClient<FoundryRoutes>({ baseUrl: "http://127.0.0.1:4141" });

// "concierge" is checked against the files in agents/.
const agent = await foundry.agent("concierge").create({
  workspaceId: "demo",
  context: { budgetUsd: 2_500 },
});
const conversation = await foundry.createConversation(agent.id);
const run = await foundry.send(agent.id, conversation.id, "I want to fly from Lisbon to Nairobi in April.");

console.log(`run ${run.id} -> http://127.0.0.1:4141/runs/${run.id}`);
const completed = await run.wait();
console.log(completed.output);

Run it with npx tsx src/client.ts while pnpm dev is running. The same calls are available over plain HTTP and through the OpenAI-compatible API.

CLI command reference

# Interactive setup
npx glove-foundry init

# Join an existing Next.js app
npx glove-foundry init . --target nextjs

# Explicit CI setup; no prompts, no dependency install unless requested
npx glove-foundry init service --template minimal --package-manager npm --yes
npx glove-foundry init service --yes --install

# Inside a project
glove foundry dev
glove foundry dev --port 4142 --no-watch
glove foundry start --root ./service
glove foundry help

Runtime options are --root, --port, --host, and --no-watch. A non-loopback host requires an application-owned request authorization adapter. Next.js projects use foundry:dev and foundry:start, leaving the app’s existing scripts intact.

5. Verify and prepare for deployment

pnpm typecheck
pnpm lint

State lives on disk from the first run. Each run executes in its own process, so both starters keep instances, conversations, transcripts (and in the concierge, traveller memory and VFS files) under .data/. They survive the restart pnpm dev performs on every save; delete .data/ to start fresh. These are single-host adapters — see Persistence before deploying.

Starter storage is disposable. Persist Foundry instance/activation data, Glove conversation history, structured memory, and VFS files with their respective adapters. A durable runtime-data adapter alone does not persist all of them. Read Persistence before retaining user work, and Deploy & security before exposing the server.

Next: the tutorial builds a multi-tenant support agent with installed tools, schedules, approvals and an OpenAI SDK client.

If setup fails, check your Node version and package-manager installation. Choose another port if 4141 is occupied. For provider errors, inspect the failed run’s events. Restart after changing environment values.

For contributors working in the Glove repository

pnpm --filter glove-foundry-example typecheck
pnpm --filter glove-foundry-example verify:architecture
pnpm --filter glove-foundry-example verify