Local Development

This guide explains how to run your Pika application locally for development and testing.

Prerequisites

Before running locally, make sure you have:

1. Node.js 22+ installed
2. pnpm package manager
3. AWS CLI useful for aws config/auth
4. AWS CDK installed globally

Install AWS CDK

pnpm install -g aws-cdk

Configure AWS CLI

aws configure

Enter your AWS access key, secret key, region, and output format.

Local Development Architecture

When running locally, Pika uses a hybrid approach:

Step-by-Step Local Setup

1. Configure Your Project

First, update your project configuration:

# Edit pika-config.ts to update project names (used for stack/resource names)
# This is recommended to avoid conflicts with other projects

Example configuration:

export const pikaConfig: PikaConfig = {
    pika: {
        projNameL: 'mycompany',
        projNameKebabCase: 'mycompany',
        projNameTitleCase: 'MyCompany',
        projNameCamel: 'mycompany',
        projNameHuman: 'My Company'
    },
    pikaChat: {
        projNameL: 'mycompanychat',
        projNameKebabCase: 'mycompany-chat',
        projNameTitleCase: 'MyCompanyChat',
        projNameCamel: 'myCompanyChat',
        projNameHuman: 'My Company Chat'
    }
};

2. Deploy Backend Services

Deploy Core Backend Service

# Navigate to the core Pika backend service
cd services/pika

# Build the service
pnpm build

# Deploy to AWS (make sure you are AWS local config is set to where you want to deploy)
pnpm run cdk:deploy

Deploy Sample Weather Service

# Navigate to the weather service
cd services/weather

# Build the service
pnpm build

# Deploy to AWS
pnpm run cdk:deploy

3. Start the Frontend

# Navigate to the chat application
cd apps/pika-chat

# Build the application
pnpm build

# Start the development server
pnpm run dev

4. Access Your Application

• Main Chat Interface: http://localhost:3000
• Weather Chat App: http://localhost:3000/chat/weather
• Sample Enterprise Site: http://localhost:3000/samples/enterprise-site

5. Start the Enterprise Site Front End

Make sure the main chat interface is running (see #4).

# Navigate to the chat application
cd apps/samples/enterprise-site

# Build the application
pnpm build

# Start the development server
pnpm run dev

Then access it with http://localhost:5173. Click the AI icon top right to show the pika chat front end embedded in an iframe.

What You Can Test Locally

1. Generic Chat Interface

The main chat interface at http://localhost:3000 provides:

• User authentication
• Chat history management
• File upload capabilities
• Custom component rendering

2. Weather Chat Application

Visit http://localhost:3000/chat/weather to test:

• Agent-based weather queries
• Tool orchestration
• Dynamic response generation
• Rich media rendering

3. Embedded Chat Mode

Visit http://localhost:5173 to test. The sample enterprise site demonstrates:

• Iframe integration
• Embedded chat functionality
• Cross-origin communication
• Responsive design

Development Workflow

Making Changes

Hot Reloading

The frontend development server supports hot reloading:

• Changes to Svelte components reload automatically
• TypeScript compilation happens in real-time
• CSS changes are applied immediately

Debugging

# Start with debugging enabled
pnpm run dev -- --debug

# Check browser console for errors
# Use browser dev tools for component inspection

Common Issues

1. Backend Services Not Deployed

Solution:

# Deploy the backend services first
cd services/pika && pnpm build && pnpm run cdk:deploy
cd services/weather && pnpm build && pnpm run cdk:deploy

2. AWS Credentials Not Configured

Solution:

3. Port Already in Use

Solution:

# Kill the process using port 3000
lsof -ti:3000 | xargs kill -9

4. Build Errors

Solution:

# Clean and reinstall dependencies
pnpm clean
pnpm install

# Rebuild the project
pnpm build

Development Tips

1. Use Environment Variables

Create a .env.local file for local development:

# .env.local
VITE_API_URL=http://localhost:3000
VITE_AUTH_PROVIDER=local
VITE_DEBUG=true

2. Monitor AWS Costs

3. Use AWS CloudWatch

Monitor your deployed services:

# View recent logs
aws logs tail /aws/lambda/mycompany-pika-service --follow

4. Test Different Scenarios

• Authentication flows: Test login/logout
• File uploads: Test document processing
• Custom components: Test your custom UI components
• Error handling: Test various error scenarios

Local Lambda Tool Development

For local Lambda tool development, you can redirect Lambda tools to run on local endpoints instead of calling deployed Lambda functions. This is useful when developing and testing custom Lambda tools.

Configuration

Create a custom-local-action-group-endpoints.json file in your project root:

{
    "oa_elasticsearch": "http://localhost:3002",
    "oa_account_data": "http://localhost:3002",
    "oa_order_data": "http://localhost:3002"
}

Set the environment variable to use this file:

export LOCAL_TOOLS="./custom-local-action-group-endpoints.json"

How It Works

• Maps tool IDs to local endpoint URLs where your Lambda functions are running locally
• When an agent tries to call a tool, it redirects to the local endpoint instead of AWS Lambda
• Useful for development and testing of Lambda tools without deploying to AWS
• Only affects Lambda tools (not MCP tools, which connect to remote MCP servers)

Next Steps

Now that you can run Pika locally:

1. Customize your application - Read the Customization Guide
2. Set up authentication - Follow the Authentication Setup
3. Deploy to production - Check out AWS Deployment
4. Learn about the sync system - Read Sync System

Getting Help

If you encounter issues:

1. Check the troubleshooting guide for common solutions
2. Review AWS CloudWatch logs for backend errors
3. Check browser console for frontend errors
4. Search existing issues on the GitHub repository
5. Create a new issue with detailed error information

Ready to customize your application? Check out the Customization Guide to start building your own features!