vk dev

Usage

vk dev [options]

Options

Option	Description	Default
-s, --stage <stage>	Stage name	dev
-p, --port <port>	Server port	3000
--no-watch	Disable file watching / hot reload	watch enabled

Description

Starts a fully local development server. No AWS credentials or cloud resources required.

• Discovers routes from your routesDir and serves them via HTTP
• Starts Docker Compose services for infrastructure (Postgres, Redis, MinIO)
• Converts HTTP requests to Lambda-compatible APIGatewayProxyEventV2 events
• Loads TypeScript handlers at runtime (no build step needed)

Examples

# Start with defaults (port 3000)
vk dev

# Custom port
vk dev --port 8080

# Custom stage
vk dev --stage my-feature

Requirements

• Docker running (for database, cache, and storage services)
• VentureKit project with vk.config.ts
• Dependencies installed (npm install)

No AWS credentials are needed for local development.

How It Works

1. Loads vk.config.ts using runtime TypeScript transpilation (via jiti)
2. Registers your project’s infrastructure intents in the shared registry (~/.vk/projects.json)
3. Generates a shared docker-compose.yml at ~/.vk/ (one Postgres, one Redis, one MinIO for all projects)
4. Starts Docker services automatically if not already running
5. Discovers routes, functions, queues, and crons from your project
6. Starts a local queue processor and cron scheduler
7. Serves requests locally, converting them to Lambda event format
8. Route handlers are loaded on-demand — edit a file and the next request uses the new code

Local Services

All services run at standard ports. Multiple projects share the same containers — databases and buckets are isolated by project-prefixed names.

Infrastructure Intent	Local Service	Port
databases (postgres)	PostgreSQL 16	5432
caches	Redis 7	6379
queues	Redis 7 (shared with caches)	6379
storage	MinIO	9000 (API), 9001 (Console)

Dev Tools (via vk open)

Tool	Port	Command
Database viewer	8081	vk open db
Storage browser	9001	vk open storage
Queue & cache monitor	5540	vk open queues
Cron status	—	vk open crons

Function Invocation

invoke() from @venturekit/runtime works locally out of the box. When VENTURE_LOCAL=true, invoke calls are routed to the local dev server via HTTP instead of AWS Lambda.

• Route invocation: invoke('users/list') calls GET http://localhost:3000/users
• Function invocation: invoke({ function: 'process-orders' }) calls POST http://localhost:3000/_dev/invoke/process-orders

Local Queues

Queue handlers in src/queues/ are discovered and processed automatically. The local queue processor:

• Polls for new messages every 500ms
• Retries failed messages up to 3 times with exponential backoff
• Moves failed messages to a local dead-letter queue
• Delivers messages in SQS-compatible event format

Enqueue messages via HTTP: POST /_dev/queue/{name} with a JSON body.

View queue stats: GET /_dev/queues

Local Cron

Cron handlers in src/crons/ run on a timer during local development. By default, each cron runs every 60 seconds. The cron scheduler delivers EventBridge-compatible scheduled events.

View cron status: GET /_dev/crons

Dev Endpoints

Endpoint	Method	Description
/_dev/invoke/{name}	POST	Invoke a standalone function
/_dev/invoke/queue/{name}	POST	Invoke a queue handler directly
/_dev/invoke/cron/{name}	POST	Invoke a cron handler directly
/_dev/queue/{name}	POST	Enqueue a message
/_dev/queues	GET	Queue stats and DLQ
/_dev/crons	GET	Cron job status
/_dev/functions	GET	List all discovered handlers