> ## Documentation Index
> Fetch the complete documentation index at: https://hubify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Cross-Lab Data Sharing

> Enable the Lab Sovereignty Rule-compliant cross-lab read gateway. Share specific datasets and learnings with other labs without exposing private experiments.

# Cross-Lab Data Sharing

Hubify supports a read-only cross-lab gateway that lets you share specific datasets and knowledge with other labs while keeping private experiments fully isolated. This is governed by the Lab Sovereignty Rule: **a lab never has write access to another lab's data, and sharing is always opt-in and explicitly scoped.**

## What Can Be Shared

| Type                  | Shareable | Notes                                              |
| --------------------- | --------- | -------------------------------------------------- |
| Datasets              | Yes       | Any dataset you explicitly publish                 |
| Knowledge / learnings | Yes       | Summaries and insights, not raw experiment outputs |
| Figures               | Yes       | PNG/PDF figures from completed experiments         |
| Papers (drafts)       | Yes       | Set visibility to `shared` or `public`             |
| Experiments           | No        | Experiments are always private to the owning lab   |
| Agents / configs      | No        | Agent configuration is never shared                |
| Private notes         | No        | Captain-only content never leaves the lab          |

***

## Step 1: Enable Lab Sharing

Lab sharing is off by default.

<Tabs>
  <Tab title="Web UI">
    1. Go to **Settings** in the sidebar
    2. Select the **Lab** tab
    3. Under **Data Sharing**, toggle **Enable cross-lab read gateway** to on
    4. Set your sharing policy:
       * **Open**, any Hubify lab can query your shared datasets
       * **Approved only**, you approve each lab that requests access
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    # Enable sharing (open policy)
    hubify lab sharing enable --policy open

    # Enable sharing (approved-only policy)
    hubify lab sharing enable --policy approved
    ```
  </Tab>
</Tabs>

Once enabled, a read-only gateway endpoint becomes active for your lab at:

```
https://www.hubify.com/api/v1/labs/{your-lab-slug}/shared
```

***

## Step 2: Publish a Shared Dataset

Publishing a dataset makes it visible to other labs through the gateway. Unpublished datasets remain fully private.

<Tabs>
  <Tab title="Web UI">
    1. Go to **Data Explorer** in the sidebar
    2. Select the dataset you want to share
    3. Click **Publish to gateway**
    4. Set a description and optionally restrict to specific labs
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    # Publish a dataset to the gateway
    hubify dataset publish dataset-42 \
      --description "DESI Year 1 anomaly catalog, cross-matched with SIMBAD" \
      --visibility shared

    # Restrict to specific labs
    hubify dataset publish dataset-42 \
      --visibility restricted \
      --allow-labs "bigbounce2,partner-lab-slug"
    ```
  </Tab>
</Tabs>

Published datasets appear in:

* Your lab's public profile (if the lab is set to public)
* The cross-lab gateway endpoint
* Search results visible to approved labs

***

## Step 3: Query from Another Lab

To read shared data from another lab:

```bash theme={null}
# List what a lab has shared
hubify lab shared list bigbounce2

# Download a shared dataset
hubify lab shared fetch bigbounce2 --dataset "desi-anomaly-catalog-v1"

# Query a shared dataset
hubify lab shared query bigbounce2 \
  --dataset "desi-anomaly-catalog-v1" \
  --filter "novelty_fraction > 0.5"
```

In the web UI, go to **Data Explorer** → **Cross-Lab** tab to browse shared datasets from labs you have access to.

<Note>
  All cross-lab reads are logged in both the source lab's gateway log and your lab's activity feed. Neither lab can modify each other's data.
</Note>

***

## Step 4: Monitor Gateway Logs

Track all incoming and outgoing cross-lab activity:

```bash theme={null}
# View incoming reads to your shared gateway
hubify lab sharing logs --direction incoming

# View datasets you have fetched from other labs
hubify lab sharing logs --direction outgoing
```

In the web UI, go to **Settings** → **Lab** → **Sharing** → **Gateway logs**.

The log shows:

* Which lab read your data
* Which dataset was accessed
* Timestamp
* Number of records returned

***

## Sharing Knowledge and Learnings

Beyond datasets, you can share distilled knowledge from your lab's wiki and experiment learnings:

```bash theme={null}
# Publish a knowledge entry to the gateway
hubify knowledge publish knowledge-7 --visibility shared

# Publish all learnings tagged "cosmological-constraints"
hubify learnings publish --tag cosmological-constraints --visibility shared
```

Other labs can then import your learnings into their own knowledge base:

```bash theme={null}
# Import learnings from another lab
hubify learnings import bigbounce2 --tag cosmological-constraints
```

***

## Access Control

### Approving Lab Requests (Approved-Only Policy)

If your policy is `approved`, labs that try to access your gateway see a "Request Access" button. You review and approve each request:

```bash theme={null}
# View pending access requests
hubify lab sharing requests list

# Approve a lab
hubify lab sharing requests approve bigbounce2

# Revoke access
hubify lab sharing revoke bigbounce2
```

### Revoking a Published Dataset

```bash theme={null}
# Unpublish a dataset (removes from gateway immediately)
hubify dataset unpublish dataset-42
```

Unpublishing is immediate. Any other lab that has fetched the data locally retains their copy, but the live gateway endpoint returns 404 for new queries.

***

## Lab Sovereignty Rule

The Lab Sovereignty Rule is enforced at the API level:

1. **Read-only, always.** No lab can write, delete, or modify another lab's data.
2. **Explicit sharing only.** Nothing is shared by default. Every shared resource was explicitly published.
3. **Revocable.** You can unpublish any dataset or revoke any lab's access at any time.
4. **Logged.** Every cross-lab read is logged on both sides.

This rule cannot be disabled by settings or API calls. It is enforced in the Convex functions that handle cross-lab queries.