# Multiplayer by Default

**Page:** guides/multiplayer

[Download Raw Markdown](./guides/multiplayer.md)

---

# Multiplayer by Default

**For thirty years, "collaboration" on computers has meant taking turns.** Screen sharing where one person drives and everyone else watches. Pair programming where two people share one keyboard. Code reviews where changes move through a queue, one at a time.

Google Docs proved that real-time collaboration does not require turn-taking. Multiple cursors. Simultaneous editing. Instant visibility. It changed how the world writes documents.

Hoody does the same thing for entire computers.

Share a URL. Everyone is in. Multiple people in the same terminal, the same file system, the same database, the same browser, the same desktop. Not watching each other work — working together, simultaneously, in the same environment. One person in Hoody OS in the browser, another via `ssh hoody.com` on a plane — same workspace, same state, real-time.



This is not a feature we bolted on. It is the natural consequence of making everything HTTP. When every service is a URL, multiplayer is automatic. And when the OS itself runs on a container, sharing the OS is as natural as sharing any other URL.

---

## How Sharing Works

Every Hoody service has a URL. URLs are shareable by nature. That is the entire mechanism.

```
Your terminal:     https://PROJECT-CONTAINER-terminal-1.SERVER.containers.hoody.icu
Your display:      https://PROJECT-CONTAINER-display-1.SERVER.containers.hoody.icu
Your VS Code:      https://PROJECT-CONTAINER-code-1.SERVER.containers.hoody.icu
Your database:     https://PROJECT-CONTAINER-sqlite-1.SERVER.containers.hoody.icu
Your agent:        https://PROJECT-CONTAINER-workspaces-1.SERVER.containers.hoody.icu
```

Send any of those URLs to someone. They open it in their browser. They are now in your environment. No installation. No invitation system. No account creation at your end. No VPN. No SSH key exchange.


By default, containers are open -- anyone with the URL can access them. This is intentional. Collaboration should not require permission ceremonies. When you are ready for production, you add access controls. The order matters: open first, secure when ready.


---

## Multiplayer Terminals

Multiple people in the same terminal. Each person has a colored cursor. Everyone sees every keystroke in real-time.

### What It Looks Like

```
┌─────────────────────────────────────────────────┐
│ root@container:~#                               │
│                                                 │
│ $ npm test                     (Alice - blue)   │
│ Running 47 tests...                             │
│ ✓ All tests passed                              │
│                                                 │
│ $ git status                   (Bob - green)    │
│ On branch feature/auth                          │
│ modified: src/auth.ts                           │
│                                                 │
│ $ cat src/auth.ts              (Agent - orange) │
│ // AI reviewing the file...                     │
│                                                 │
└─────────────────────────────────────────────────┘
```

Three participants -- two humans and an AI agent -- in the same terminal session. Each with a distinct cursor color. Everyone sees everything. No one waits for a turn.

### Set It Up

There is nothing to set up. Open the terminal URL from multiple browsers:


  
    ```bash
    # Share the terminal URL -- that's the entire setup
    hoody containers get $CONTAINER_ID

    # Output:
    # URL: https://PROJECT-CONTAINER-terminal-1.SERVER.containers.hoody.icu
    # Status: running
    # Connected users: 0
    # Share this URL for multiplayer access
    ```
  
  
    ```typescript
    import { HoodyClient } from '@hoody-ai/hoody-sdk';

    const client = new HoodyClient({ baseURL: 'https://api.hoody.icu', token: process.env.HOODY_TOKEN });

    // Get the terminal URL
    const container = await client.api.containers.get(CONTAINER_ID);

    const terminalUrl = `https://${container.data.project_id}-${container.data.id}-terminal-1.${container.data.server_name}.containers.hoody.icu`;

    // Share this URL -- anyone who opens it joins the terminal session
    console.log('Share this URL:', terminalUrl);
    ```
  
  
    ```bash
    # Get container details to construct the terminal URL
    curl "https://api.hoody.icu/api/v1/containers/$CONTAINER_ID" \
      -H "Authorization: Bearer $HOODY_TOKEN"

    # The terminal URL is:
    # https://{project_id}-{container_id}-terminal-1.{server}.containers.hoody.icu
    # Share it. Anyone who opens it is in.
    ```
  


### Multiple Terminal Instances

Need separate terminal sessions for different tasks? Use instance numbers:

```
terminal-1  → Alice and Bob debug the backend together
terminal-2  → Carol and the AI agent work on the frontend
terminal-3  → Dave monitors logs independently
terminal-4  → Shared team standup terminal for commands
```

Each instance is a separate URL. Each is independently shareable. Each supports multiple simultaneous users.

---

## Shared Displays

Shared displays bring graphical application sharing to the same level. Multiple people see the same desktop, the same browser, the same GUI application -- and can interact with it simultaneously.

```
Display URL:  https://PROJECT-CONTAINER-display-1.SERVER.containers.hoody.icu

Alice sees:   The React app running in the container's Chrome
Bob sees:     The exact same view, in real-time
Carol clicks: A button in the app -- Alice and Bob see the result instantly
```

This is not screen sharing. There is no video feed, no compression artifacts, no lag from encoding. Everyone is connected to the same display server. The experience is identical for every participant.

### Use Cases for Shared Displays

**Live debugging:** Everyone sees the same browser. One person triggers the bug. Everyone watches the network tab, the console, the DOM simultaneously.

**Design review:** A designer opens Figma in the container's browser. The team reviews together, pointing at elements, making live changes.

**AI observation:** The agent runs browser automation in display-1 while the team watches. The agent navigates, clicks, fills forms. The team verifies the behavior is correct.

---

## Collaborative File Editing

hoody-code gives everyone VS Code in a browser. Multiple people editing the same codebase simultaneously.

```
https://PROJECT-CONTAINER-code-1.SERVER.containers.hoody.icu
```

Open this URL from different browsers. Each person gets a full VS Code instance connected to the same filesystem. File changes propagate instantly.


Unlike Google Docs where you see other cursors in the same document, hoody-code gives each user their own VS Code instance viewing the same filesystem. When Alice saves a file, Bob's instance picks up the change. This means you can work on different files simultaneously without conflict.


---

## Workspace Sharing

A hoody-workspace is a floating desktop that can display multiple containers and services in one view. Share a workspace URL and the entire layout -- terminals, displays, code editors, databases -- becomes a shared experience.

```
┌──────────────────────────────────────────────────────────────┐
│  SHARED WORKSPACE: "Team Dashboard"                          │
│                                                              │
│  ┌─────────────────────┐  ┌──────────────────────────────┐   │
│  │   Terminal-1         │  │   Display-1                  │   │
│  │   (Backend logs)     │  │   (App preview)              │   │
│  │                      │  │                              │   │
│  │   Alice & Bob here   │  │   Everyone sees this         │   │
│  └─────────────────────┘  └──────────────────────────────┘   │
│                                                              │
│  ┌─────────────────────┐  ┌──────────────────────────────┐   │
│  │   Code-1             │  │   SQLite-1                   │   │
│  │   (VS Code)          │  │   (Database browser)         │   │
│  │                      │  │                              │   │
│  │   Carol editing      │  │   Dave checking data         │   │
│  └─────────────────────┘  └──────────────────────────────┘   │
│                                                              │
└──────────────────────────────────────────────────────────────┘
```

One URL. Four services. Four participants. Everything in sync.

This is what Google Docs did for documents, applied to entire computing environments. The workspace is not a static screenshot -- it is a live, interactive, multiplayer operating system in your browser.

---

## Permission Layers

Open-by-default does not mean open-forever. When you are ready to control access, Hoody provides granular proxy permissions:


  
    ```bash
    # Set a password on the container
    # Writes are optimistic-concurrency guarded: pass the current file_version via --if-match
    hoody containers proxy permissions replace --container $CONTAINER_ID \
      --project $PROJECT_ID \
      --if-match "$(hoody containers proxy permissions get --container $CONTAINER_ID --field file_version)" \
      --groups '{"team": {"type": "password", "password": "team-access-2026"}}' \
      --permissions '{}'

    # Or restrict by IP (each IP group takes a single CIDR; add multiple groups for multiple ranges)
    hoody containers proxy permissions replace --container $CONTAINER_ID \
      --project $PROJECT_ID \
      --if-match "$(hoody containers proxy permissions get --container $CONTAINER_ID --field file_version)" \
      --groups '{"office-vpn": {"type": "ip", "range": "203.0.113.50/32"}, "office-lan": {"type": "ip", "range": "198.51.100.0/24"}}' \
      --permissions '{}'

    # Or use realm-based access tokens
    hoody containers proxy permissions replace --container $CONTAINER_ID \
      --project $PROJECT_ID \
      --if-match "$(hoody containers proxy permissions get --container $CONTAINER_ID --field file_version)" \
      --groups '{"realm": {"type": "token", "value": "'$REALM_TOKEN'"}}' \
      --permissions '{}'
    ```
  
  
    ```typescript
    import { HoodyClient } from '@hoody-ai/hoody-sdk';

    const client = new HoodyClient({ baseURL: 'https://api.hoody.icu', token: process.env.HOODY_TOKEN });

    // Writes need an If-Match precondition (the current file_version is returned
    // as a header by GET). Pass it via the `ifMatch` option, e.g. { ifMatch: 'file:v1' }.

    // Password protection
    await client.api.proxyPermissionsContainer.replace(CONTAINER_ID, {
      project: PROJECT_ID,
      container: CONTAINER_ID,
      groups: { team: { type: 'password', password: 'team-access-2026' } },
      permissions: { team: { terminal: true, files: true, display: true, http: true } },
      default: 'deny'
    }, { ifMatch: 'file:v1' });

    // Or IP restriction
    await client.api.proxyPermissionsContainer.replace(CONTAINER_ID, {
      project: PROJECT_ID,
      container: CONTAINER_ID,
      groups: {
        office_primary: { type: 'ip', range: '203.0.113.50/32' },
        office_subnet: { type: 'ip', range: '198.51.100.0/24' }
      },
      permissions: {
        office_primary: { terminal: true, files: true, display: true, http: true },
        office_subnet: { terminal: true, files: true, display: true, http: true }
      },
      default: 'deny'
    }, { ifMatch: 'file:v1' });
    ```
  
  
    ```bash
    # Password protection
    # Writes require an If-Match precondition (read the current file_version via GET first)
    curl -X PATCH "https://api.hoody.icu/api/v1/containers/$CONTAINER_ID/proxy/permissions" \
      -H "Authorization: Bearer $HOODY_TOKEN" \
      -H "Content-Type: application/json" \
      -H "If-Match: file:v1" \
      -d '{"project":"'$PROJECT_ID'","container":"'$CONTAINER_ID'","groups":{"team":{"type":"password","password":"team-access-2026"}},"permissions":{"team":{"terminal":true,"files":true,"display":true,"http":true}},"default":"deny"}'

    # Or IP restriction
    curl -X PATCH "https://api.hoody.icu/api/v1/containers/$CONTAINER_ID/proxy/permissions" \
      -H "Authorization: Bearer $HOODY_TOKEN" \
      -H "Content-Type: application/json" \
      -H "If-Match: file:v1" \
      -d '{"project":"'$PROJECT_ID'","container":"'$CONTAINER_ID'","groups":{"office_primary":{"type":"ip","range":"203.0.113.50/32"},"office_subnet":{"type":"ip","range":"198.51.100.0/24"}},"permissions":{"office_primary":{"terminal":true,"files":true,"display":true,"http":true},"office_subnet":{"terminal":true,"files":true,"display":true,"http":true}},"default":"deny"}'
    ```
  


**The progression:**

1. **Development** -- Wide open. Share the URL, everyone is in. Maximum collaboration velocity.
2. **Staging** -- Password protected. Team members know the password. External parties need to ask.
3. **Production** -- IP restricted or token-gated. Only authorized traffic reaches the services.

Permissions apply at the proxy level, which means they protect ALL services in the container simultaneously. Set once, enforced everywhere.

---

## Real-Time Collaboration Patterns

### Pattern 1: Pair Programming

Two developers. One container. Two browser tabs.

```
Developer A: Opens code-1 URL → Edits src/components/Header.tsx
Developer B: Opens code-1 URL → Edits src/components/Footer.tsx
Both:        Open terminal-1 URL → See each other's commands
Both:        Open display-1 URL → See the app update live
```

No screen sharing latency. No "let me take control." Both have full access to everything. The filesystem is the single source of truth.

### Pattern 2: Client Demo

Show a client the work-in-progress. Live. Interactive.

```
You:    Open workspace URL → Present the running application
Client: Opens the same URL → Clicks around, tests features, asks questions
You:    Open terminal-1 → Make live changes in response to feedback
Client: Sees changes immediately in display-1
```

The client does not install anything. They do not need an account. They open a URL in their browser. That is the entire onboarding process.

### Pattern 3: Team Debugging

Production issue. Everyone needs to see the same thing at the same time.

```
Lead:       Opens terminal-1 → Tails the error logs
Backend:    Opens terminal-2 → Queries the database for corrupted records
Frontend:   Opens display-1  → Reproduces the bug in the browser
DevOps:     Opens terminal-3 → Checks network configuration
Everyone:   Sees each other's terminals in the shared workspace
```

Four people. Four perspectives. One container. Real-time coordination without a single Zoom call.

### Pattern 4: AI + Human Collaboration

The most powerful pattern: humans and AI agents working together in the same container.


  
    ```bash
    # Start an AI task via the agent prompt endpoint
    curl -X POST "https://$PROJECT_ID-$CONTAINER_ID-workspaces-1.$SERVER.containers.hoody.icu/api/v1/agent/prompt/sync" \
      -H "Content-Type: application/json" \
      -d '{
        "parts": [{"type": "text", "text": "Implement the user profile page based on the design in /docs/profile-mockup.png"}],
        "autoApprove": true
      }'

    # While the agent works, you and your team observe in real-time:
    # terminal-1 URL → Watch the agent execute commands
    # code-1 URL     → Watch the agent write code
    # display-1 URL  → Watch the app update
    # agent-1 URL    → Chat with the agent, provide guidance
    ```
  
  
    ```typescript
    import { HoodyClient } from '@hoody-ai/hoody-sdk';

    const client = new HoodyClient({ baseURL: 'https://api.hoody.icu', token: process.env.HOODY_TOKEN });

    // Using raw fetch to show the HTTP surface directly.
    // The same endpoints are also available via client.agent.* in the SDK.
    const agentBase = `https://${PROJECT_ID}-${CONTAINER_ID}-workspaces-1.${SERVER}.containers.hoody.icu`;
    const response = await fetch(`${agentBase}/api/v1/agent/prompt/sync`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        parts: [{ type: 'text', text: 'Implement the user profile page based on the design in /docs/profile-mockup.png' }],
        autoApprove: true,
      }),
    });
    const result = await response.json();

    // Team observes via URLs:
    // terminal-1 → Agent commands in real-time
    // code-1     → Code changes as they happen
    // display-1  → App preview updates live
    // agent-1    → Chat interface for guidance
    ```
  
  
    ```bash
    # Start AI task
    curl -X POST "https://$PROJECT_ID-$CONTAINER_ID-workspaces-1.$SERVER.containers.hoody.icu/api/v1/agent/prompt/sync" \
      -H "Content-Type: application/json" \
      -d '{
        "parts": [{"type": "text", "text": "Implement the user profile page based on the design in /docs/profile-mockup.png"}],
        "autoApprove": true
      }'

    # Team watches via service URLs:
    # terminal-1.containers.hoody.icu  → Agent's commands
    # code-1.containers.hoody.icu      → Code changes
    # display-1.containers.hoody.icu   → Live preview
    # agent-1.containers.hoody.icu     → Chat with agent
    ```
  


The team watches the AI work. Someone notices a mistake and corrects the agent through the chat interface. Someone else opens the terminal and fixes a configuration issue the agent missed. The agent continues building, now on the right track. Human judgment and AI execution, simultaneously.

---

## Use Instance Numbers for Organization

When multiple people and agents share a container, use instance numbers to avoid stepping on each other:

```
terminal-1  → Team lead (oversight, commands)
terminal-2  → AI agent (automated execution)
terminal-3  → Backend developer (database queries)
terminal-4  → Frontend developer (build tools)

display-1   → App preview (shared)
display-2   → AI agent's browser automation (shared observation)

agent-1     → Primary AI agent (feature work)
agent-2     → Secondary AI agent (testing)

code-1      → Developer A's VS Code
code-2      → Developer B's VS Code
```

All instances share the same container filesystem and network. But each instance is a separate access point that can be independently shared.

---

## The Multiplayer Advantage

Traditional collaboration tools add layers on top of single-user systems. Hoody's multiplayer is not a layer -- it is the architecture itself.

| Traditional | Hoody |
|------------|-------|
| Install screen sharing software | Share the URL |
| One person drives at a time | Everyone has full control |
| Video encoding introduces lag | Direct HTTP connection, no encoding |
| Requires same time zone for effectiveness | Asynchronous access to the same URL |
| Setup per collaboration session | No setup ever -- URLs are permanent |
| Cannot share with AI agents | Agents use the same URLs as humans |

The URL IS the collaboration mechanism. There is nothing to configure, nothing to install, nothing to negotiate. Open the URL. You are in.

---

## What's Next

- **[Building a Full-Stack Application](/guides/full-stack-app/)** -- Build something together
- **[The Vibe Coding Revolution](/guides/vibe-coding/)** -- AI + human collaborative development
- **[Deploying Autonomous AI Agents](/guides/ai-agents/)** -- Multi-agent orchestration patterns
- **[Proxy Permissions](/foundation/proxy/permissions/)** -- Fine-grained access control