CodePuppet

Self-Hosted AI Coding Agent Platform

CodePuppet is a self-hosted platform for running AI coding agents against your own codebase, using your own LLM API keys — the backend only ever stores and uses credentials a user has explicitly saved, never a shared key. It's split into three pieces that share a common backend contract: an Express + Prisma API that owns agent sessions and encrypted credentials, a local CLI that executes file/process/git tools on the developer's own machine, and a Next.js web app for account sign-up and approving CLI device-login requests.

Designed a provider-agnostic streaming layer with adapters for 3 LLM providers (OpenAI, Google, Anthropic) normalised behind a single event contract, forwarding tokens to clients over Server-Sent Events in under 100 ms while persisting each turn atomically in 1 Prisma transaction with per-turn token accounting.
Secured multi-tenant credentials with AES-256-GCM encryption and per-user HKDF-SHA256 derived keys bound to (user, provider, label) as authenticated data, and added an OAuth-style device-authorization login flow for CLI sessions.
Eliminated a remote code execution path by resolving tool-execution category server-side across 5 tool categories rather than trusting client input; validated with 40+ Jest tests.

What It Does

Bring-your-own-key: each user's OpenAI, Anthropic, or Google API key is encrypted per-user on the backend, never shared globally.
Streams agent responses token-by-token over Server-Sent Events for a chosen provider/model.
Lets the model call tools mid-conversation — file/process/git tools run locally via the CLI, while a small set of "backend" tools run server-side, with results fed back into the same conversation.
OAuth-style device-authorization login for the CLI — type a short code and approve it from the browser, no pasting long tokens into a terminal.

Architecture

A Turborepo/Bun monorepo: apps/api (Express + Prisma/Postgres) owns users, encrypted credentials and agent sessions; apps/cli is a local Node CLI that executes tools in the developer's own workspace; apps/web is a Next.js app for sign-in and device-login approval. Six shared workspace packages sit underneath — database, protocol (Zod schemas), provider-registry (one streaming adapter per LLM provider), tool-registry, harness (the CLI's local API client/config store), and a shared shadcn/ui component library.

Services

apps/apiExpress + Prisma/Postgres backend — owns users, encrypted provider credentials, and the full lifecycle of an agent session.

apps/cliNode CLI (code-puppet) that developers install locally, log in from, and run agent sessions from inside a real workspace, executing tools on their own machine.

apps/webNext.js app for account sign-up/sign-in and approving CLI device-login requests in the browser.

Tech Stack

Language & Runtime

TypeScript

Bun 1.3

Node.js 20+

Monorepo Tooling

Turborepo

Bun workspaces

Backend

Express 4

PostgreSQL

Prisma ORM

Auth

better-auth

Device-authorization flow

Validation

Zod v4

LLM Providers

OpenAI SDK

Anthropic SDK

Google GenAI SDK

Frontend

Next.js 16

React 19

Tailwind CSS v4

shadcn/ui

CLI

Commander

Inquirer

Axios

Chalk

Testing & Infra

Jest

Docker Compose

Languages

TypeScript94%

CSS2%

JavaScript2%

Dockerfile1%

Getting Started

1Install dependencies
```
bun install
```

2Start Postgres

docker compose -f infra/docker-compose.database.yml up -d

3Configure environment variables

cp apps/api/.env.example apps/api/.env
cp apps/cli/.env.example apps/cli/.env

4Run database migrations and seed the model catalog
```
bun run db:migrate:dev
bun run db:seed
```
5Run everything (API, web, CLI watch builds)
```
bun run dev
```