Why does this happen? The authentication worked, the session is valid, the user is authenticated, but the authorization failed.

This specific issue is called IDOR (Insecure Direct Object Reference). It’s one of the most common security bugs and is categorized under Broken Object Level Authorization (BOLA) in the OWASP API Security Top 10.

In this tutorial, you’ll learn:

• Why IDOR happens

• Why authentication alone is not enough

• How object-level authorization works

• How to fix IDOR properly in Next.js API routes

• How to design safer APIs from the start

Table of Content

• Table of Content

• Authentication vs. Authorization

• What is an IDOR Vulnerability?

• The Vulnerable Pattern in Next.js

• How to Handle IDOR in Next.js

  • Object-Level Authorization

• How to Design Safer Endpoints (/api/me)

• Mental Model for API Design

• Conclusion

Authentication vs. Authorization

Before writing further, let’s clarify something critical.

• Authentication answers: Who are you?

• Authorization answers: What are you allowed to access?

In IDOR scenarios, authentication works (the user is logged in), while authorization is missing or incomplete. That distinction is the core lesson of this article.

What is an IDOR Vulnerability?

An IDOR vulnerability happens when your API fetches a resource by an identifier (like a user ID), and then you do not verify that the requester owns or is allowed to access that resource.

Example of such a request:

GET /api/users/123

The code above is an HTTP GET request to the /api/users/123 route. The GET method is used to request data from the server. This indicates that the client is requesting a specific user with the ID 123 and this request returns the user data in a response (often in JSON format).

If your backend makes the request using a similar structure to the code snippet below without checking who is making the request, you have an IDOR vulnerability, even if the user is logged in.

db.user.findUnique({ where: { id: "123" } })

What the code does is to query the database for a single user record. The db.user part refers to the user model/table and findUnique() is a method that returns only one record based on a unique field. Inside the method, the where clause specifies the filter condition and { id: "123" } tells the database to find the user whose unique id equals "123". If a matching record exists, it returns that user object; otherwise, it returns null.

The Vulnerable Pattern in Next.js

Looking at this Next.js App Router API route:

// app/api/users/[id]/route.ts
import { NextResponse } from "next/server";
import { db } from "@/lib/db";

export async function GET(
  req: Request,
  { params }: { params: { id: string } }
) {
  const user = await db.user.findUnique({
    where: { id: params.id },
    select: { id: true, email: true, name: true },
  });

  return NextResponse.json({ user });
}

Before going to the implication of this code snippet, let's understand what the code does. It defines a dynamic API route for /api/users/[id]. The exported GET function is an async route handler that runs when a GET request is made to this endpoint. It receives the request object and a params object, where params.id contains the dynamic [id] in the URL segment. The db.user.findUnique() method queries the database for a user whose id matches params.id, and the select option limits the returned fields to id, email, and name. Finally, NextResponse.json() sends the retrieved user data back to the client as a JSON response.

Now, to the implication, the code is a bad approach because the route accepts a user ID from the URL, fetches that user directly from the database, and returns the result. There is no session validation, no ownership check, and no role check.

If a logged-in user changes the id in the URL, they may access other users’ data. This is simply IDOR.

How to Handle IDOR in Next.js

The first element of defense is verifying identity. We’ll use getServerSession from NextAuth (adjust if using another auth provider). This change ensures that you read the session from the cookies, verify it on the server side, and ensure the user has a valid ID. This prevents unauthenticated access.

// lib/auth.ts
import { getServerSession } from "next-auth";
import { authOptions } from "@/lib/authOptions";

export async function requireSession() {
  const session = await getServerSession(authOptions);

  if (!session?.user?.id) {
    return null;
  }

  return session;
}

The code above defines an authentication helper function called requireSession. The getServerSession(authOptions) function retrieves the current user session on the server using the provided authentication configuration. The optional chaining (session?.user?.id) in the if block that follows safely checks whether a logged-in user and their id exist. If no valid session or user ID is found, the function returns null, indicating the request is unauthenticated. Otherwise, it returns the full session object so it can be used in protected routes or server logic.

You have successfully confirmed that the user and session exist; now, update the route:

export async function GET(
  req: Request,
  { params }: { params: { id: string } }
) {
  const session = await requireSession();

  if (!session) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  const user = await db.user.findUnique({
    where: { id: params.id },
    select: { id: true, email: true, name: true },
  });

  return NextResponse.json({ user });
}

The fix is incomplete yet, but in the above code, you’ve prevented anonymous access. The GET handler calls the requireSession() that was created earlier to verify that the request is authenticated. If no valid session is returned, it immediately responds with a JSON error message and a 401 Unauthorized HTTP status. If the user is authenticated, it proceeds to call db.user.findUnique() to fetch the user whose id matches params.id, selecting only the id, email, and name fields. Finally, it returns the retrieved user data as a JSON response using NextResponse.json().

Something is still missing. Can you guess? Any authenticated user can still request any resource by changing the URL path to the request they want. How? This leads us to object-level authorization.

Object-Level Authorization

An object-level authorization ensures that a user can only access their own data (unless explicitly permitted).

The improvement to the code would be to add an ownership check. The adjustment ensures the API request checks if the requester is authenticated and owns the requested object. If either fails, access is denied.

export async function GET(
  req: Request,
  { params }: { params: { id: string } }
) {
  const session = await requireSession();

  if (!session) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  if (session.user.id !== params.id) {
    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
  }

  const user = await db.user.findUnique({
    where: { id: params.id },
    select: { id: true, email: true, name: true },
  });

  return NextResponse.json({ user });
}

Let's take a look at what happened in the code, the GET handler first authenticates the request using requireSession(), returning a 401 response if no valid session exists. It then performs an authorization check by comparing session.user.id with params.id. If they do not match, it returns a 403 Forbidden response, preventing users from accessing other users’ data. If both checks pass, it queries the database using db.user.findUnique() to retrieve the specified user and limits the result to selected fields. Finally, it sends the user data back as a JSON response. With this, you’ve enforced an object-level authorization.

How to Design Safer Endpoints (/api/me)

The safest approach in designing your endpoint is to eliminate the risk entirely. Instead of allowing users to specify IDs (/api/users/:id), use /api/me, because the server already knows the user’s identity from the session.

// app/api/me/route.ts
export async function GET() {
  const session = await requireSession();

  if (!session) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  const user = await db.user.findUnique({
    where: { id: session.user.id },
    select: { id: true, email: true, name: true },
  });

  return NextResponse.json({ user });
}

This approach makes sure that your API only returns data for the currently authenticated user. It first calls requireSession() to ensure the request is authenticated, returning a 401 response if no session exists. Instead of using a URL parameter, it reads the user’s ID directly from session.user.id, ensuring the user can only access their own data. It then calls db.user.findUnique() to retrieve that user from the database, selecting only specific fields, and returns the result as a JSON response.

You can be confident with this approach because the client cannot manipulate user IDs. The server gets the user identity from a trusted source, and the attack surface is reduced. This is called secure-by-design API model.

Now, you should clearly understand that authentication does not imply authorization. Hence,

• IDOR occurs when object ownership is not verified

• Every API route that accepts an ID must validate access

• Safer API design reduces vulnerability surface

• Authorization must always run on the server

Mental Model for API Design

When writing any API route, answer these questions:

1. Who is making this request?

2. What object are they requesting?

3. Does policy allow them to access it?

If you cannot clearly answer all three, your route may be vulnerable.

Conclusion

IDOR vulnerabilities happen when APIs trust user-supplied identifiers without verifying ownership or permission.

To prevent them in Next.js, authenticate every private route, enforce object-level authorization, centralize authorization logic, and write tests for forbidden access.

Security is not about adding logins, it’s about enforcing security policy on every object access.

Firebase makes this possible with custom claims and security rules. In this article, you’ll learn how to:

• Add custom claims to users with the Firebase Admin SDK.

• Use Firebase Security Rules to enforce RBAC.

• Test your rules with different roles.

By the end, you’ll have a working setup where roles like admin and user are enforced directly in Firestore.

Table of Contents

• Step 1: Understand Firebase Custom Claims

• Step 2: Assign a Role with the Firebase Admin SDK

• Step 3: Write and Enforce Firestore Security Rules

• Step 4: Build the Frontend with Next.js and Firebase

• Step 5: Test the RBAC Workflow

• Conclusion

Prerequisites

To follow along, you should:

• Have a Firebase project set up with Authentication and Firestore enabled.

• Be comfortable with JavaScript/Node.js.

• Have the Firebase SDK and Admin SDK installed.

If you’re new to Firebase, check out the official setup guide before continuing.

Step 1: Understand Firebase Custom Claims

Firebase custom claims allow you to attach extra information (like a role) to a user’s authentication token. You set this information server-side using the Admin SDK. They are included in the user’s request.auth.token, and you can’t set them directly from the client (for security reasons).

Here’s an example: a user’s ID token might look like this after a claim is added:

{
  "user_id": "abc123",
  "email": "jane@example.com",
  "role": "admin"
}

In this example, the role field determines access privileges in your application. Firebase automatically includes this claim in the user’s ID token, so it can be securely validated both on the server and in Firestore rules.

Step 2: Assign a Role with the Firebase Admin SDK

The Firebase Admin SDK allows you to manage users and assign roles securely from your backend (or through a script).

First, install the Admin SDK in a Node environment (not in your frontend app):

npm install firebase-admin

Then initialize it with your Firebase service account credentials:

const admin = require("firebase-admin");
const serviceAccount = require("./service-account.json");

admin.initializeApp({
  credential: admin.credential.cert(serviceAccount),
});

To get your service-account.json file, navigate to your firebase settings > project settings > service account.

Click on Generate private key, and it will automatically download the JSON file. You can rename the file or use it as it is.

You can now define a simple function to set a user’s role:

async function setUserRole(uid, role) {
  await admin.auth().setCustomUserClaims(uid, { role });
  console.log(`Role ${role} assigned to user ${uid}`);
}

The role parameter can be anything you define, for example:

• "admin": Full read/write access.

• "editor": Can create or modify limited content.

• "user": Read-only access.

The role you assign to a user depends on your app’s needs. In most applications, you’ll start simple, perhaps just admin and user and expand over time.

Usage example:

Once you’ve defined the function, call it with a user’s UID:

setUserRole("USER_UID_HERE", "admin");

This securely attaches a custom claim to the user.

Note: The user must log out and log back in (or refresh their token) for the new claim to take effect.

Step 3: Write Firestore Security Rules for RBAC

Firestore Security Rules control how your data can be read or written. They are executed before any client request reaches your database, ensuring that your security logic isn’t bypassed.

Open your Firestore Rules (firestore.rules) and define role-based access like this:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {

    match /posts/{postId} {
      // Anyone logged in can read
      allow read: if request.auth != null;

      // Only admins can write
      allow write: if request.auth.token.role == "admin";
    }
  }
}

Here’s what’s happening:

• request.auth != null: ensures the user is logged in.

• request.auth.token.role == "admin": Grants write access only to users with the admin role.

You can expand this for multiple roles:

allow write: if request.auth.token.role in ["admin", "editor"];

Quick Reference

Keep these points in mind when managing Firebase RBAC:

• Keep your roles simple (for example, admin, editor, user). Don’t overcomplicate.

• Don’t store roles in Firestore documents. Enforce via custom claims instead.

• Always test rules locally before deploying.

• Remember that users must refresh their tokens after claims are updated.

Step 4: Build the Frontend with Next.js and Firebase

Let’s bring this to life with a working demo using Next.js and Firebase.

firebase-rbac/
├── firebase-admin-scripts/       # Server-side scripts for setting user roles
│   ├── assignRole.js             # Uses Firebase Admin SDK to assign custom claims
│   ├── .env                      # Contains service account path and test UID
│   └── fir-rbac-...json          # Firebase Admin SDK service account json file
│
├── src/
│   ├── app/
│   │   ├── page.js               # Main Next.js page for login + post display
│   │   ├── layout.js             # Global layout
│   │   └── globals.css           # Tailwind global styles
│   └── lib/
│       └── firebase.js           # Firebase client initialization
│
├── .env.local                    # Firebase web config (NEXT_PUBLIC_ variables)
├── package.json
└── README.md

In your .env.local, complete these variables with your Firebase project config information:

NEXT_PUBLIC_FIREBASE_API_KEY=your-api-key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your-project-id.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your-project-id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your-project-id.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your-sender-id
NEXT_PUBLIC_FIREBASE_APP_ID=your-app-id

Firebase Initialization (src/lib/firebase.js):

import { initializeApp, getApps, getApp } from "firebase/app";
import { getAuth } from "firebase/auth";
import { getFirestore } from "firebase/firestore";

const firebaseConfig = {
  apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
  authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN,
  projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID,
  storageBucket: process.env.NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET,
  messagingSenderId: process.env.NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID,
  appId: process.env.NEXT_PUBLIC_FIREBASE_APP_ID,
};

const app = initializeApp(firebaseConfig);
export const auth = getAuth(app);
export const db = getFirestore(app);

Demo Component (src/app/page.js):

This component lets you log in, view posts, and, if you’re an admin, create new posts.

"use client";

import { useState, useEffect } from "react";
import { auth, db } from "@/lib/firebase";
import {
  signInWithEmailAndPassword,
  onAuthStateChanged,
  signOut,
} from "firebase/auth";
import { collection, getDocs, addDoc } from "firebase/firestore";

export default function Page() {
  const [user, setUser] = useState(null);
  const [email, setEmail] = useState("");
  const [password, setPassword] = useState("");
  const [posts, setPosts] = useState([]);
  const [newPost, setNewPost] = useState("");

  useEffect(() => {
    const unsubscribe = onAuthStateChanged(auth, async (u) => {
      setUser(u);
      if (u) await loadPosts();
      else setPosts([]);
    });
    return () => unsubscribe();
  }, []);

  const loadPosts = async () => {
    const snapshot = await getDocs(collection(db, "posts"));
    setPosts(snapshot.docs.map((doc) => ({ id: doc.id, ...doc.data() })));
  };

  const handleLogin = async (e) => {
    e.preventDefault();
    try {
      await signInWithEmailAndPassword(auth, email, password);
      alert("Logged in!");
      setEmail("");
      setPassword("");
    } catch (error) {
      console.error("Login failed:", error.message);
      alert("Login failed: " + error.message);
    }
  };

  const handleLogout = async () => {
    await signOut(auth);
    setUser(null);
  };

  const handleAddPost = async () => {
    try {
      await addDoc(collection(db, "posts"), { text: newPost });
      setNewPost("");
      await loadPosts();
      alert("New Post added!");
    } catch (e) {
      alert("Opps!! Only admins can add posts.");
      console.error(e.message);
    }
  };

  return (
    <main className="min-h-screen flex flex-col items-center justify-center bg-gray-900 text-gray-100 px-4">
      <div className="w-full max-w-md bg-gray-800 rounded-2xl shadow-lg p-8 space-y-6">
        <h1 className="text-2xl font-bold text-center text-indigo-400">
          Firebase RBAC Demo (Next.js)
        </h1>

        {/* Login Form */}
        {!user ? (
          <form onSubmit={handleLogin} className="space-y-4">
            <div>
              <label className="block text-gray-300 text-sm mb-1">Email</label>
              <input
                type="email"
                value={email}
                onChange={(e) => setEmail(e.target.value)}
                placeholder="you@example.com"
                required
                className="w-full px-3 py-2 rounded-md bg-gray-700 border border-gray-600 text-gray-100 focus:outline-none focus:ring-2 focus:ring-indigo-400"
              />
            </div>

            <div>
              <label className="block text-gray-300 text-sm mb-1">
                Password
              </label>
              <input
                type="password"
                value={password}
                onChange={(e) => setPassword(e.target.value)}
                placeholder="••••••••"
                required
                className="w-full px-3 py-2 rounded-md bg-gray-700 border border-gray-600 text-gray-100 focus:outline-none focus:ring-2 focus:ring-indigo-400"
              />
            </div>

            <button
              type="submit"
              className="w-full px-6 py-2 rounded-lg bg-indigo-600 hover:bg-indigo-500 transition font-medium text-white"
            >
              Login
            </button>
          </form>
        ) : (
          <div className="space-y-6">
            <div className="flex flex-col items-center">
              <p className="text-gray-300 mb-2">
                Logged in as{" "}
                <span className="font-semibold text-indigo-400">
                  {user.email}
                </span>
              </p>
              <button
                onClick={handleLogout}
                className="text-sm text-red-400 hover:text-red-300 underline"
              >
                Logout
              </button>
            </div>

            <section className="border-t border-gray-700 pt-4">
              <h2 className="text-lg font-semibold text-indigo-300 mb-3">
                Posts
              </h2>

              {posts.length > 0 ? (
                <ul className="space-y-2">
                  {posts.map((p) => (
                    <li
                      key={p.id}
                      className="bg-gray-700 rounded-md px-3 py-2 text-gray-200"
                    >
                      {p.text}
                    </li>
                  ))}
                </ul>
              ) : (
                <p className="text-gray-400 italic">No posts yet.</p>
              )}

              <div className="mt-4 flex items-center gap-2">
                <input
                  value={newPost}
                  onChange={(e) => setNewPost(e.target.value)}
                  placeholder="New post"
                  className="flex-1 px-3 py-2 rounded-md bg-gray-700 border border-gray-600 text-gray-100 focus:outline-none focus:ring-2 focus:ring-indigo-400"
                />
                <button
                  onClick={handleAddPost}
                  className="px-4 py-2 rounded-md bg-indigo-600 hover:bg-indigo-500 transition font-medium text-white"
                >
                  Add
                </button>
              </div>
            </section>
          </div>
        )}
      </div>

      <footer className="mt-8 text-gray-500 text-sm">
        Built with Next.js + Firebase | &copy; FreeCodeCamp 2025
      </footer>
    </main>
  );
}

Step 5: Test the RBAC Workflow

Now that everything is set up, it’s time to test the entire Role-Based Access Control flow to ensure your rules and roles are working correctly.

Enable Authentication

Head over to your Firebase Console, select your project, and navigate to Authentication then Sign-in method. Select Add New Provider. Then enable Email/Password authentication. This will let you create and sign in with test users directly from your app.

Configure Firestore Rules

Next, you’ll need to update the Firestore rules. Navigate to Firestore Database, located in the build drop-down. Once you’re there, click on Rules where you will be able to update the rules.

Replace the default rules with the RBAC rules you defined earlier. These rules ensure that only authenticated users can read data, and only admins can create or modify posts.

Then publish the updated version and you are good to go.

Assign a Role to a User

To test admin permissions, assign an admin role to one of your test users. Open your terminal, change into the firebase-admin-scripts directory, and run:

cd firebase-admin-scripts
node assignRole.js

This executes the Admin SDK script that adds a custom claim to your test user. Once the role is set, you’ll get a message confirming that the admin role has been assigned to the specified user ID.

If the user is logged in already, the user must log out and log back in for the new role to take effect.

Run the App

Now you can start your Next.js development server:

npm run dev

Visit http://localhost:3000 in your browser. You should find the Firebase RBAC demo app.

Verify Role-Based Access

Try logging in as the user who was assigned the admin role. Once logged in, you should be able to create new posts successfully. Next, log in as a regular user. You’ll notice that you can view existing posts, but any attempt to add a new post will fail with a “Permission denied” alert.

If you see these behaviors, then your RBAC system is working as intended!

By enforcing permissions at the Firestore layer, you ensure that security is handled centrally and can’t be bypassed by manipulating the client-side code. This approach keeps your app secure and scalable, even as your roles and data grow more complex.

Next steps:

• Add more roles (like editor, and more as you wish).

• Combine RBAC with document-level validation for fine-grained control.

• Explore Firebase’s security rules.

Conclusion

You just learned a simple but important role-based access control (RBAC) functionality in Firebase. In this guide, we covered custom claims and how to set roles using the Admin SDK. You also learned how to enforce those roles in Firestore security rules.

If you try to run a Python GUI library like Pygame, Tkinter, or PyQt inside Codespaces, you’ll get an error. That’s because Codespaces runs in a headless environment. There’s no physical display for your app to open a window on.

In this article, I’ll show you how to fix that. You’ll learn how to set up a virtual desktop using Xvfb and stream it into your browser using noVNC. By the end, you’ll be able to run any Python GUI application inside GitHub Codespaces.

Table of Contents

• Why Codespaces Needs Extra Setup for GUIs

• Step 1: Create the Repo and Open Codespace

• Step 2: Add the Setup Script

• Step 3: Start the GUI Environment

• Step 4: Open the noVNC Desktop

• Step 5: Run Your Python GUI App

• Tips

• Conclusion

Prerequisites

Before you start, you should have:

• A GitHub account and access to GitHub Codespaces.

• Basic familiarity with Python.

• A Python GUI app to test (we’ll use a small Pygame example).

Why Codespaces Needs Extra Setup for GUIs

When you run GUI code like:

import pygame
pygame.display.set_mode((800, 600))

On your local machine, Python tells your operating system to create a window. But Codespaces runs on a server with no monitor attached. Without a display, your GUI app cannot render.

That’s where Xvfb (X virtual framebuffer) comes in. It simulates a display in memory, so GUI programs think they’re running on a real screen. To make that screen visible in the browser, you can use noVNC, which streams the virtual display through a web client.

Together, Xvfb and noVNC turn Codespaces into a cloud-based desktop for GUI apps.

Step 1: Create the Repo and Open Codespace

First, create a GitHub repository for your project (or a demo repo) and open it in Codespaces:

Step 2: Add the Setup Script

Create a file called start-gui.sh in the root of your project.

Paste the following code into the start-gui.sh file:

#!/usr/bin/env bash
set -e

echo "Installing dependencies..."
sudo apt-get update -y
sudo apt-get install -y xvfb x11vnc fluxbox websockify novnc

echo "Starting virtual display..."
Xvfb :1 -screen 0 1024x768x24 &
export DISPLAY=:1
fluxbox &

echo "Starting VNC server..."
x11vnc -display :1 -nopw -forever -shared -rfbport 5900 &

echo "Starting noVNC on port 6080..."
websockify --web=/usr/share/novnc 6080 localhost:5900 &

echo ""
echo "GUI environment is ready!"
echo "Go to the Ports tab, set port 6080 to Public, and open the link."

Let’s explain this script so you can understand what it does:

set -e

• This tells the shell to exit immediately if any command fails.

• Without it, the script would keep running even if something goes wrong (like a failed install).

Installing Dependencies

sudo apt-get update -y: updates your package list.

sudo apt-get install -y ⁣installs the packages we listed (xvfb, x11vnc, fluxbox, websockify, and novnc)

• • xvfb: creates a “dummy” display (virtual screen in memory).

    • x11vnc: shares that dummy display via the VNC protocol.

    • Fluxbox: a lightweight window manager, so the desktop has a GUI environment.

    • websockify: converts VNC traffic into WebSockets so it can run in a browser.

    • novnc: provides a browser client to connect to the desktop.

Virtual Display

• Xvfb :1 -screen 0 1024x768x24 &: Starts the virtual framebuffer on display :1 with resolution 1024x768 and 24-bit color.

• export DISPLAY=:1: tells apps (like Python GUIs) to draw on this virtual screen instead of looking for a real display unit.

• fluxbox &: launches the window manager so GUI apps have a desktop to sit in.

VNC Server

• x11vnc -display :1: connects you to the dummy display (:1).

• -nopw: ensures that no password is required.

• -forever: this keeps the VNC running even if clients disconnect.

• -shared: allows multiple clients.

• -rfbport 5900: exposes the internal server on VNC’s standard port.

noVNC Server

• websockify acts as a bridge that converts WebSocket traffic to VNC protocol (on port 5900).

• --web=/usr/share/novnc: serves the noVNC web client files.

• 6080: the port where you’ll connect in your browser (this is publicly accessible).

• localhost:5900:forwards traffic to the VNC server that was started earlier.

You should only expose port 6080 (noVNC) as Public and keep 5900 (raw VNC) private because:

• Prt 5900 (VNC) uses the raw VNC protocol, which is not encrypted and doesn’t require a password in this setup. If exposed, anyone could connect directly and control your Codespace desktop.

• Prt 6080 (noVNC) runs over WebSockets + HTTPS, so traffic is encrypted and secured through GitHub Codespaces’ connection. It also only serves the noVNC web client, not the raw VNC protocol.

5900 = unsafe to expose, 6080 = browser-safe way to view the GUI.

The next step is for you to make the bash file executable by running the code below in the terminal:

chmod +x start-gui.sh

Step 3: Start the GUI Environment

Run the script:

./start-gui.sh

This will:

1. Install all dependencies (Xvfb, fluxbox, x11vnc, novnc).

2. Start a virtual display (DISPLAY=:1).

3. Launch a lightweight window manager (fluxbox).

4. Stream the desktop to your browser via noVNC on port 6080.

Step 4: Open the noVNC Desktop

1. In Codespaces, open the Ports tab.

2. Find port 6080 and change its visibility to public. (right-click on the private word)

3. Open the URL in a new browser tab.

4. Click vnc.html or vnc_auto.html if prompted.

   

You should now see a lightweight Linux desktop running inside your browser.

Step 5: Run Your Python GUI App

In a new Codespaces terminal, run:

export DISPLAY=:1
python3 your_script.py

Your Python GUI app should appear inside the noVNC desktop 🎉.

For example, here’s a simple Pygame script test.py:

import pygame
from pygame import display, font, event
from pygame.locals import *

# Setup display
pygame.init()
screen = display.set_mode()
display.set_caption("Capstone 2")
myFont = font.SysFont('arial', 12)  # Choose a font to use in game

# Directions displayed throughout game
directions = "Please press the 'Y' key for yes and the 'N' key for no."

# Counts how many questions have been asked
currentQuestion = 0


# Determines which question to ask
def story(answer, count):
    screen.fill("white")
    if count == 0:
        question1(answer)
    elif count == 1:
        question2(answer)
    elif count == 2:
        question3(answer)
    elif count == 3:
        end(answer)


# Displays the first part of the story
def intro():
    # Break up the string into multiple variables because there isn't text wrapping in Pygame
    intro1 = "Once upon a time lived a brave hero named Anya."
    intro2 = "She lived a simple life in a small village, making biscuits for the village people."
    intro3 = "One day, late at night, she hears a loud noise outside the village."
    q1 = "Should she go outside to investigate? Yes or no?"

    screen.fill("white")
    textSurface = myFont.render(intro1, True, "black")
    screen.blit(textSurface, (10, 10))
    textSurface = myFont.render(intro2, True, "black")
    screen.blit(textSurface, (10, 24))
    textSurface = myFont.render(intro3, True, "black")
    screen.blit(textSurface, (10, 38))
    textSurface = myFont.render(q1, True, "black")
    screen.blit(textSurface, (10, 52))
    textSurface = myFont.render(directions, True, "black")
    screen.blit(textSurface, (10, 66))


# First question
def question1(answer):
    if answer == K_y:
        yes1 = "She ventures into the dark, prepared for danger."
        yes2 = "Eventually, she sees an army of ogres coming toward her village!"
        q2 = "Should she fight the ogres? Yes or no?"

        textSurface = myFont.render(yes1, True, "black")
        screen.blit(textSurface, (10, 10))
        textSurface = myFont.render(yes2, True, "black")
        screen.blit(textSurface, (10, 24))
        textSurface = myFont.render(q2, True, "black")
        screen.blit(textSurface, (10, 38))
        textSurface = myFont.render(directions, True, "black")
        screen.blit(textSurface, (10, 52))

    elif answer == K_n:
        no1 = "She chooses the safety of her home and stays inside."
        no2 = "However, the sounds do not go away."
        no3 = "She can tell something is very wrong..."
        no4 = "Eventually, she sees an army of ogres coming toward her village!"
        q2 = "Should she fight the ogres? Yes or no?"

        textSurface = myFont.render(no1, True, "black")
        screen.blit(textSurface, (10, 10))
        textSurface = myFont.render(no2, True, "black")
        screen.blit(textSurface, (10, 24))
        textSurface = myFont.render(no3, True, "black")
        screen.blit(textSurface, (10, 38))
        textSurface = myFont.render(no4, True, "black")
        screen.blit(textSurface, (10, 52))
        textSurface = myFont.render(q2, True, "black")
        screen.blit(textSurface, (10, 66))
        textSurface = myFont.render(directions, True, "black")
        screen.blit(textSurface, (10, 80))


# Second question
def question2(answer):
    if answer == K_y:
        yes1 = "She bravely confronts the ogres, hoping to protect her village from harm."
        textSurface = myFont.render(yes1, True, "black")
        screen.blit(textSurface, (10, 10))

    elif answer == K_n:
        no1 = "The ogres raid the village but Anya manages to escape with her life."
        textSurface = myFont.render(no1, True, "black")
        screen.blit(textSurface, (10, 10))

    story2 = "The ogres decide to leave but she knows they will be back."
    story3 = "Anya decides to talk with a village elder about what she should do."
    story4 = "The elder says there is a powerful sword hidden in the Ancient Forest."
    q3 = "Should Anya risk her life to retrieve it? Yes or no?"

    textSurface = myFont.render(story2, True, "black")
    screen.blit(textSurface, (10, 24))
    textSurface = myFont.render(story3, True, "black")
    screen.blit(textSurface, (10, 38))
    textSurface = myFont.render(story4, True, "black")
    screen.blit(textSurface, (10, 52))
    textSurface = myFont.render(q3, True, "black")
    screen.blit(textSurface, (10, 66))
    textSurface = myFont.render(directions, True, "black")
    screen.blit(textSurface, (10, 80))


# Third question
def question3(answer):
    if answer == K_y:
        yes1 = "Although Anya almost died in the Ancient Forest,"
        yes2 = "she returns with the Sword of Legends!"
        yes3 = "In the dead of winter, the ogres come back."
        yes4 = "This time they are being led by their evil king."
        q4 = "Should Anya fight the ogre king now that she has the Sword of Legends?"

        textSurface = myFont.render(yes1, True, "black")
        screen.blit(textSurface, (10, 10))
        textSurface = myFont.render(yes2, True, "black")
        screen.blit(textSurface, (10, 24))
        textSurface = myFont.render(yes3, True, "black")
        screen.blit(textSurface, (10, 38))
        textSurface = myFont.render(yes4, True, "black")
        screen.blit(textSurface, (10, 52))
        textSurface = myFont.render(q4, True, "black")
        screen.blit(textSurface, (10, 66))
        textSurface = myFont.render(directions, True, "black")
        screen.blit(textSurface, (10, 80))

    elif answer == K_n:
        no1 = "Anya decides it's too risky to go into the forest alone."
        no2 = "She hopes for the best with the weapons she has."
        no3 = "In the dead of winter, the ogres come back."
        no4 = "This time they are being led by their evil king."
        q4 = "Should Anya fight the king even though she doesn't have the Sword of Legends?"

        textSurface = myFont.render(no1, True, "black")
        screen.blit(textSurface, (10, 10))
        textSurface = myFont.render(no2, True, "black")
        screen.blit(textSurface, (10, 24))
        textSurface = myFont.render(no3, True, "black")
        screen.blit(textSurface, (10, 38))
        textSurface = myFont.render(no4, True, "black")
        screen.blit(textSurface, (10, 52))
        textSurface = myFont.render(q4, True, "black")
        screen.blit(textSurface, (10, 66))
        textSurface = myFont.render(directions, True, "black")
        screen.blit(textSurface, (10, 80))


# Ending
def end(answer):
    if answer == K_y:
        yes1 = "Tension fills the air as she prepares to fight the king. The duel commences..."
        end1 = "After an intense battle, Anya strikes the final blow!"
        end2 = "The king surrenders and pleads for mercy."
        end3 = "Anya is a true hero, who shows mercy to the king."
        end4 = "This act of kindness warms the evil king's heart,"
        end5 = "who promises to leave the village alone for eternity."
        end6 = "The end!"

        textSurface = myFont.render(yes1, True, "black")
        screen.blit(textSurface, (10, 10))
        textSurface = myFont.render(end1, True, "black")
        screen.blit(textSurface, (10, 24))
        textSurface = myFont.render(end2, True, "black")
        screen.blit(textSurface, (10, 38))
        textSurface = myFont.render(end3, True, "black")
        screen.blit(textSurface, (10, 52))
        textSurface = myFont.render(end4, True, "black")
        screen.blit(textSurface, (10, 66))
        textSurface = myFont.render(end5, True, "black")
        screen.blit(textSurface, (10, 80))
        textSurface = myFont.render(end6, True, "black")
        screen.blit(textSurface, (10, 94))

    elif answer == K_n:
        no1 = "Anya refuses to duel the king, who laughs at her cowardice."
        end1 = "This buys some time for the villagers to escape."
        end2 = "Sadly, the ogre king takes over Anya's village."
        end3 = "She is just thankful that the villagers were able to get to safety."
        end4 = "The end!"

        textSurface = myFont.render(no1, True, "black")
        screen.blit(textSurface, (10, 10))
        textSurface = myFont.render(end1, True, "black")
        screen.blit(textSurface, (10, 24))
        textSurface = myFont.render(end2, True, "black")
        screen.blit(textSurface, (10, 38))
        textSurface = myFont.render(end3, True, "black")
        screen.blit(textSurface, (10, 52))
        textSurface = myFont.render(end4, True, "black")
        screen.blit(textSurface, (10, 66))


# Game loop
while True:
    # Checks to see if at beginning of game
    if currentQuestion == 0:
        intro()

    # Get the most recent event
    currentEvent = event.poll()

    # Displays the correct question based on event that occurs
    if currentEvent.type == KEYDOWN:
        story(currentEvent.key, currentQuestion)
        currentQuestion = currentQuestion + 1

    # add text to screen
    display.update()

code source: codecombat (developing python game)

The code above is a simple interactive story game written with Pygame. In the first few lines, you import Pygame and its display, font, and event modules.

pygame.locals brings in constants like K_y (Y key), K_n (N key), and⁣ KEYDOWN.

The preceding line then initializes Pygame and creates a window (screen). It also sets the window title and then loads a font for rendering the text.

Then you have the section for functions that power the story (intro, question1, question2, question3, and conditions based on the player’s answer).

In summary, the code is a choose-your-own-adventure text game with a single character, Anya. The choices of the player determine which text is shown.

To run this script, install pygame.

sudo apt-get update
sudo apt-get install -y python3-pygame
pip install pygame

The above code will install pygame into your environment, after which you can then run the script.

python3 test.py

When you run this inside Codespaces, the window will appear in the noVNC tab. If it doesn’t open automatically, click on connect.

Tips

• Ignore ALSA errors: Codespaces doesn’t have sound output, so audio warnings are normal.

• Adjust resolution: Change 1024x768x24 in the script if you want a bigger (or smaller) screen.

• Use with other libraries: Tkinter, PyQt, and Matplotlib interactive plots. All will work with this setup.

• Automate DISPLAY export: Add export DISPLAY=:1 in your bash file if you don’t want to type it each time.

Conclusion

You’ve just turned GitHub Codespaces into a Python GUI environment. By using Xvfb and noVNC, you can run apps that normally require a desktop environment right inside your browser.

Whether you’re building games, testing interfaces, or teaching Python graphics, you can now do it all in Codespaces without leaving the cloud.

Want to try it yourself? Clone this repo, run ./start-gui.sh, and launch your first GUI app in Codespaces today.