Understanding the relationship between Subjects, Events, Reports, and Queues is essential for using Ozone:

• Subjects: The target of an action. This can be an entire account or an individual piece of content (e.g., a post). Note that an account profile is a distinct subject from the account itself.
• Events: A record of something happening. Every event has a subject and a creator. Events include reports, actions (like adding labels), and workflow helpers (like escalation).
• Reports: A specific type of event, usually created by app users. A special type is an Appeal, where an account reports itself following a moderation intervention.
• Queues: Dynamic views of subjects based on state:
  • Unreviewed: Reported subjects with no resolution.
  • Escalated: Subjects flagged for additional team consideration.
  • Resolved: Subjects that have been reviewed and either acknowledged or acted upon.

Ozone is a labeling and moderation system for the atproto network, utilizing the tools.ozone.* Lexicon namespace. The system is built around four primary abstractions:

• Subjects: The target of moderation. This can be an entire account (referenced by a DID) or specific content (referenced by an AT-URI and optionally a CID). Note that an account profile record is considered a distinct subject from the account itself.
• Events: Records of actions taken within the system. Every event includes a subject (the target) and a creator (the account performing the action). Events can update a subject's state. Common events include reports, actions (like adding labels), escalations, and acknowledgements.
• Reports: A specific type of event, typically created by app users. A special subtype is an Appeal, which occurs when an account reports itself in response to a moderation decision.
• Queues: Dynamic lists of subjects in specific states, generated by querying the tools.ozone.moderation.querySubjects API endpoint.

A subject's current state is the result of all historical events applied to it. Ozone tracks several independent state properties:

reviewState

Tracks the lifecycle of a subject being reviewed. Possible values:

• reviewOpen: The default state for subjects with incoming reports. Reports are displayed in reverse chronological order.
• reviewEscalated: The subject has been flagged for review by higher-tier moderators.
• reviewClosed: The moderator has acknowledged the reports (with or without action). New reports will move the subject back to reviewOpen.
• reviewNone: Used for subjects with metadata (tags/comments) that do not require human review.

muted (Boolean)

Indicates if a subject is temporarily excluded from moderation queues to prevent clutter (e.g., from frequent re-reporting). Muted subjects only reappear after a selected period unless manually unmuted.

appealed (Boolean)

Indicates if the author of a subject has appealed a decision. An appeal automatically moves the reviewState to reviewOpen. A moderator must explicitly use the "Resolve Appeal" action to change this.

takendown (Boolean)

Indicates if a moderator has temporarily or permanently removed the subject. Temporary suspensions are automatically reversed after a set period.

The Ozone web interface is a collaborative tool for moderators to review reports, create labels, and inspect atproto content.

Logging In

Users log in using an atproto account with their handle and password. (Note: OAuth support is planned for future updates).

Basic Navigation

• Queues: Upon login, you will see a queue of un-reviewed reports. Other queues include escalated and resolved reports.
• Take Action Panel: Click the "Take Action" link in the upper-right to open a modal for reviewing a single subject. This panel allows you to view historical events, add/remove labels, and add team-private comments.
• Ctrl Panel: Press Ctrl-K or click the link in the left bar to open a quick search panel. You can paste a handle, bsky.app URL, or other identifier to quickly access reports or profile metadata.
• Account Profile View: Clicking a handle or username in the Take Action panel opens the Ozone account profile page, showing metadata like public DID PLC history, recent posts, and report history.

To develop Ozone locally, you must connect it to a running PDS (Personal Data Server) instance. The recommended approach is to use the dev-env from the atproto repository.

1. Start the atproto dev-env: In your atproto repository, run:

   yarn workspace @atproto/dev-env start

2. **Identify the Ozone service DID**: Look in the `dev-env` startup logs for a line indicating the Ozone service DID:
   `🗼 Ozone service DID did:plc:xxxxx`
3. **Configure Ozone**: Create a `.env.local` file in the Ozone project root and add the DID:
   ```env
   NEXT_PUBLIC_OZONE_SERVICE_DID=did:plc:xxxxx

4. Start Ozone: Run the development server:

   yarn dev

5. **Login**: Navigate to `http://localhost:3000`. Use the "Credentials" tab with the following test accounts:

| Role | Account Handle | Password | Service URL |
| :--- | :--- | :--- | :--- |
| Mod | `mod.test` | `mod-pass` | `http://localhost:2583` |
| Triage | `triage.test` | `triage-pass` | `http://localhost:2583` |
| Admin | `admin-mod.test` | `admin-mod-pass` | `http://localhost:2583` |

Step 1: Start atproto dev-env

yarn workspace @atproto/dev-env start

Step 3: Configure Ozone

echo "NEXT_PUBLIC_OZONE_SERVICE_DID=did:plc:xxxxx" > .env.local

Step 4: Start Ozone

yarn dev

The Account View includes an Email tab for communicating with accounts. Emails are sent via request to the account's PDS.

Email Templates

Templates are specific to the Ozone backend instance.

• Variables: Use double-brackets for auto-substitution, e.g., {{handle}}.
• Placeholders: Use triple-quotes for manual placeholders, e.g., ### DESCRIPTION OF IMAGE ###. The email will not be sent until these placeholders are replaced or an override is toggled.
• Privacy: The template name and any additional comments are saved in the event log for the team, but the recipient only sees the subject and body of the email.

Workflow

1. Navigate to the Email tab in the Account View.
2. Select a template or write free-form text.
3. Replace any manual placeholders if necessary.
4. Send the email (Note: Emails are not sent automatically as a result of other actions; they must be sent manually).

Follow these steps to install Ozone using Docker on Ubuntu:

1. Open Linux Firewall

If using ufw, allow HTTP and HTTPS traffic:

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

2. Install Docker

Uninstall old versions, set up the repository, and install Docker Engine and Docker Compose plugin as per the official Docker instructions for Ubuntu.

3. Set up Directories

Create the necessary directory structure for Ozone and its dependencies:

sudo mkdir /ozone
sudo mkdir /ozone/postgres
sudo mkdir --parents /ozone/caddy/data
sudo mkdir --parents /ozone/caddy/etc/caddy

4. Configure Caddy

Create a Caddyfile to handle TLS and reverse proxying. Replace ozone.example.com with your domain and ozone@example.com with your email.

cat <<CADDYFILE | sudo tee /ozone/caddy/etc/caddy/Caddyfile
ozone.example.com {
  tls ozone@example.com
  reverse_proxy http://localhost:3000
}
CADDYFILE

5. Configure Postgres and Ozone Environment Variables

Create /ozone/postgres.env with your POSTGRES_USER, POSTGRES_PASSWORD, and POSTGRES_DB.

Then, create /ozone/ozone.env. You must provide values for:

• OZONE_HOSTNAME
• OZONE_SERVICE_ACCOUNT_HANDLE
• OZONE_SERVER_DID (resolved via atproto identity API)
• OZONE_ADMIN_PASSWORD
• OZONE_SIGNING_KEY_HEX (a secp256k1 private key in hex format)
• OZONE_DB_POSTGRES_URL (using the credentials from your postgres.env)

6. Deploy with Docker Compose and Systemd

Download the compose.yaml file and create a systemd service to manage the containers.

# Download compose file
curl https://raw.githubusercontent.com/bluesky-social/ozone/main/service/compose.yaml | sudo tee /ozone/compose.yaml

# Create systemd service
cat <<SYSTEMD_UNIT_FILE | sudo tee /etc/systemd/system/ozone.service
[Unit]
Description=Bluesky Ozone Service
Documentation=https://github.com/bluesky-social/ozone
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/ozone
ExecStart=/usr/bin/docker compose --file /ozone/compose.yaml --profile daemon up --detach
ExecStop=/usr/bin/docker compose --file /ozone/compose.yaml --profile daemon down

[Install]
WantedBy=default.target
SYSTEMD_UNIT_FILE

# Start service
sudo systemctl daemon-reload
sudo systemctl enable ozone
sudo systemctl start ozone