diff --git a/docs/API.md b/docs/API.md
index d37707957..1497312de 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -25,7 +25,7 @@ GET https://api.openfront.io/public/games
 - `end` (required): ISO 8601 timestamp
 - `type` (optional): Game type, must be one of `[Private, Public, Singleplayer]`
 - `mode` (optional): Game mode, must be one of `[Free For All, Team]`
-- `rankedType` (optional): Ranked type, must be one of `[unranked, 1v1]`
+- `rankedType` (optional): Ranked type, must be one of `[unranked, 1v1, 2v2]`
 - `playerTeams` (optional): Player team configuration (e.g. `Duos`)
 - `limit` (optional): Number of results (max 1000, default 50)
 - `offset` (optional): Pagination offset
diff --git a/resources/lang/en.json b/resources/lang/en.json
index 1af29f0c9..13eb59a36 100644
--- a/resources/lang/en.json
+++ b/resources/lang/en.json
@@ -1077,6 +1077,7 @@
     "replaced": "You joined matchmaking from another tab or window.",
     "searching": "Searching for game...",
     "title": "1v1 Ranked Matchmaking (ALPHA)",
+    "title_2v2": "2v2 Ranked Matchmaking (ALPHA)",
     "waiting_for_game": "Waiting for game to start..."
   },
   "mode_selector": {
@@ -1208,6 +1209,7 @@
     "public": "Public",
     "ranked": "Ranked",
     "ranked_1v1": "1v1",
+    "ranked_2v2": "2v2",
     "solo": "Solo",
     "stats_games_played": "Games Played",
     "stats_losses": "Losses",
diff --git a/src/client/Main.ts b/src/client/Main.ts
index 4e5c49b7b..a74f14ac1 100644
--- a/src/client/Main.ts
+++ b/src/client/Main.ts
@@ -233,7 +233,7 @@ declare global {
     "kick-player": CustomEvent;
     toggle_game_start_timer: CustomEvent;
     "join-changed": CustomEvent;
-    "open-matchmaking": CustomEvent<undefined>;
+    "open-matchmaking": CustomEvent<{ mode?: "1v1" | "2v2" } | undefined>;
     userMeResponse: CustomEvent<UserMeResponse | false>;
     "leave-lobby": CustomEvent;
     "update-game-config": CustomEvent;
@@ -854,16 +854,24 @@ class Client {
       window.location.href = "/";
     }
 
-    if (this.consumeRequeueUrl()) {
-      document.dispatchEvent(new CustomEvent("open-matchmaking"));
+    const requeueMode = this.consumeRequeueUrl();
+    if (requeueMode !== null) {
+      document.dispatchEvent(
+        new CustomEvent("open-matchmaking", {
+          detail: { mode: requeueMode },
+        }),
+      );
     }
   }
 
-  private consumeRequeueUrl(): boolean {
+  // Returns the requeue mode ("/?requeue" = 1v1, "/?requeue=2v2" = 2v2), or
+  // null when the URL has no requeue param.
+  private consumeRequeueUrl(): "1v1" | "2v2" | null {
     const searchParams = new URLSearchParams(window.location.search);
     if (!searchParams.has("requeue")) {
-      return false;
+      return null;
     }
+    const mode = searchParams.get("requeue") === "2v2" ? "2v2" : "1v1";
 
     searchParams.delete("requeue");
     const newUrl =
@@ -871,7 +879,7 @@ class Client {
       (searchParams.toString() ? `?${searchParams.toString()}` : "") +
       window.location.hash;
     history.replaceState(null, "", newUrl);
-    return true;
+    return mode;
   }
 
   private async handleJoinLobby(event: CustomEvent<JoinLobbyEvent>) {
@@ -1066,8 +1074,14 @@ class Client {
     crazyGamesSDK.gameplayStop();
   }
 
-  private handleOpenMatchmaking(_event: CustomEvent<undefined>) {
-    this.matchmakingModal?.open();
+  private handleOpenMatchmaking(
+    event: CustomEvent<{ mode?: "1v1" | "2v2" } | undefined>,
+  ) {
+    if (!this.matchmakingModal) return;
+    // Always set the mode: dispatchers without a detail (homepage button,
+    // requeue URL) mean 1v1 and must reset a lingering 2v2 selection.
+    this.matchmakingModal.mode = event.detail?.mode === "2v2" ? "2v2" : "1v1";
+    this.matchmakingModal.open();
   }
 
   private handleKickPlayer(event: CustomEvent) {
diff --git a/src/client/Matchmaking.ts b/src/client/Matchmaking.ts
index 9f2484241..9e4effdb9 100644
--- a/src/client/Matchmaking.ts
+++ b/src/client/Matchmaking.ts
@@ -18,6 +18,9 @@ export class MatchmakingModal extends BaseModal {
   private reconnectTimeout: ReturnType<typeof setTimeout> | null = null;
   private reconnectAttempts = 0;
   private intentionalClose = false;
+  // Which queue to join; set by Main from the open-matchmaking event
+  // before the modal opens.
+  public mode: "1v1" | "2v2" = "1v1";
   @state() private connected = false;
   @state() private socket: WebSocket | null = null;
   @state() private gameID: string | null = null;
@@ -34,7 +37,11 @@ export class MatchmakingModal extends BaseModal {
 
   protected renderHeaderSlot() {
     return modalHeader({
-      title: translateText("matchmaking_modal.title"),
+      title: translateText(
+        this.mode === "2v2"
+          ? "matchmaking_modal.title_2v2"
+          : "matchmaking_modal.title",
+      ),
       onBack: () => this.close(),
       ariaLabel: translateText("common.back"),
     });
@@ -80,7 +87,7 @@ export class MatchmakingModal extends BaseModal {
       this.connectTimeout = null;
     }
     this.socket = new WebSocket(
-      `${ClientEnv.jwtIssuer()}/matchmaking/join?instance_id=${encodeURIComponent(ClientEnv.instanceId())}`,
+      `${ClientEnv.jwtIssuer()}/matchmaking/join?instance_id=${encodeURIComponent(ClientEnv.instanceId())}&mode=${this.mode}`,
     );
     this.socket.onopen = async () => {
       console.log("Connected to matchmaking server");
@@ -184,9 +191,11 @@ export class MatchmakingModal extends BaseModal {
       return;
     }
 
-    this.elo =
-      userMe.player.leaderboard?.oneVone?.elo ??
-      translateText("matchmaking_modal.no_elo");
+    const row =
+      this.mode === "2v2"
+        ? userMe.player.leaderboard?.twoVtwo
+        : userMe.player.leaderboard?.oneVone;
+    this.elo = row?.elo ?? translateText("matchmaking_modal.no_elo");
 
     this.connected = false;
     this.gameID = null;
diff --git a/src/client/components/RankedModal.ts b/src/client/components/RankedModal.ts
index 94cf987b1..d377546fe 100644
--- a/src/client/components/RankedModal.ts
+++ b/src/client/components/RankedModal.ts
@@ -13,6 +13,7 @@ export class RankedModal extends BaseModal {
   protected routerName = "ranked";
 
   @state() private elo: number | string = "...";
+  @state() private elo2v2: number | string = "...";
   @state() private userMeResponse: UserMeResponse | false = false;
   @state() private errorMessage: string | null = null;
   // CrazyGames players authenticate through the SDK, not a linked
@@ -56,20 +57,23 @@ export class RankedModal extends BaseModal {
   private updateElo() {
     if (this.errorMessage) {
       this.elo = translateText("map_component.error");
+      this.elo2v2 = translateText("map_component.error");
       return;
     }
 
     if (this.isRankedEligible()) {
-      this.elo =
-        this.userMeResponse &&
-        this.userMeResponse.player.leaderboard?.oneVone?.elo
-          ? this.userMeResponse.player.leaderboard.oneVone.elo
-          : translateText("matchmaking_modal.no_elo");
+      const leaderboard = this.userMeResponse
+        ? this.userMeResponse.player.leaderboard
+        : undefined;
+      const noElo = translateText("matchmaking_modal.no_elo");
+      this.elo = leaderboard?.oneVone?.elo ?? noElo;
+      this.elo2v2 = leaderboard?.twoVtwo?.elo ?? noElo;
     }
   }
 
   protected override async onOpen(): Promise<void> {
     this.elo = "...";
+    this.elo2v2 = "...";
     this.errorMessage = null;
 
     try {
@@ -83,6 +87,7 @@ export class RankedModal extends BaseModal {
       this.userMeResponse = false;
       this.errorMessage = translateText("map_component.error");
       this.elo = translateText("map_component.error");
+      this.elo2v2 = translateText("map_component.error");
     } finally {
       this.updateElo();
     }
@@ -110,11 +115,15 @@ export class RankedModal extends BaseModal {
               (this.isRankedEligible()
                 ? translateText("matchmaking_modal.elo", { elo: this.elo })
                 : translateText("mode_selector.ranked_title")),
-            () => this.handleRanked(),
+            () => this.handleRanked("1v1"),
           )}
-          ${this.renderDisabledCard(
+          ${this.renderCard(
             translateText("mode_selector.ranked_2v2_title"),
-            translateText("mode_selector.coming_soon"),
+            this.errorMessage ??
+              (this.isRankedEligible()
+                ? translateText("matchmaking_modal.elo", { elo: this.elo2v2 })
+                : translateText("mode_selector.ranked_title")),
+            () => this.handleRanked("2v2"),
           )}
           ${this.renderDisabledCard(
             translateText("mode_selector.coming_soon"),
@@ -133,7 +142,7 @@ export class RankedModal extends BaseModal {
     return html`
       <button
         @click=${onClick}
-        class="flex flex-col w-full h-28 sm:h-32 rounded-2xl bg-surface border-0 transition-transform hover:scale-[1.02] active:scale-[0.98] p-6 items-center justify-center gap-3"
+        class="flex flex-col w-full h-28 sm:h-32 rounded-2xl bg-malibu-blue border-0 transition-all duration-200 hover:bg-aquarius hover:scale-[1.03] hover:shadow-[var(--shadow-action-card-hover)] active:bg-malibu-blue/80 active:scale-[0.98] p-6 items-center justify-center gap-3"
       >
         <div class="flex flex-col items-center gap-1 text-center">
           <h3
@@ -142,7 +151,7 @@ export class RankedModal extends BaseModal {
             ${title}
           </h3>
           <p
-            class="text-xs text-white/60 uppercase tracking-wider whitespace-pre-line leading-tight"
+            class="text-xs text-white/80 uppercase tracking-wider whitespace-pre-line leading-tight"
           >
             ${subtitle}
           </p>
@@ -172,13 +181,15 @@ export class RankedModal extends BaseModal {
     `;
   }
 
-  private async handleRanked() {
+  private async handleRanked(mode: "1v1" | "2v2") {
     if ((await userAuth()) === false) {
       this.close();
       window.showPage?.("page-account");
       return;
     }
 
-    document.dispatchEvent(new CustomEvent("open-matchmaking"));
+    document.dispatchEvent(
+      new CustomEvent("open-matchmaking", { detail: { mode } }),
+    );
   }
 }
diff --git a/src/client/components/baseComponents/stats/PlayerStatsTree.ts b/src/client/components/baseComponents/stats/PlayerStatsTree.ts
index 809e482c0..ebff61234 100644
--- a/src/client/components/baseComponents/stats/PlayerStatsTree.ts
+++ b/src/client/components/baseComponents/stats/PlayerStatsTree.ts
@@ -78,6 +78,8 @@ export class PlayerStatsTreeView extends LitElement {
     switch (r) {
       case RankedType.OneVOne:
         return translateText("player_stats_tree.ranked_1v1");
+      case RankedType.TwoVTwo:
+        return translateText("player_stats_tree.ranked_2v2");
     }
   }
 
diff --git a/src/client/hud/layers/WinModal.ts b/src/client/hud/layers/WinModal.ts
index 2728db546..8e95c876e 100644
--- a/src/client/hud/layers/WinModal.ts
+++ b/src/client/hud/layers/WinModal.ts
@@ -228,7 +228,7 @@ export class WinModal extends LitElement implements Controller {
     await this.loadPatternContent();
     // Check if this is a ranked game
     this.isRankedGame =
-      this.game.config().gameConfig().rankedType === RankedType.OneVOne;
+      this.game.config().gameConfig().rankedType !== undefined;
     this.isVisible = true;
     this.requestUpdate();
     setTimeout(() => {
@@ -250,8 +250,12 @@ export class WinModal extends LitElement implements Controller {
 
   private _handleRequeue() {
     this.hide();
-    // Navigate to homepage and open matchmaking modal
-    window.location.href = "/?requeue";
+    // Navigate to homepage and open matchmaking modal for the same mode
+    const requeue =
+      this.game.config().gameConfig().rankedType === RankedType.TwoVTwo
+        ? "/?requeue=2v2"
+        : "/?requeue";
+    window.location.href = requeue;
   }
 
   init() {}
diff --git a/src/core/ApiSchemas.ts b/src/core/ApiSchemas.ts
index 0eeb2ee6f..b242ee0bc 100644
--- a/src/core/ApiSchemas.ts
+++ b/src/core/ApiSchemas.ts
@@ -128,6 +128,11 @@ export const UserMeResponseSchema = z.object({
             elo: z.number().optional(),
           })
           .optional(),
+        twoVtwo: z
+          .object({
+            elo: z.number().optional(),
+          })
+          .optional(),
       })
       .optional(),
     currency: CurrencyBalancesSchema.optional(),
diff --git a/src/core/GameRunner.ts b/src/core/GameRunner.ts
index 1e8627455..8c3c153bb 100644
--- a/src/core/GameRunner.ts
+++ b/src/core/GameRunner.ts
@@ -55,6 +55,7 @@ export async function createGameRunner(
       p.isLobbyCreator ?? false,
       p.clanTag,
       p.friends ?? [],
+      p.teamIndex ?? null,
     );
   });
 
diff --git a/src/core/Schemas.ts b/src/core/Schemas.ts
index 396df0bb0..50ee54ae0 100644
--- a/src/core/Schemas.ts
+++ b/src/core/Schemas.ts
@@ -690,6 +690,10 @@ export const PlayerSchema = z.object({
   cosmetics: PlayerCosmeticsSchema.optional(),
   isLobbyCreator: z.boolean().optional(),
   friends: z.array(ID).optional(),
+  // Server-stamped team slot for matchmade team games (index into the
+  // game's team list). Feeds deterministic team assignment, so it must be
+  // identical for every client (like clanTag/friends).
+  teamIndex: z.number().int().nonnegative().optional(),
 });
 
 export const GameStartInfoSchema = z.object({
diff --git a/src/core/game/Game.ts b/src/core/game/Game.ts
index a4d4523ca..e4d8b07b6 100644
--- a/src/core/game/Game.ts
+++ b/src/core/game/Game.ts
@@ -125,6 +125,7 @@ export enum GameMode {
 
 export enum RankedType {
   OneVOne = "1v1",
+  TwoVTwo = "2v2",
 }
 
 export const isGameMode = (value: unknown): value is GameMode =>
@@ -419,6 +420,9 @@ export class PlayerInfo {
     public readonly isLobbyCreator: boolean = false,
     public readonly clanTag: string | null = null,
     public readonly friends: ClientID[] = [],
+    // Server-pinned team slot (index into the game's team list) for
+    // matchmade team games; null = assign normally.
+    public readonly teamIndex: number | null = null,
   ) {
     this.displayName = formatPlayerDisplayName(this.name, this.clanTag);
   }
diff --git a/src/core/game/TeamAssignment.ts b/src/core/game/TeamAssignment.ts
index 02bf47b5d..eca321aa6 100644
--- a/src/core/game/TeamAssignment.ts
+++ b/src/core/game/TeamAssignment.ts
@@ -11,12 +11,27 @@ export function assignTeams(
   const result = new Map<PlayerInfo, Team | "kicked">();
   const teamPlayerCount = new Map<Team, number>();
 
+  // Matchmade games arrive with a server-pinned team slot (teamIndex). The
+  // matchmaker already balanced those teams, so pins are honored
+  // unconditionally — before and regardless of clan/friend grouping and
+  // maxTeamSize — and seed the counts the balancing below sees.
+  const unpinned: PlayerInfo[] = [];
+  for (const p of players) {
+    const pinnedTeam = p.teamIndex === null ? undefined : teams[p.teamIndex];
+    if (pinnedTeam === undefined) {
+      unpinned.push(p);
+      continue;
+    }
+    result.set(p, pinnedTeam);
+    teamPlayerCount.set(pinnedTeam, (teamPlayerCount.get(pinnedTeam) ?? 0) + 1);
+  }
+
   // Clans are strict: a clan goes to one team together, and any overflow
   // members get kicked. (You opted into the clan, so we honor "all or
   // nothing" for placement.)
   const clanGroups = new Map<string, PlayerInfo[]>();
   const nonClanPlayers: PlayerInfo[] = [];
-  for (const p of players) {
+  for (const p of unpinned) {
     if (p.clanTag) {
       if (!clanGroups.has(p.clanTag)) clanGroups.set(p.clanTag, []);
       clanGroups.get(p.clanTag)!.push(p);
diff --git a/src/server/GameManager.ts b/src/server/GameManager.ts
index eba8a711e..08558696a 100644
--- a/src/server/GameManager.ts
+++ b/src/server/GameManager.ts
@@ -67,6 +67,7 @@ export class GameManager {
     creatorPersistentID?: string,
     startsAt?: number,
     publicGameType?: PublicGameType,
+    matchmakingTeams?: string[][],
   ): GameServer | null {
     if (this.games.has(id)) {
       this.log.warn("cannot create game, id already exists", { gameID: id });
@@ -98,6 +99,7 @@ export class GameManager {
       creatorPersistentID,
       startsAt,
       publicGameType,
+      matchmakingTeams,
     );
     this.games.set(id, game);
     return game;
diff --git a/src/server/GameServer.ts b/src/server/GameServer.ts
index 71a39652d..c1a0fe15d 100644
--- a/src/server/GameServer.ts
+++ b/src/server/GameServer.ts
@@ -173,6 +173,9 @@ export class GameServer {
     private creatorPersistentID?: string,
     private startsAt?: number,
     private publicGameType?: PublicGameType,
+    // Matchmade team split from the matchmaking assignment: publicIds per
+    // team. At start each client is stamped with its team's index.
+    private matchmakingTeams?: string[][],
   ) {
     this.log = log_.child({ gameID: id });
     if (startsAt !== undefined) {
@@ -537,7 +540,10 @@ export class GameServer {
       clientIP: ipAnonymize(client.ip),
     });
 
+    // Skipped in dev: local testing (multi-tab, the matchmaking e2e) is
+    // inherently same-IP.
     if (
+      ServerEnv.env() !== GameEnv.Dev &&
       this.gameConfig.gameType === GameType.Public &&
       this.activeClients.filter(
         (c) => c.ip === client.ip && c.clientID !== client.clientID,
@@ -941,6 +947,7 @@ export class GameServer {
         cosmetics: c.cosmetics,
         isLobbyCreator: this.lobbyCreatorID === c.clientID,
         friends: friendsFor(c),
+        teamIndex: this.matchmakingTeamIndex(c),
       })),
     });
     if (!result.success) {
@@ -972,6 +979,20 @@ export class GameServer {
     });
   }
 
+  // Resolves a client to its matchmade team slot (index into
+  // matchmakingTeams), or undefined when the game isn't matchmade / the
+  // client isn't in the assignment.
+  private matchmakingTeamIndex(c: Client): number | undefined {
+    const publicId = c.publicId;
+    if (this.matchmakingTeams === undefined || publicId === undefined) {
+      return undefined;
+    }
+    const idx = this.matchmakingTeams.findIndex((team) =>
+      team.includes(publicId),
+    );
+    return idx === -1 ? undefined : idx;
+  }
+
   private addIntent(intent: StampedIntent) {
     this.intents.push(intent);
   }
diff --git a/src/server/MapPlaylist.ts b/src/server/MapPlaylist.ts
index a294c8cb5..5dbe46110 100644
--- a/src/server/MapPlaylist.ts
+++ b/src/server/MapPlaylist.ts
@@ -441,6 +441,37 @@ export class MapPlaylist {
     } satisfies GameConfig;
   }
 
+  public get2v2Config(): GameConfig {
+    const maps = [
+      GameMapType.Australia, // 40%
+      GameMapType.Australia,
+      GameMapType.Iceland, // 20%
+      GameMapType.Asia, // 20%
+      GameMapType.EuropeClassic, // 20%
+    ];
+    return {
+      donateGold: true,
+      donateTroops: true,
+      gameMap: maps[Math.floor(Math.random() * maps.length)],
+      maxPlayers: 4,
+      gameType: GameType.Public,
+      gameMapSize: GameMapSize.Compact,
+      difficulty: Difficulty.Medium, // Doesn't matter, nations are disabled
+      rankedType: RankedType.TwoVTwo,
+      infiniteGold: false,
+      infiniteTroops: false,
+      maxTimerValue: 10,
+      instantBuild: false,
+      randomSpawn: false,
+      nations: "disabled",
+      gameMode: GameMode.Team,
+      playerTeams: 2,
+      bots: 100,
+      spawnImmunityDuration: 30 * 10,
+      disabledUnits: [],
+    } satisfies GameConfig;
+  }
+
   private getNextMap(type: ScheduledPublicGameType): GameMapType {
     const playlist = this.playlists[type];
     if (playlist.length === 0) {
diff --git a/src/server/Worker.ts b/src/server/Worker.ts
index bf043567d..98c2643d2 100644
--- a/src/server/Worker.ts
+++ b/src/server/Worker.ts
@@ -700,6 +700,21 @@ export async function startWorker() {
 }
 
 async function startMatchmakingPolling(gm: GameManager) {
+  // One checkin serves exactly one queue, so a host serving both modes
+  // runs one long-poll loop per mode.
+  startMatchmakingLoop(gm, "1v1");
+  startMatchmakingLoop(gm, "2v2");
+}
+
+const MatchmakingAssignmentSchema = z.object({
+  // Flat list of matched players' publicIds.
+  players: z.array(z.string()),
+  // The matcher's team split ([[a],[b]] for 1v1). Optional for tolerance,
+  // but the current API always sends it.
+  teams: z.array(z.array(z.string())).optional(),
+});
+
+function startMatchmakingLoop(gm: GameManager, mode: "1v1" | "2v2") {
   startPolling(
     async () => {
       try {
@@ -723,6 +738,7 @@ async function startMatchmakingPolling(gm: GameManager) {
             gameId: gameId,
             ccu: gm.activeClients(),
             instanceId: process.env.INSTANCE_ID,
+            mode,
           }),
           signal: controller.signal,
         });
@@ -731,20 +747,34 @@ async function startMatchmakingPolling(gm: GameManager) {
 
         if (!response.ok) {
           log.warn(
-            `Failed to poll lobby: ${response.status} ${response.statusText}`,
+            `Failed to poll ${mode} lobby: ${response.status} ${response.statusText}`,
           );
           return;
         }
 
         const data = await response.json();
-        log.info(`Lobby poll successful:`, data);
+        log.info(`Lobby ${mode} poll successful:`, data);
 
         if (data.assignment) {
+          const parsed = MatchmakingAssignmentSchema.safeParse(data.assignment);
+          if (!parsed.success) {
+            // Don't strand the matched players: create the game without
+            // the allowlist/team pins rather than dropping the match.
+            log.warn(
+              `Unexpected ${mode} assignment shape: ${z.prettifyError(parsed.error)}`,
+            );
+          }
+          const baseConfig =
+            mode === "2v2" ? playlist.get2v2Config() : playlist.get1v1Config();
           const game = gm.createGame(
             gameId,
-            playlist.get1v1Config(),
+            parsed.success
+              ? { ...baseConfig, allowedPublicIds: parsed.data.players }
+              : baseConfig,
             undefined,
             Date.now() + 7000,
+            undefined,
+            parsed.success ? parsed.data.teams : undefined,
           );
           if (game === null) {
             log.warn(`Failed to create matchmaking game ${gameId}`);
@@ -755,7 +785,7 @@ async function startMatchmakingPolling(gm: GameManager) {
           // Abort is expected if no game is scheduled on this worker.
           return;
         }
-        log.error(`Error polling lobby:`, error);
+        log.error(`Error polling ${mode} lobby:`, error);
       }
     },
     5000 + Math.random() * 1000,
diff --git a/tests/Team.test.ts b/tests/Team.test.ts
index 414bb6c35..efb750b7b 100644
--- a/tests/Team.test.ts
+++ b/tests/Team.test.ts
@@ -2,6 +2,7 @@ import {
   ColoredTeams,
   Game,
   GameMode,
+  PlayerInfo,
   PlayerType,
 } from "../src/core/game/Game";
 import { playerInfo, setup } from "./util/Setup";
@@ -39,4 +40,33 @@ describe("Teams", () => {
       false,
     );
   });
+
+  test("humans with pinned teamIndex get the matcher's exact split", async () => {
+    // Matchmade 2v2: the server stamps teamIndex per player; the split
+    // [h1,h4] vs [h2,h3] must survive full game construction.
+    const pinned = (name: string, teamIndex: number) =>
+      new PlayerInfo(
+        name,
+        PlayerType.Human,
+        name,
+        name,
+        false,
+        null,
+        [],
+        teamIndex,
+      );
+    game = await setup(
+      "plains",
+      {
+        gameMode: GameMode.Team,
+        playerTeams: 2,
+      },
+      [pinned("h1", 0), pinned("h2", 1), pinned("h3", 1), pinned("h4", 0)],
+    );
+
+    expect(game.player("h1").team()).toBe(ColoredTeams.Red);
+    expect(game.player("h2").team()).toBe(ColoredTeams.Blue);
+    expect(game.player("h3").team()).toBe(ColoredTeams.Blue);
+    expect(game.player("h4").team()).toBe(ColoredTeams.Red);
+  });
 });
diff --git a/tests/TeamAssignment.test.ts b/tests/TeamAssignment.test.ts
index 6a3c7c718..c8089d8bf 100644
--- a/tests/TeamAssignment.test.ts
+++ b/tests/TeamAssignment.test.ts
@@ -291,6 +291,115 @@ describe("assignTeams", () => {
     expect(result.get(players[3])).not.toEqual(result.get(players[0]));
   });
 
+  // Matchmade games: the server pins each player to a team slot via
+  // PlayerInfo.teamIndex and the matcher's split must be honored verbatim.
+  const createPinnedPlayer = (
+    id: string,
+    teamIndex: number | null,
+    clan?: string,
+    friends: string[] = [],
+  ): PlayerInfo => {
+    return new PlayerInfo(
+      `Player ${id}`,
+      PlayerType.Human,
+      id, // clientID
+      id,
+      false,
+      clan,
+      friends,
+      teamIndex,
+    );
+  };
+
+  it("should honor pinned teamIndex exactly (matchmade 2v2)", () => {
+    const players = [
+      createPinnedPlayer("1", 0),
+      createPinnedPlayer("2", 1),
+      createPinnedPlayer("3", 1),
+      createPinnedPlayer("4", 0),
+    ];
+
+    const result = assignTeams(players, teams);
+
+    expect(result.get(players[0])).toEqual(ColoredTeams.Red);
+    expect(result.get(players[1])).toEqual(ColoredTeams.Blue);
+    expect(result.get(players[2])).toEqual(ColoredTeams.Blue);
+    expect(result.get(players[3])).toEqual(ColoredTeams.Red);
+  });
+
+  it("should let pins override clan grouping", () => {
+    // Two clanmates matched onto opposite teams stay split: the matcher's
+    // balancing is authoritative over the clan all-on-one-team rule.
+    const players = [
+      createPinnedPlayer("1", 0, "CLANA"),
+      createPinnedPlayer("2", 1, "CLANA"),
+      createPinnedPlayer("3", 1),
+      createPinnedPlayer("4", 0),
+    ];
+
+    const result = assignTeams(players, teams);
+
+    expect(result.get(players[0])).toEqual(ColoredTeams.Red);
+    expect(result.get(players[1])).toEqual(ColoredTeams.Blue);
+  });
+
+  it("should balance unpinned players around pinned ones", () => {
+    // Red already holds two pinned players (at capacity for 4 players /
+    // 2 teams), so the unpinned player must land on Blue.
+    const players = [
+      createPinnedPlayer("1", 0),
+      createPinnedPlayer("2", 0),
+      createPinnedPlayer("3", 1),
+      createPinnedPlayer("4", null),
+    ];
+
+    const result = assignTeams(players, teams);
+
+    expect(result.get(players[3])).toEqual(ColoredTeams.Blue);
+  });
+
+  it("should treat an out-of-range teamIndex as unpinned", () => {
+    const players = [
+      createPinnedPlayer("1", 7),
+      createPinnedPlayer("2", null),
+      createPinnedPlayer("3", null),
+      createPinnedPlayer("4", null),
+    ];
+
+    const result = assignTeams(players, teams);
+
+    for (const p of players) {
+      expect([ColoredTeams.Red, ColoredTeams.Blue]).toContain(result.get(p));
+    }
+  });
+
+  it("should pull an unpinned friend toward a pinned player's team", () => {
+    const players = [
+      createPinnedPlayer("1", 0),
+      createPinnedPlayer("2", null, undefined, ["1"]),
+      createPinnedPlayer("3", null),
+      createPinnedPlayer("4", null),
+    ];
+
+    const result = assignTeams(players, teams);
+
+    expect(result.get(players[1])).toEqual(ColoredTeams.Red);
+  });
+
+  it("should honor pins even past maxTeamSize (trust the matcher)", () => {
+    const players = [
+      createPinnedPlayer("1", 0),
+      createPinnedPlayer("2", 0),
+      createPinnedPlayer("3", 0),
+    ];
+
+    const result = assignTeams(players, teams, 1);
+
+    expect(result.get(players[0])).toEqual(ColoredTeams.Red);
+    expect(result.get(players[1])).toEqual(ColoredTeams.Red);
+    expect(result.get(players[2])).toEqual(ColoredTeams.Red);
+  });
+
   it("should still kick when every team is at capacity", () => {
     // 5 friends in a clique, 2 teams, maxTeamSize = ceil(5/2) = 3.
     // Total capacity is 6, so we have slack — nobody should get kicked.
diff --git a/tests/matchmaking/README.md b/tests/matchmaking/README.md
index 65bd2866a..cc84978e5 100644
--- a/tests/matchmaking/README.md
+++ b/tests/matchmaking/README.md
@@ -27,8 +27,16 @@ Prerequisite: `npm run dev` (app on :9000). No API worker needed.
 Real integration against the **API worker on `localhost:8787`**. Two browser
 players join the real queue through the real modal; the dev game server's
 `/matchmaking/checkin` long-poll receives the assignment and creates the
-game; the test asserts both players get the same `gameId` and dispatch
-`join-lobby` once the game exists.
+game; the test asserts all players get the same `gameId`, dispatch
+`join-lobby` once the game exists, that the game carries the mode's config,
+and that the `allowedPublicIds` allowlist admits every matched player.
+
+Modes:
+
+- default: 1v1 with two players
+- `MM_MODE=2v2 npm run test:matchmaking:e2e`: four players into the 2v2
+  queue; additionally rides the real flow into the started game and asserts
+  the in-game team split is 2 vs 2 and identical on every client.
 
 Prerequisites:
 
diff --git a/tests/matchmaking/contained.mjs b/tests/matchmaking/contained.mjs
index f169c26e8..298563b7d 100644
--- a/tests/matchmaking/contained.mjs
+++ b/tests/matchmaking/contained.mjs
@@ -74,16 +74,18 @@ try {
       const el = document.querySelector("matchmaking-modal");
       ${body}
     })()`);
-  const resetAndConnect = () =>
+  const resetAndConnect = (mode = "1v1") =>
     modal(`el.gameID = null;
       el.intentionalClose = false;
       el.reconnectAttempts = 0;
+      el.mode = ${JSON.stringify(mode)};
       el.connect();`);
 
   // 1. Joining the queue: connect -> join arrives (after the modal's 2s delay)
   await resetAndConnect();
   await joinCountReaches(1, 8000);
   c.check("join sent after connect", true);
+  c.check("1v1 join sends mode=1v1", (await joins())[0].mode === "1v1");
 
   // 2. Deploy/restart: server drops the socket abruptly -> reconnect + rejoin
   await control("kill");
@@ -132,6 +134,12 @@ try {
     "intentional close -> no message",
     (await page.evaluate(() => window.__mmMessages.length)) === msgsBefore,
   );
+
+  // 7. 2v2 queue: join carries mode=2v2
+  await resetAndConnect("2v2");
+  await joinCountReaches(7, 8000);
+  c.check("2v2 join sends mode=2v2", (await joins())[6].mode === "2v2");
+  await modal(`el.onClose();`);
 } finally {
   await browser.close();
   await fake.close();
diff --git a/tests/matchmaking/e2e.mjs b/tests/matchmaking/e2e.mjs
index 5396f041c..db7010d64 100644
--- a/tests/matchmaking/e2e.mjs
+++ b/tests/matchmaking/e2e.mjs
@@ -3,12 +3,16 @@
 //   - the dev app running on localhost:9000 (`npm run dev` — its game server
 //     long-polls the worker's /matchmaking/checkin out of the box in dev)
 //
-// Drives two real browser players through the real matchmaking modal:
-// both join the queue on the worker, the matcher pairs them, the local game
-// server receives the checkin assignment and creates the game, and both
-// clients see the game exist and dispatch join-lobby.
+// Drives real browser players through the real matchmaking modal: all join
+// the queue on the worker, the matcher groups them, the local game server
+// receives the checkin assignment and creates the game, and every client
+// gets into it (which also proves the allowedPublicIds allowlist accepts
+// the matched players).
 //
-// Run: npm run test:matchmaking:e2e
+// Run: npm run test:matchmaking:e2e            (1v1: two players)
+//      MM_MODE=2v2 npm run test:matchmaking:e2e (2v2: four players,
+//        also verifies the in-game team split is 2 vs 2 and identical on
+//        every client)
 
 import {
   gotoHome,
@@ -16,6 +20,9 @@ import {
 } from "../../.claude/skills/run-openfront/driver.mjs";
 import { isUp, makeChecker, waitFor } from "./util.mjs";
 
+const MODE = process.env.MM_MODE === "2v2" ? "2v2" : "1v1";
+const PLAYER_COUNT = MODE === "2v2" ? 4 : 2;
+
 if (!(await isUp("http://localhost:9000"))) {
   console.error(
     "Dev app is not running on :9000 — start it with `npm run dev`.",
@@ -29,13 +36,56 @@ if (!(await isUp("http://localhost:8787"))) {
   process.exit(1);
 }
 
-const { browser, page: page1 } = await launch();
-const context2 = await browser.newContext({
-  viewport: { width: 1400, height: 1000 },
-});
-const page2 = await context2.newPage();
+// Throttle rAF like the driver does for in-game work: software WebGL frames
+// are expensive and an unthrottled loop starves the sim/timers.
+const rafThrottle = (interval) => {
+  let last = 0;
+  window.requestAnimationFrame = (cb) => {
+    const now = performance.now();
+    const wait = Math.max(0, interval - (now - last));
+    return setTimeout(() => {
+      last = performance.now();
+      cb(last);
+    }, wait);
+  };
+  window.cancelAnimationFrame = (id) => clearTimeout(id);
+};
+
+// The app refuses software WebGL (initGL.ts gates on the renderer string and
+// failIfMajorPerformanceCaveat), but headless browsers only have SwiftShader.
+// We're verifying matchmaking/teams, not rendering, so let the context
+// through in the test pages.
+const glSpoof = () => {
+  const origGetContext = HTMLCanvasElement.prototype.getContext;
+  HTMLCanvasElement.prototype.getContext = function (type, attrs) {
+    if (type === "webgl2" && attrs) {
+      const rest = { ...attrs };
+      delete rest.failIfMajorPerformanceCaveat;
+      return origGetContext.call(this, type, rest);
+    }
+    return origGetContext.call(this, type, attrs);
+  };
+  const origGetParameter = WebGL2RenderingContext.prototype.getParameter;
+  WebGL2RenderingContext.prototype.getParameter = function (p) {
+    if (p === 0x9246 /* UNMASKED_RENDERER_WEBGL */) {
+      return "Harness Spoofed GPU";
+    }
+    return origGetParameter.call(this, p);
+  };
+};
+
+const { browser } = await launch();
+const pages = [];
+for (let i = 0; i < PLAYER_COUNT; i++) {
+  // One context per player: separate localStorage = distinct players.
+  const context = await browser.newContext({
+    viewport: { width: 1400, height: 1000 },
+  });
+  await context.addInitScript(rafThrottle, 2000);
+  await context.addInitScript(glSpoof);
+  pages.push(await context.newPage());
+}
 
-const pages = [page1, page2];
 const consoles = pages.map(() => []);
 pages.forEach((p, i) => p.on("console", (msg) => consoles[i].push(msg.text())));
 
@@ -51,20 +101,34 @@ const dumpConsoles = () => {
   );
 };
 
+// The dev game server runs NUM_WORKERS=2; the worker path is derived from
+// the gameId, so just probe both.
+const fetchGameInfo = async (gameId) => {
+  for (const worker of ["w0", "w1"]) {
+    const res = await fetch(
+      `http://localhost:9000/${worker}/api/game/${gameId}`,
+    );
+    if (res.ok) return res.json();
+  }
+  return null;
+};
+
 const c = makeChecker();
 try {
-  // Two contexts = separate localStorage = two distinct players.
   for (const p of pages) {
     await gotoHome(p);
-    await p.evaluate(() => {
+    await p.evaluate((mode) => {
       window.__joinLobby = null;
       document.addEventListener(
         "join-lobby",
         (e) => (window.__joinLobby = e.detail ?? {}),
       );
-      document.querySelector("matchmaking-modal").connect();
-    });
+      const el = document.querySelector("matchmaking-modal");
+      el.mode = mode;
+      el.connect();
+    }, MODE);
   }
+  console.log(`${PLAYER_COUNT} players queued (${MODE})...`);
 
   const gameIdOf = (p) =>
     p.evaluate(() => document.querySelector("matchmaking-modal").gameID);
@@ -79,15 +143,22 @@ try {
       {
         timeoutMs: 90000,
         intervalMs: 1000,
-        label: "both players to receive a match-assignment",
+        label: "every player to receive a match-assignment",
       },
     );
   } catch (err) {
     dumpConsoles();
     throw err;
   }
-  c.check(`both players received an assignment (${gameIds[0]})`, true);
-  c.check("both players got the same gameId", gameIds[0] === gameIds[1]);
+  const gameId = gameIds[0];
+  c.check(
+    `all ${PLAYER_COUNT} players received an assignment (${gameId})`,
+    true,
+  );
+  c.check(
+    "all players got the same gameId",
+    gameIds.every((id) => id === gameId),
+  );
 
   // The modal polls the game server until the assigned game exists, then
   // dispatches join-lobby — this proves the checkin/creation side worked.
@@ -97,19 +168,116 @@ try {
         const details = await Promise.all(
           pages.map((p) => p.evaluate(() => window.__joinLobby)),
         );
-        return details.every((d) => d?.gameID === gameIds[0]);
+        return details.every((d) => d?.gameID === gameId);
       },
       {
         timeoutMs: 45000,
         intervalMs: 1000,
-        label: "both players to dispatch join-lobby for the created game",
+        label: "every player to dispatch join-lobby for the created game",
       },
     );
-    c.check("game created on the game server and joinable by both", true);
+    c.check("game created on the game server", true);
   } catch (err) {
     dumpConsoles();
     throw err;
   }
+
+  // The game must carry the mode's config and admit exactly the matched
+  // players (allowedPublicIds).
+  const info = await fetchGameInfo(gameId);
+  if (MODE === "2v2") {
+    c.check(
+      "2v2 game config: Team mode, 2 teams, 4 max players, ranked 2v2",
+      info?.gameConfig?.gameMode === "Team" &&
+        info?.gameConfig?.playerTeams === 2 &&
+        info?.gameConfig?.maxPlayers === 4 &&
+        info?.gameConfig?.rankedType === "2v2",
+    );
+  } else {
+    c.check(
+      "1v1 game config: FFA, 2 max players",
+      info?.gameConfig?.gameMode === "Free For All" &&
+        info?.gameConfig?.maxPlayers === 2,
+    );
+  }
+  c.check(
+    `assignment allowlist has ${PLAYER_COUNT} publicIds`,
+    info?.gameConfig?.allowedPublicIds?.length === PLAYER_COUNT,
+  );
+
+  try {
+    await waitFor(
+      async () => {
+        const now = await fetchGameInfo(gameId);
+        return (now?.clients?.length ?? 0) === PLAYER_COUNT;
+      },
+      {
+        timeoutMs: 60000,
+        intervalMs: 1000,
+        label: "all matched players to pass the allowlist and join the game",
+      },
+    );
+    c.check("all matched players admitted past the allowlist", true);
+  } catch (err) {
+    console.error(
+      "game info at failure:",
+      JSON.stringify(await fetchGameInfo(gameId)),
+    );
+    for (const p of pages) {
+      console.error("page:", p.url());
+    }
+    dumpConsoles();
+    throw err;
+  }
+
+  if (MODE === "2v2") {
+    // Ride the real flow into the game and read the ground-truth team split
+    // from each client's GameView (see run-openfront skill notes).
+    const splitOf = (p) =>
+      p.evaluate(() => {
+        const g = document.querySelector("build-menu")?.game;
+        if (!g) return null;
+        try {
+          const humans = g.players().filter((pl) => pl.type() === "HUMAN");
+          if (humans.length < 4) return null;
+          return humans.map((pl) => `${pl.clientID()}:${pl.team()}`).sort();
+        } catch {
+          return null;
+        }
+      });
+
+    let splits;
+    try {
+      splits = await waitFor(
+        async () => {
+          const all = await Promise.all(pages.map(splitOf));
+          return all.every(Boolean) ? all : null;
+        },
+        {
+          timeoutMs: 120000,
+          intervalMs: 2000,
+          label: "every client to reach the started game with 4 humans",
+        },
+      );
+    } catch (err) {
+      dumpConsoles();
+      throw err;
+    }
+
+    const teamCounts = {};
+    for (const entry of splits[0]) {
+      const team = entry.split(":")[1];
+      teamCounts[team] = (teamCounts[team] ?? 0) + 1;
+    }
+    c.check(
+      `in-game team split is 2 vs 2 (${JSON.stringify(teamCounts)})`,
+      Object.values(teamCounts).sort().join(",") === "2,2",
+    );
+    c.check(
+      "team split is identical on every client (deterministic)",
+      splits.every((s) => JSON.stringify(s) === JSON.stringify(splits[0])),
+    );
+  }
 } finally {
   await browser.close();
 }
diff --git a/tests/matchmaking/fakeServer.mjs b/tests/matchmaking/fakeServer.mjs
index 4a0dd80b3..f435b6a4a 100644
--- a/tests/matchmaking/fakeServer.mjs
+++ b/tests/matchmaking/fakeServer.mjs
@@ -57,12 +57,21 @@ export async function startFakeMatchmakingServer() {
 
   const wss = new WebSocketServer({
     server,
-    // Real worker rejects a missing instance_id with HTTP 400 pre-upgrade.
-    verifyClient: ({ req }) =>
-      new URL(req.url, "http://localhost").searchParams.has("instance_id"),
+    // Real worker rejects a missing instance_id or an unknown mode with
+    // HTTP 400 pre-upgrade. mode is optional; omitted means 1v1.
+    verifyClient: ({ req }) => {
+      const params = new URL(req.url, "http://localhost").searchParams;
+      const mode = params.get("mode");
+      return (
+        params.has("instance_id") &&
+        (mode === null || mode === "1v1" || mode === "2v2")
+      );
+    },
   });
 
-  wss.on("connection", (ws) => {
+  wss.on("connection", (ws, req) => {
+    // Raw mode param (null when omitted) so tests can assert 1v1 omits it.
+    const mode = new URL(req.url, "http://localhost").searchParams.get("mode");
     ws.on("message", (raw) => {
       let msg;
       try {
@@ -71,7 +80,7 @@ export async function startFakeMatchmakingServer() {
         return;
       }
       if (msg.type !== "join") return;
-      state.joins.push({ jwt: msg.jwt, at: Date.now() });
+      state.joins.push({ jwt: msg.jwt, mode, at: Date.now() });
       if (state.rejectNextJoin) {
         state.rejectNextJoin = false;
         ws.close(1008, "Invalid session");