Local Development

ccp dev starts a local HTTP server running your function in a real V8 isolate — the same runtime used in production.

Start the Dev Server

ccp dev
# ◼ Dev Server started!
# › http://127.0.0.1:1234

The server watches your project root recursively and hot-reloads on any change. Common build/output directories are ignored: node_modules, .cluster, .git, dist, build, .next, .turbo, and target.

Options

Flag	Default	Description
`--port <port>`	`1234`	Port to listen on
`--hostname <host>`	`127.0.0.1` (TTY) / `0.0.0.0` (headless)	Hostname to bind to
`--env <path>`	`.env`	Path to a custom env file
`--public-dir <path>`	—	Serve static assets from this directory
`--client <path>`	—	Include a client-side script
`--allow-code-generation`	`false`	Allow `eval()` and `new Function()`
`--prod` / `--production`	`false`	Set `process.env.NODE_ENV` to `"production"`
`--headless`	auto	Suppress styled banners; emit one-line `[dev] ...` logs. Auto-enabled when stdout isn't a TTY

The hostname default is context-dependent: interactive shells bind to 127.0.0.1, headless / non-TTY runs (and remote dev VMs) bind to 0.0.0.0 so the dev server is reachable from outside the container. Pass --hostname explicitly to override.

Environment Variables

CCP automatically loads a .env file from the project root if one exists:

# .env
API_KEY=sk-abc123
DEBUG=true

ccp dev
# Automatically loaded .env file...
# ◼ Dev Server started!

Point to a different env file with --env:

ccp dev --env .env.staging

Variables are available in your handler via process.env:

export function handler(request: Request): Response {
  const key = process.env.API_KEY;
  return new Response(`Key: ${key}`);
}

Static Assets

For static sites, pass the public directory:

ccp dev --public-dir public

Static files are served directly. Non-matching paths fall through to your handler. See Static Sites for more details.

Logs

console.log(), console.error(), and console.warn() output directly to your terminal with level prefixes:

INFO Hello from the handler
ERROR Something went wrong
WARN Deprecated API usage

Timeouts

The local dev server applies the same timeouts as production:

Tick timeout: 500ms per I/O tick
Total timeout: 30 seconds per request

Headless Mode

For CI, dev VMs, and AI agents, run with CCP_HEADLESS=1 (or pass --headless). The server skips styled banners and screen clears, emits terse [dev] ... lines suitable for log capture, and binds to 0.0.0.0 so a parent process can reach it.

CCP_HEADLESS=1 ccp dev --port 3000
# [dev] listening on http://0.0.0.0:3000

See Headless Mode for the full reference.

Local Development

On this page