Quickstart

Get started with 1Code in under 5 minutes. Run your first AI coding agent locally.

Get your first agent running in 3 steps

This guide will help you install 1Code, create your first chat session, and run an AI coding agent on your local project.

1. Download and install 1Code

   Choose your installation method:

   Download (Recommended)

   Visit 1code.dev and download the pre-built app for your platform:

   • macOS: Download the DMG (Apple Silicon or Intel)
   • Windows: Download the installer (coming soon)
   • Linux: Download AppImage or DEB (coming soon)

   Pre-built releases include automatic updates and support for background agents. Your subscription helps maintain and improve 1Code.

   macOS Installation:

   1. Open the downloaded DMG file
   2. Drag 1Code to your Applications folder
   3. Launch 1Code from Applications
   4. If you see a security warning, go to System Preferences → Security & Privacy and click Open Anyway

   Build from Source

   Build 1Code yourself from the open-source repository:

   Prerequisites:

   • Bun runtime
   • Python 3.11+ with setuptools installed
   • macOS: Xcode Command Line Tools
   • Linux: Build essentials

   Build steps:

   # Clone the repository
   git clone https://github.com/21st-dev/1code.git
   cd 1code
   
   # Install dependencies
   bun install
   
   # Download required agent binaries (critical!)
   bun run claude:download
   bun run codex:download
   
   # Build the app
   bun run build
   
   # Package for your platform
   bun run package:mac     # macOS
   # bun run package:win   # Windows
   # bun run package:linux # Linux
   

   Don’t skip the claude:download and codex:download steps! These download the required agent binaries. Without them, the app will build but agents won’t work.

   The packaged app will be in the release/ directory.

2. Create your first chat session

   When you first launch 1Code, you’ll be prompted to:

   1. Select a project folder - Choose any local Git repository or project directory
   2. Configure your API keys - Add your Anthropic API key for Claude, or OpenAI key for Codex
      • Click Settings → API Keys
      • Enter your API key and save

   Don’t have an API key? Get one from Anthropic or OpenAI.

   3. Start a new chat - Click the New Chat button or press Cmd/Ctrl + N
3. Run your first agent

   Now let’s give your agent a task!

   Try these example prompts:

   Simple task

   Add a README file with project setup instructions
   

   Watch your agent work:

   • See real-time tool execution (bash commands, file edits)
   • Review diffs before they’re applied
   • View file changes with syntax highlighting
   • Approve or reject changes

   Each chat runs in its own Git worktree by default, keeping your main branch safe. You can disable this in settings if you prefer.

What’s next?

Now that you have 1Code running, explore these powerful features:

Git Worktree Isolation

Run agents in isolated worktrees without touching your main branch.

Plan Mode

Let agents ask clarifying questions and show plans before execution.

Background Agents

Run agents in cloud sandboxes that work while you sleep.

MCP Integration

Connect external tools and data sources to your agents.

Common first-run issues

Agent binary not found

Error: “Claude binary not found” or “Codex binary not found”

Solution: If you built from source, make sure you ran the download scripts:

bun run claude:download
bun run codex:download

The binaries should be in resources/bin/ after download.

API key not working

Error: “Invalid API key” or authentication failures

Solution:

1. Verify your API key is correct in Settings → API Keys
2. Check your API key has sufficient credits/quota
3. For Anthropic, ensure you’re using a valid Claude API key (not Console key)

macOS security warning

Error: “1Code can’t be opened because it is from an unidentified developer”

Solution:

1. Go to System Preferences → Security & Privacy
2. Click Open Anyway next to the 1Code warning
3. Confirm you want to open the app

For builds from source, you may need to remove quarantine:

xattr -cr /Applications/1Code.app

Python build errors

Error: Build fails with Python-related errors

Solution:

1. Ensure Python 3.11+ is installed: python --version
2. Install setuptools: pip install setuptools
3. On Python 3.12+, setuptools is required for native module rebuilds

Need more help?

Join our Discord community for support and discussions.