Quick Start

Get up and running with Pika Platform in 15 minutes. This guide takes you from zero to your first working chat application as quickly as possible.

Prerequisites

Before you begin, verify you have these installed:

# Check Node.js version (need 22+)
node --version

# Check if pnpm is installed
pnpm --version

# Check if Git is installed
git --version

Need to Install?

If any of these commands fail, follow the detailed installation guide to set up your system.

Quick Install Commands:

• pnpm: npm install -g pnpm or curl -fsSL https://get.pnpm.io/install.sh | sh -
• Node.js: Download from nodejs.org or use your package manager

Step 1: Install Pika CLI

Install the Pika command-line tool globally:

pnpm install -g pika-app

Verify the installation:

pika --version

Step 2: Create Your Application

Create a new Pika application with a single command:

pika create-app my-chat-app

This command will:

• Clone the Pika framework repository
• Set up the complete project structure
• Install all dependencies
• Configure the project for your use case

What Gets Created

This creates a generic framework for defining multiple chat applications and agents. You typically only need one Pika installation per AWS account. The framework provides the infrastructure to host and manage multiple chat apps.

The installation process takes 2-5 minutes depending on your internet connection.

Step 3: Navigate to Your Project

cd my-chat-app

Take a moment to explore the structure:

my-chat-app/
├── apps/
│   ├── pika-chat/          # Main chat frontend
│   └── samples/            # Sample applications
├── services/
│   ├── pika/              # Core backend service
│   └── samples/           # Sample services (like weather)
├── packages/              # Shared packages
└── pika-config.ts         # Project configuration

Step 4: Configure Your Project

Update the project names in pika-config.ts to customize your installation:

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'
    }
};

Why Configure Names?

These names are used for AWS stack and resource names. Customizing them helps avoid conflicts with other projects and makes your resources easier to identify in the AWS console.

Step 5: Start Development Mode

Start the development server:

pnpm dev

This command:

• Builds the project
• Starts the frontend development server
• Opens your browser to http://localhost:3000

First Run Takes Longer

The first build can take 2-3 minutes as TypeScript compiles all packages. Subsequent starts are much faster thanks to caching.

Step 6: Explore Your Application

Your application is now running at http://localhost:3000!

What You Can Do:

Main Chat Interface

The home page shows available chat applications. With the default setup, you'll see the Weather chat app.

Weather Chat App

Visit http://localhost:3000/chat/weather to interact with the sample weather agent. Try asking "What's the weather in Seattle?"

Sample Enterprise Site

The sample at http://localhost:5173 demonstrates how to embed Pika chat into an existing website using an iframe.

Understanding the Default Setup

Mock Authentication

Development Only

By default, Pika uses a mock authentication provider that automatically logs you in as a test user. This is for development only and provides no real security. Before deploying to production, you must implement a custom authentication provider.

The mock setup:

• Hardcodes a single test user
• No password required
• Automatically authenticates anyone who visits

See the Authentication Guide to implement real authentication.

Sample Weather Service

The weather service demonstrates:

• How to define a chat app
• How to create an agent with tools
• How agents use tools to answer questions
• How responses are rendered in the UI

This is your template for creating your own chat apps and agents.

Next Steps

Now that you have Pika running, you have several options:

Option 1: Build Your First Custom Agent

Follow the Hello World Tutorial to create your first custom agent from scratch.

Option 2: Deploy to AWS

To test with real AWS services:

1. Configure AWS CLI: aws configure
2. Deploy backend: cd services/pika && pnpm build && pnpm run cdk:deploy
3. Deploy sample: cd services/samples/weather && pnpm build && pnpm run cdk:deploy

See Local Development Guide for details.

Option 3: Learn More About Pika

• Why Pika? - Understand the platform's design philosophy
• Capabilities - Explore what you can build
• Concepts - Learn how Pika works under the hood

Option 4: Customize Your Installation

• Authentication - Implement real authentication
• Customization - Customize the UI and behavior
• Access Control - Configure who can access what

Common Quick Start Issues

Port 3000 Already in Use

If port 3000 is already in use:

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

# Or use a different port
pnpm run dev -- --port 3001

Dependencies Fail to Install

If pnpm install fails:

# Clear pnpm cache and retry
pnpm store prune
pnpm install --force

TypeScript Errors During Build

If you see TypeScript compilation errors:

# Clean and rebuild
pnpm clean
pnpm install
pnpm build

Getting Help

If you encounter issues:

• Check the detailed installation guide for system-specific instructions
• Review troubleshooting tips for common problems
• Visit the GitHub repository for issues and discussions

Summary

In this quick start, you:

1. Installed the Pika CLI
2. Created a new Pika application
3. Configured your project
4. Started the development server
5. Explored the default weather chat app

You now have a working Pika installation ready for customization!

Ready to build your own agent? Head to the Hello World Tutorial to create your first custom chat app.