First Steps

A step-by-step guide to getting started with Yukkai after installation — from onboarding and permissions to your first task.

Welcome to Yukkai! This guide walks you through the essential first steps after installing the app — from initial setup to running your first real task.

1. Complete Onboarding

When you first launch Yukkai, the onboarding flow guides you through:

  1. Welcome screen — overview of Yukkai's capabilities.
  2. Account setup — create or sign in to your Yukkai account (this generates your master API key yk_...).
  3. Model selection — choose your default model:

  • Yukkai Free — no cost, daily/monthly limits.
  • Yukkai Fusion — best all-around choice for everyday use.
  • Yukkai Frontier — maximum capability for demanding tasks.
  • Personal OpenRouter key — bring your own API key.
  • Yukkai Local — run open-weight models on your Mac (offline).

  1. Permissions — grant the required macOS permissions (see below).

2. Grant Permissions

Yukkai needs several macOS permissions to function fully. The onboarding flow will prompt you, but you can also grant them manually:

Permission Required For
Accessibility Desktop automation — clicks, typing, window management
Screen Recording Screenshots for desktop observation
Full Disk Access File read/write across the filesystem

To grant permissions manually:

  1. Open System Settings → Privacy & Security.
  2. Select Accessibility, Screen Recording, or Full Disk Access.
  3. Toggle Yukkai to on.
  4. Restart Yukkai if prompted.

Without Accessibility and Screen Recording, desktop automation will silently fail — clicks and typing will have no effect.

3. Choose Your Model

The model picker is in the chat interface. For your first session, we recommend:

  • Yukkai Fusion if you have a Yukkai account with credits — it automatically picks the best model for each task.
  • Yukkai Free if you want to try Yukkai at no cost.
  • Yukkai Local if you want to run everything offline (requires downloading a model first).

You can switch models at any time from the model picker. See Choosing a Model for details.

4. Send Your First Message

Try a simple task to see Yukkai in action: 

List all files in ~/Documents and create a summary of what's there.

Yukkai will:

  1. Use the glob or bash tool to list files.
  2. Read relevant files.
  3. Create a summary document.

5. Try Desktop Automation

If you granted Accessibility and Screen Recording permissions, try: 

Take a screenshot and tell me what's on my screen.

Or: 

Open TextEdit and write "Hello from Yukkai!" in a new document.

Yukkai will use YukkaiPilot to observe your screen, launch TextEdit, and type the text — verifying each step along the way.

6. Try Web Browsing

Search the web for "latest macOS updates" and summarize the top 3 results.

Yukkai will use web search, then browse the top results with its built-in WebKit browser to extract and summarize content.

7. Explore the Interface

Key areas of the Yukkai interface:

Area Purpose
Chat Main conversation interface — where you interact with Yukkai.
Model Picker Switch between available models (Fusion, Frontier, Free, Local, personal).
Settings Configure permissions, API keys, credits, security, tools, and more.
Sessions Manage multiple simultaneous conversations.
Browser Independent browser window for manual browsing.
YukkaiPilot Status UI for desktop automation.

8. Add Credits (Optional)

If you're using Yukkai Fusion or Frontier, you'll need credits in your Wallet:

  1. Go to Settings → Credits.
  2. Click Add Credits.
  3. Choose a credit pack ($10 to $1000).
  4. Complete the Stripe checkout in your browser.
  5. Your balance updates automatically once payment is confirmed.

See Yukkai Wallet for details.

9. Explore Advanced Features

Once you're comfortable with the basics, explore:

  • Swarm — orchestrate dozens of parallel agents for complex tasks. See Swarm Overview.
  • Skills — activate specialized knowledge domains (code review, Office documents, design, etc.). See Built-in Skills.
  • Workflows — create reusable multi-stage automation pipelines.
  • YukkaiConnect — integrate with GitHub, Slack, Notion, Trello, and more.
  • RAG Knowledge Base — index your documents for semantic search.
  • Vault — encrypt sensitive files and folders with AES-256-GCM.

10. Customize Your Experience

  • Custom personalities — change Yukkai's tone and behavior. See Personalities.
  • Custom skills — create your own knowledge domains. See Creating Custom Skills.
  • Agent roles — define custom roles for swarm sub-agents.
  • Design systems — enforce consistent visual identity in generated frontend code.

Common First Tasks

Here are some tasks new users commonly try: 

# File management
Organize my ~/Downloads folder by file type into subfolders.

# Web research
Research the top 5 project management tools and create a comparison table.

# Code generation
Create a simple SwiftUI todo list app in ~/Projects/todo-app.

# Desktop automation
Open Safari, go to apple.com, and take a screenshot.

# Media generation
Generate an image of a sunset over mountains in 16:9 aspect ratio.

# Parallel processing
Launch 5 agents to analyze the code files in ~/Projects/myapp and summarize each one.

Troubleshooting

If something doesn't work:

  • Desktop automation fails → Check Accessibility and Screen Recording permissions.
  • No response from model → Check your internet connection and Wallet balance.
  • File access denied → Grant Full Disk Access in System Settings.
  • Local model won't load → Check available RAM and close other apps.

See the Troubleshooting Guide for detailed solutions.

Next Steps

Last updated: July 19, 2026