This guide will get you from zero to a working Kizuna instance in under 10 minutes.

Option 1: Try Kizuna Cloud (Fastest)

The fastest way to experience Kizuna is with our managed cloud offering:

1. Sign up at cloud.kizuna.codes
2. Create an organization — your workspace for repositories
3. Create your first repository — click "New Repository" and follow the prompts
4. Clone and start coding:

   jj git clone https://cloud.kizuna.codes/your-org/your-repo
   cd your-repo
   # Start making changes — jj tracks everything automatically

Option 2: Self-Host with Docker

Run Kizuna OSS locally or on your own infrastructure:

Prerequisites

• Docker 24.0+
• Docker Compose 2.0+

1. Download the Compose File

curl -O https://raw.githubusercontent.com/kizuna-platform/kizuna/main/docker-compose.yml

2. Start the Services

docker-compose up -d

This starts:

• Kizuna web application (port 4000)
• PostgreSQL database
• Valkey (Redis-compatible cache)

3. Create an Admin User

docker-compose exec kizuna bin/kizuna eval "KizunaCore.Release.create_admin('admin@example.com', 'changeme')"

4. Access Kizuna

Open http://localhost:4000 and sign in with your admin credentials.

Your First Repository

Create via Web UI

1. Click New Repository on the dashboard
2. Enter a name (e.g., hello-kizuna)
3. Choose visibility: Public, Internal, or Private
4. Click Create Repository

Clone with Jujutsu

# Clone the repository
jj git clone http://localhost:4000/your-org/hello-kizuna
cd hello-kizuna

# Make your first change
echo "# Hello Kizuna" > README.md

# The change is automatically committed in jj
jj log

# Push to the server
jj git push

Clone with Git

Kizuna is fully Git-compatible:

git clone http://localhost:4000/your-org/hello-kizuna
cd hello-kizuna
echo "# Hello Kizuna" > README.md
git add README.md
git commit -m "Initial commit"
git push origin main

Register Your First Agent

Kizuna treats AI agents as first-class participants:

1. Go to Settings → Agents
2. Click Register New Agent
3. Enter:
   • Name: my-first-agent
   • Model Family: claude
   • Model Version: 3.5-sonnet
4. Select Trust Level 1 (Restricted — draft changes only)
5. Click Register

Your agent now has an AgentID and can interact with repositories via the MCP server.

Install the CLI (Optional)

The Kizuna CLI (kz) lets you manage everything from the terminal, including a full TUI:

# macOS (Apple Silicon)
curl -L https://releases.kizuna.codes/cli/latest/kz-darwin-arm64 -o kz
chmod +x kz && sudo mv kz /usr/local/bin/

# Set up and authenticate
kz config init
kz auth login

See the CLI Overview for all platforms and build-from-source instructions.

Next Steps

• Onboarding Tutorial — Complete walkthrough from sign-up to first PR
• Team Setup Tutorial — Configure your team's workflow
• Learn about Jujutsu workflows — Understand changes, conflicts, and the operation log
• Set up CI/CD — Configure automated pipelines
• CLI & TUI Guide — Manage Kizuna from the terminal
• Explore the REST API — Integrate with your tools
• Read about Agent Trust Levels — Understand the autonomy model

Getting Help

• Documentation: Browse the sidebar for detailed guides
• GitHub Issues: github.com/kizuna-platform/kizuna/issues
• Discord: Join our community at discord.gg/kizuna