Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Evincere/klisk/llms.txt

Use this file to discover all available pages before exploring further.

​
Usage

klisk deploy [options]
klisk deploy init [project]

​
Description

Deploy your Klisk project to Google Cloud Run with automated setup for Docker, dependencies, and GCP configuration.

​
Subcommands

​
klisk deploy init

Generate deployment files (Dockerfile, .dockerignore, requirements.txt). 
klisk deploy init [project]

​
Arguments

​
project
string
default:"."
Project name or path to initialize for deployment.

​
klisk deploy

Deploy to Google Cloud Run. 
klisk deploy [options]

​
Options

​
--path
string
Project name or path. Use -p as shorthand.Default: Current directory (.)
​
--service
string
Cloud Run service name. Use -s as shorthand.Default: Slugified project name from klisk.config.yaml
​
--region
string
GCP region for deployment. Use -r as shorthand.Default: Your gcloud default region (if not set, you’ll be prompted)
​
--project
string
GCP project ID.Default: Your gcloud default project (from gcloud config get-value project)

​
Deployment Workflow

​
1. Initialize Deployment Files

klisk deploy init
This generates: Dockerfile: 
FROM python:3.12-slim
WORKDIR /app
COPY *.whl .
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8080
CMD ["klisk", "serve", ".", "--port", "8080"]
.dockerignore: 
.venv/
__pycache__/
*.pyc
.git/
.env
.env.*
node_modules/
.mypy_cache/
.pytest_cache/
requirements.txt: 
./klisk-<version>.whl           # Standard agents
./klisk-<version>.whl[litellm]  # If using non-OpenAI providers
The command also:
  • Builds a wheel file from the Klisk package
  • Detects if you’re using LiteLLM models
  • Creates .env from .env.example if needed

​
2. Configure API Keys

Ensure .env contains real API keys (not placeholders): 
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
The deploy command will warn you if keys appear to be placeholders.

​
3. Deploy to Cloud Run

klisk deploy
The deployment process:
  1. Checks prerequisites:
    • gcloud CLI installed
    • Authenticated with Google Cloud
    • GCP project configured
    • Billing enabled
    • Required APIs enabled (Cloud Run, Cloud Build, Artifact Registry)
    • Proper IAM permissions
  2. Builds container using Cloud Build
  3. Deploys to Cloud Run:
    • Copies environment variables from .env
    • Configures service as publicly accessible
    • Returns the deployed URL

​
Prerequisites

​
Install gcloud CLI

macOS: 
brew install google-cloud-sdk
Other platforms: https://cloud.google.com/sdk/docs/install

​
Authenticate

gcloud auth login
Follow the browser prompt to sign in.

​
Set GCP Project

If you have an existing project: 
gcloud config set project YOUR_PROJECT_ID
If you need to create one:
  1. Go to https://console.cloud.google.com
  2. Create a new project
  3. Run: gcloud config set project YOUR_PROJECT_ID

​
Enable Billing

Cloud Run requires billing to be enabled. Google Cloud offers $300 in free credits for new accounts. Enable billing at: https://console.cloud.google.com/billing?project=YOUR_PROJECT_ID

​
Required APIs

The deploy command automatically enables:
  • run.googleapis.com - Cloud Run
  • cloudbuild.googleapis.com - Cloud Build
  • artifactregistry.googleapis.com - Artifact Registry
You’ll be prompted to enable them if they’re not already active.

​
Examples

​
Full Deployment Flow

# 1. Initialize deployment files
klisk deploy init

# 2. Verify .env has real API keys
cat .env

# 3. Deploy to Cloud Run
klisk deploy
Output: 
  Checking prerequisites...

  Deploying to Cloud Run...
  Service:  my-agent
  Project:  my-gcp-project

  Running: gcloud run deploy my-agent --source ...

  [Cloud Build output...]

  Deployed successfully!

  Chat:   https://my-agent-abc123-uc.a.run.app
  API:    https://my-agent-abc123-uc.a.run.app/api/chat
  Health: https://my-agent-abc123-uc.a.run.app/health

  Embed widget:
  <script src="https://my-agent-abc123-uc.a.run.app/widget.js"></script>

​
Deploy with Custom Service Name

klisk deploy --service customer-support-bot

​
Deploy to Specific Region

klisk deploy --region us-central1

​
Deploy Different Project

klisk deploy --path ~/klisk/my-other-agent

​
Deploy to Different GCP Project

klisk deploy --project my-other-gcp-project

​
Service Name Slugification

Cloud Run service names must:
  • Be lowercase
  • Contain only letters, numbers, and hyphens
  • Start with a letter
  • Be 63 characters or fewer
The deploy command automatically converts your project name: 
"My Cool Agent!" → "my-cool-agent"
"Agent_2024" → "agent-2024"

​
Environment Variables

Environment variables from .env are automatically set on the Cloud Run service. Placeholder values are skipped: Deployed: 
OPENAI_API_KEY=sk-proj-...
LOG_LEVEL=info
Skipped (placeholders): 
API_KEY=your-key-here
TOKEN=changeme
SECRET=xxx

​
LiteLLM Detection

The deploy command scans your Python files for LiteLLM model providers: 
# Detected as LiteLLM (non-OpenAI)
Agent(model="anthropic/claude-3-5-sonnet")
Agent(model="gemini/gemini-pro")

# Standard OpenAI
Agent(model="gpt-5.2")
Agent(model="openai/gpt-4o")
If LiteLLM providers are found, requirements.txt includes klisk[litellm].

​
IAM Permissions

The deploy command ensures the default Compute Engine service account has:
  • roles/storage.objectAdmin - Access Cloud Storage
  • roles/logging.logWriter - Write logs
  • roles/artifactregistry.writer - Push container images
These are granted automatically during deployment.

​
Troubleshooting

​
Deployment Failed

If deployment fails, try:
  1. Re-run the command - Permission propagation can take a few seconds
  2. Check billing - Ensure billing is enabled for the project
  3. Enable APIs manually: 
    gcloud services enable run.googleapis.com \
  cloudbuild.googleapis.com \
  artifactregistry.googleapis.com

​
Build Timeout

If the build times out after 10 minutes: 
Error: Deployment timed out after 10 minutes.
Check build status: 
https://console.cloud.google.com/cloud-build/builds?project=YOUR_PROJECT_ID

​
Missing API Keys

If your deployed service returns errors, verify environment variables were set: 
gcloud run services describe SERVICE_NAME --format="value(spec.template.spec.containers[0].env)"

​
Permission Denied

If you get permission errors:
  1. Verify you’re authenticated: gcloud auth list
  2. Check you have Owner or Editor role on the project
  3. Enable required APIs manually (see above)

​
Post-Deployment

​
Test Your Deployment

curl https://YOUR-SERVICE.run.app/health

​
View Logs

gcloud run logs read SERVICE_NAME --project=YOUR_PROJECT_ID
Or in the console: 
https://console.cloud.google.com/run?project=YOUR_PROJECT_ID

​
Update Deployment

To deploy updates: 
# Re-build deployment files (if needed)
klisk deploy init

# Deploy changes
klisk deploy
Cloud Run performs a rolling update with zero downtime.

​
Embed Chat Widget

Add the chat widget to your website: 
<script src="https://YOUR-SERVICE.run.app/widget.js"></script>

​
Cost Optimization

Cloud Run pricing is based on:
  • Request time - Pay only when handling requests
  • CPU/memory - Allocated resources
  • Network egress - Data transfer out
Free tier (per month):
  • 2 million requests
  • 360,000 GB-seconds of memory
  • 180,000 vCPU-seconds
Most Klisk deployments stay within the free tier for development and small-scale use.

Build docs developers (and LLMs) love

Get started for freeTalk to us