platform-setup

name	platform-setup
description	Set up Tangerine on the host machine or inside a VM — install tools, configure projects, clone repos, and install agent skills.
metadata	{"author":"tung","version":"1.3.3"}

Tangerine Init Skill

Set up the Tangerine coding agent platform. Tangerine can run directly on the host machine OR inside a Lima VM. Either way: one machine runs the server, dashboard, agents, and all project repos.

Architecture (v1)

Host (laptop) — or VM (Lima)
├── tangerine server + dashboard (:3456)
├── {workspace}/project-a      (main clone)
│              /project-a--wt-1 (task worktree)
│              /project-a--wt-2 (task worktree)
├── {workspace}/project-b, project-b--wt-1, ...
├── ACP agents — local stdio processes
└── Apache, MariaDB, tools — shared

{workspace} defaults to ~/tangerine-workspace but is configurable via config.workspace in ~/tangerine/config.json.

No SSH tunnels, no per-project VMs. One machine, all projects.

Routing

Before doing anything, figure out which mode applies:

1. Check if Tangerine is already running (tangerine --version or ~/tangerine/config.json exists) → Mode 3 (add a project).
2. Check if we're inside a Lima VM (limactl info fails or uname -n contains "lima") → Mode 1 (set up Tangerine here).
3. Check if the user is on macOS (uname -s = Darwin) and limactl is available → ask: "Do you want to run Tangerine directly on this machine or inside a Lima VM?"
   • Direct → Mode 1
   • VM → Mode 2
4. Otherwise (Linux host, no VM) → Mode 1.

Setup Modes

Two modes: Tangerine Setup (install and run Tangerine on the current machine) and VM Creation (create a Lima VM on macOS, then run Tangerine Setup inside it — the setup steps are identical once inside).

Mode 1: Tangerine Setup (host or inside VM)

User is on the machine where Tangerine will run — either their host or inside a Lima VM. You help them:

1. Install prerequisites

   Detect OS: uname -s → Darwin = macOS, Linux = Linux.

   macOS (use Homebrew; install brew first if missing):

   brew install git gh jq dtach node
   # Bun:
   curl -fsSL https://bun.sh/install | bash
   

   Linux (Debian/Ubuntu):

   sudo apt-get update && sudo apt-get install -y git curl jq dtach
   # Node.js 22:
   curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash -
   sudo apt-get install -y nodejs
   # Bun:
   curl -fsSL https://bun.sh/install | bash
   # gh CLI:
   (type -p wget >/dev/null || (sudo apt update && sudo apt-get install wget -y)) \
     && sudo mkdir -p -m 755 /etc/apt/keyrings \
     && out=$(mktemp) && wget -nv -O$out https://cli.github.com/packages/githubcli-archive-keyring.gpg \
     && cat $out | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \
     && sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
     && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
     && sudo apt update && sudo apt install gh -y
   

2. Choose, install, and authenticate ACP agent command(s).

   Tangerine is an ACP client only. It does not bundle provider adapters or manage LLM credentials. Configure one or more ACP commands in top-level agents[]. reads this config and installs Tangerine skills into the corresponding real agent directories via skills.sh (Claude Code, Codex, OpenCode, Pi); ACP itself is not a skill target.

Mode 2: VM Creation (macOS host, Lima)

User wants a Lima VM to run Tangerine in. You help them create it, then they run Mode 1 inside:

1. Write the Lima VM template and start the VM:

   cat > /tmp/tangerine.yaml << 'EOF'
   # Tangerine Lima VM Template
   
   # Debian 13 (Trixie) cloud images
   images:
     - location: "https://cloud.debian.org/images/cloud/trixie/daily/latest/debian-13-generic-arm64-daily.qcow2"
       arch: "aarch64"
     - location: "https://cloud.debian.org/images/cloud/trixie/daily/latest/debian-13-generic-amd64-daily.qcow2"
       arch: "x86_64"
   
   # Apple Virtualization.framework for better perf on macOS
   vmType: "vz"
   vmOpts:
     vz:
       rosetta:
         enabled: true
         binfmt: true
   
   cpus: 4
   memory: "8GiB"
   disk: "20GiB"
   
   ssh:
     localPort: 0
     loadDotSSHPubKeys: true
     forwardAgent: true
   
   portForwards:
     - guestPort: 3456
       hostIP: "0.0.0.0"
       hostPort: 3456
   
   # Mount tangerine data — DB, config, credentials survive VM rebuilds.
   mounts:
     - location: "~/tangerine"
       mountPoint: "/home/$USER/tangerine"
       writable: true
     - location: "~/.config/gh"
       mountPoint: "/home/$USER/.config/gh"
       writable: false
   EOF
   limactl start --name tangerine /tmp/tangerine.yaml
   

2. Shell into the VM, install your ACP agent command(s), authenticate them, then run /platform-setup:

   limactl shell tangerine
   # Install/configure the ACP agent command(s) you want Tangerine to run.
   bunx --bun @agentclientprotocol/claude-agent-acp --help
   bunx --bun @zed-industries/codex-acp --help
   bunx --bun opencode-ai acp --help
   bunx --bun pi-acp --
   
   gh auth login
   
   
   

Mode 3: Project Setup

User wants to add a project to an already-running Tangerine instance. You help them add the project to Tangerine.

Project Setup Workflow

1. Get repo URL from the user (and optionally a project name; default to the repo name).

2. Read the workspace path from the existing config (default ~/tangerine-workspace if the file doesn't exist yet):

   [ -f ~/tangerine/config.json ] \
     && jq -r '.workspace // "~/tangerine-workspace"' ~/tangerine/config.json \
     || echo ~/tangerine-workspace
   

   Use this resolved path as {workspace} for all subsequent steps. Never hardcode ~/tangerine-workspace.

3. Clone the repo into {workspace}/{projectName}:

   git clone <repo-url> {workspace}/my-project
   

   This is the main branch clone — it is never assigned to tasks. Task worktrees are created as siblings: {workspace}/my-project--wt-1, {workspace}/my-project--wt-2, etc. This path must match what getRepoDir() in packages/server/src/config.ts computes: join(resolveWorkspace(config), projectId).

4. Scan the cloned repo for stack indicators (see references/stacks.md):

   • Language runtimes and versions
   • Package managers
   • Frameworks and dev server configuration
   • Database/service dependencies
   • Test runners and commands
   • CI config (reveals required tooling)

5. Present the plan before writing:

   • Detected stack summary
   • Proposed project name
   • Clone path ({workspace}/{projectName})
   • Setup command — required, ask the user if it cannot be detected
   • Test command
   • Post-update command (install deps + build, runs after git pull)
   • ACP agent commands to configure and chosen defaultAgent
   • Optional runner agent, model, reasoningEffort, and permissionMode if the coordinator should differ from workers

6. Write config to ~/tangerine/config.json.

Credentials

Tangerine does not manage agent credentials. Before starting Tangerine, ensure each ACP agent command in top-level agents[] is installed and authenticated.

Tangerine does not configure or verify credentials — it relies on the agent's own auth being in place. If an agent fails to start due to missing credentials, authenticate it directly with that agent's CLI and retry. The known adapters above are process adapters only; Claude/Codex/OpenCode/Pi credentials still live in their own CLIs/config.

gh CLI is also required for GitHub integration (PR tracking, webhook setup). Tangerine checks gh auth status on startup and will warn if it is not authenticated — run gh auth login to fix it.

File Locations

~/tangerine/
  config.json             # all projects (managed by tangerine CLI)
  tangerine.db            # task database
~/tangerine-workspace/    # configurable via config.workspace
  project-a/         # main branch clone (never assigned to tasks)
  project-a--wt-1/   # task worktree
  project-a--wt-2/   # task worktree
  project-b/
  project-b--wt-1/

~/workspace/tangerine/    # tangerine source code

What to Ask the User

Only ask if you can't determine from the codebase:

• Repo URL (if no git remote found)
• Which ACP agent command(s) to configure (Claude Agent, Codex, OpenCode, Pi, or custom ACP command) and which one should be defaultAgent
• Whether runner tasks should use different taskTypes.runner.agent, model, reasoningEffort, or permissionMode defaults than worker tasks

Migrating from Old Worktree Layout

Older Tangerine installations used a numbered subdirectory layout:

{workspace}/project-a/0   # task worktree
{workspace}/project-a/1   # task worktree

The current layout uses sibling directories:

{workspace}/project-a        # main branch clone
{workspace}/project-a--wt-1  # task worktree
{workspace}/project-a--wt-2  # task worktree

To migrate, run:

tangerine migrate

This will:

• Move the main clone from {workspace}/project/ to {workspace}/project (flatten)
• Recreate worktree pool in the new sibling layout
• Release any stale worktree slots from dead tasks

Options:

• --project, -p <name> — migrate one project only

If active tasks still reference old worktrees, migration is blocked for that project. Finish or cancel running tasks first, then rerun.

After Init

# Start the server
bin/tangerine start

# Open browser
# http://localhost:3456 (forwarded from VM)

# Create tasks from dashboard or CLI
tangerine task create --project my-app --title "Fix bug"