overleaf

name	overleaf
description	How to set up and manipulate Overleaf CE project state via HTTP APIs for CUA-Gym tasks. For setup-gen and reward-gen agents.
user-invocable	false

Overleaf — Setup & Verification Guide

This skill teaches setup-gen and reward-gen how to create, manipulate, and verify Overleaf project state for LaTeX editing tasks. Unlike file-based domains, Overleaf tasks involve HTTP state management through a shared Overleaf CE instance — there are no local .tex files on the VM.

• Libraries: requests, json, uuid, zipfile, io, re
• Overleaf CE instance: https://cua-gym-overleaf.xlang.ai
• Admin account: [e-mail] (used only for user lifecycle management)

---

0. Architecture Overview

Admin creates session user  →  Session user logs in  →  Project created via ZIP upload
       ↓                              ↓                          ↓
  activate URL             CSRF + session cookie          CUA agent edits in browser
       ↓                              ↓                          ↓
  set password              setup-gen / reward-gen        reward-gen verifies via API
                                                                  ↓
                                                      User self-deletes account

Key difference from mock_websites: Overleaf uses per-session user accounts (not just per-session state IDs). Each training episode gets its own user, ensuring complete isolation. The user is created at setup and deleted after reward verification.

Key difference from file-based domains: There is no dual-VM pattern (initial_env / golden_env). Both initial and golden states exist as Overleaf projects under the same user on the shared instance. The reward script verifies by downloading and inspecting project content via HTTP.

---

1. Authentication API

All Overleaf API calls require session-cookie authentication. CSRF tokens are embedded in HTML pages as <meta name="ol-csrfToken"> tags.

1.1 Extracting CSRF Token

import re
import requests

OVERLEAF_URL = 'https://cua-gym-overleaf.xlang.ai'

session = requests.Session()

def get_csrf(session):
    """Extract CSRF token from any Overleaf page."""
    resp = session.get(f'{OVERLEAF_URL}/login', timeout=10)
    match = re.search(r'name="ol-csrfToken"\s+content="([^"]+)"', resp.text)
    if not match:
        raise RuntimeError('Cannot extract CSRF token')
    return match.group(1)

1.2 Login

def login(session, email, password):
    """Login and establish session cookie."""
    csrf = get_csrf(session)
    resp = session.post(
        f'{OVERLEAF_URL}/login',
        json={'email': email, 'password': password, '_csrf': csrf},
        timeout=15,
        allow_redirects=False,
    )
    if resp.status_code not in (200, 302):
        raise RuntimeError(f'Login failed: {resp.status_code} {resp.text[:200]}')
    return session

1.3 CSRF for POST/PUT/DELETE Requests

There are two ways to pass CSRF tokens, depending on content type:

Request Type	CSRF Method
application/json	Include "_csrf": token in JSON body
multipart/form-data (file upload)	Use X-CSRF-Token HTTP header

# JSON request
session.post(url, json={..., '_csrf': csrf})

# File upload (multipart) — CSRF must be in header, NOT in form data
session.post(url, files={...}, data={...}, headers={'X-CSRF-Token': csrf})

CRITICAL: For file uploads (ZIP upload, image upload), putting _csrf in the data dict returns 403 Forbidden. Always use the X-CSRF-Token header for multipart requests.

---

2. User Lifecycle API

Each training session requires an isolated user account. The admin account creates and manages session users.

2.1 Create Session User (Admin)

def create_session_user(admin_session, email):
    """Admin creates a new user. Returns activate URL for password setup."""
    csrf = get_csrf(admin_session)
    resp = admin_session.post(
        f'{OVERLEAF_URL}/admin/register',
        json={'email': email, '_csrf': csrf},
        timeout=15,
    )
    resp.raise_for_status()
    data = resp.json()
    # Returns: {"email": "...", "setNewPasswordUrl": "https://.../user/activate?token=...&user_id=..."}
    return data['setNewPasswordUrl']

2.2 Set Password via Activate URL

The activate URL is a one-time link. A fresh (non-logged-in) session must visit it and POST the new password.

def set_user_password(activate_url, new_password):
    """Set password for a newly created user via the activate URL."""
    pw_session = requests.Session()
    resp = pw_session.get(activate_url, timeout=10)

    csrf = re.search(r'name="ol-csrfToken"\s+content="([^"]+)"', resp.text).group(1)
    token = re.search(r'token=([a-f0-9]+)', activate_url).group(1)

    resp2 = pw_session.post(
        f'{OVERLEAF_URL}/user/password/set',
        json={
            'passwordResetToken': token,
            'password': new_password,
            '_csrf': csrf,
        },
        timeout=15,
        allow_redirects=False,
    )
    if resp2.status_code not in (200, 302):
        raise RuntimeError(f'Set password failed: {resp2.status_code}')

2.3 Delete Session User (Self-Delete)

After task completion and reward verification, the session user deletes their own account. This also removes all associated projects.

def delete_own_account(session, password):
    """User deletes their own account and all projects."""
    csrf = get_csrf(session)
    resp = session.post(
        f'{OVERLEAF_URL}/user/delete',
        json={'password': password, '_csrf': csrf},
        timeout=15,
    )
    resp.raise_for_status()

2.4 Full User Lifecycle (Setup Helper)

import uuid

def create_session_credentials():
    """Generate unique session email and password."""
    session_id = uuid.uuid4().hex[:12]
    email = f'session-{session_id}@cua-gym.local'
    password = f'cua-{uuid.uuid4().hex[:16]}'
    return email, password, session_id

def provision_session_user(admin_email, admin_password):
    """Full flow: admin creates user → set password → return logged-in session."""
    email, password, session_id = create_session_credentials()

    # Step 1: Admin creates user
    admin = requests.Session()
    login(admin, admin_email, admin_password)
    activate_url = create_session_user(admin, email)
    admin.post(f'{OVERLEAF_URL}/logout',
               json={'_csrf': get_csrf(admin)}, allow_redirects=False)

    # Step 2: Set password
    set_user_password(activate_url, password)

    # Step 3: Login as session user
    session = requests.Session()
    login(session, email, password)

    return session, email, password, session_id

---

3. Project API

3.1 Create Project from ZIP (Primary Method)

The most reliable way to create projects with arbitrary content. Build a ZIP in memory, upload it.

import io
import zipfile

def build_project_zip(files: dict) -> bytes:
    """Build a ZIP from a dict of {filename: content_string}.

    Args:
        files: e.g., {'main.tex': '\\documentclass{article}...', 'refs.bib': '@article{...}'}
    Returns:
        ZIP bytes ready for upload.
    """
    buf = io.BytesIO()
    with zipfile.ZipFile(buf, 'w', zipfile.ZIP_DEFLATED) as zf:
        for name, content in files.items():
            zf.writestr(name, content)
    buf.seek(0)
    return buf.read()

def create_project(session, name, zip_bytes):
    """Upload ZIP to create project. Returns project_id."""
    csrf = get_csrf(session)
    resp = session.post(
        f'{OVERLEAF_URL}/project/new/upload',
        files={'qqfile': (f'{name}.zip', zip_bytes, 'application/zip')},
        data={'name': name},
        headers={'X-CSRF-Token': csrf},
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()['project_id']

3.2 Create Blank Project

def create_blank_project(session, name):
    """Create blank project with default main.tex. Returns project_id."""
    csrf = get_csrf(session)
    resp = session.post(
        f'{OVERLEAF_URL}/project/new',
        json={'projectName': name, '_csrf': csrf},
        timeout=15,
    )
    resp.raise_for_status()
    return resp.json()['project_id']

3.3 Read Project File List (Entities)

def get_file_list(session, project_id):
    """Get flat list of project files with paths.

    Returns: ['/main.tex', '/sections/intro.tex', '/figures/fig1.png', ...]
    """
    resp = session.get(
        f'{OVERLEAF_URL}/project/{project_id}/entities',
        timeout=10,
    )
    resp.raise_for_status()
    data = resp.json()
    entities = data.get('entities', [])
    return [e['path'] for e in entities]

Response format:

{
  "project_id": "abc123",
  "entities": [
    {"path": "/main.tex", "type": "doc"},
    {"path": "/references.bib", "type": "doc"},
    {"path": "/figures/plot.png", "type": "file"}
  ]
}

• type: "doc" = text file (.tex, .bib, .cls, .sty, .bst, .txt)
• type: "file" = binary file (images, PDFs, fonts)

3.4 Download Project as ZIP

def download_project_zip(session, project_id):
    """Download entire project as ZIP. Returns bytes."""
    resp = session.get(
        f'{OVERLEAF_URL}/Project/{project_id}/download/zip',
        timeout=30,
    )
    resp.raise_for_status()
    return resp.content

def read_file_from_zip(zip_bytes, filename):
    """Extract a single file's content from project ZIP."""
    with zipfile.ZipFile(io.BytesIO(zip_bytes)) as zf:
        return zf.read(filename).decode('utf-8')

def list_files_in_zip(zip_bytes):
    """List all files in project ZIP."""
    with zipfile.ZipFile(io.BytesIO(zip_bytes)) as zf:
        return zf.namelist()

3.5 Compile Project

def compile_project(session, project_id):
    """Compile project. Returns compile result with output file URLs.

    Returns: {
        'status': 'success' | 'failure' | 'timedout',
        'outputFiles': [{'path': 'output.pdf', 'url': '/project/.../output.pdf', 'build': '...', 'size': N}, ...]
    }
    """
    csrf = get_csrf(session)
    resp = session.post(
        f'{OVERLEAF_URL}/project/{project_id}/compile',
        json={'rootDoc_id': '', 'draft': False, 'check': 'silent', '_csrf': csrf},
        timeout=120,
    )
    resp.raise_for_status()
    return resp.json()

3.6 Download Compiled PDF

CRITICAL: The PDF URL requires a build ID from the compile response. The simple path /project/{id}/output/output.pdf does NOT work.

def download_pdf(session, project_id, compile_result):
    """Download compiled PDF. Must pass compile_result from compile_project()."""
    for f in compile_result.get('outputFiles', []):
        if f.get('path') == 'output.pdf':
            resp = session.get(f'{OVERLEAF_URL}{f["url"]}', timeout=30)
            resp.raise_for_status()
            return resp.content
    raise RuntimeError('No PDF in compile output')

3.7 Update Project Settings

def update_settings(session, project_id, settings):
    """Update project settings.

    Supported settings:
        compiler: 'pdflatex' | 'xelatex' | 'lualatex' | 'latex'
        spellCheckLanguage: 'en' | 'fr' | 'de' | ...
    """
    csrf = get_csrf(session)
    resp = session.post(
        f'{OVERLEAF_URL}/project/{project_id}/settings',
        json={**settings, '_csrf': csrf},
        timeout=10,
    )
    resp.raise_for_status()

3.8 Word Count

def get_wordcount(session, project_id):
    """Get word count of compiled document.

    Returns: {'texcount': {'textWords': N, 'headWords': N, 'mathInline': N, ...}}
    """
    resp = session.get(
        f'{OVERLEAF_URL}/project/{project_id}/wordcount',
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()

3.9 Delete Project

def delete_project(session, project_id):
    """Delete a project."""
    csrf = get_csrf(session)
    resp = session.delete(
        f'{OVERLEAF_URL}/Project/{project_id}',
        headers={'X-CSRF-Token': csrf},
        timeout=10,
    )
    resp.raise_for_status()

---

4. Task State Persistence

The state file /tmp/task_overleaf_state links initial_setup.py, golden_patch.py, and reward.py to the same user and project.

State format:

{
    "project_id": "69b8f6ef24d927a869b834c4",
    "overleaf_url": "https://cua-gym-overleaf.xlang.ai",
    "session_email": "[e-mail]",
    "session_password": "cua-7f8e9d0c1b2a3456",
    "admin_email": "[e-mail]",
    "admin_password": "cua-gym-agent-2024"
}

import json

STATE_FILE = '/tmp/task_overleaf_state'

def save_state(state):
    with open(STATE_FILE, 'w') as f:
        json.dump(state, f)

def load_state():
    with open(STATE_FILE) as f:
        return json.load(f)

---

5. initial_setup.py Template

"""
Initial Setup: <task_description>
Task ID: <task_id>
Domain: overleaf
"""
import io
import json
import os
import re
import shlex
import subprocess
import time
import uuid
import zipfile

import requests

# --- Config ---
OVERLEAF_URL = 'https://cua-gym-overleaf.xlang.ai'
ADMIN_EMAIL = '[e-mail]'
ADMIN_PASSWORD = 'cua-gym-agent-2024'

# --- Helper functions (from Section 1-2) ---
def get_csrf(session):
    resp = session.get(f'{OVERLEAF_URL}/login', timeout=10)
    match = re.search(r'name="ol-csrfToken"\s+content="([^"]+)"', resp.text)
    return match.group(1)

def do_login(session, email, password):
    csrf = get_csrf(session)
    resp = session.post(f'{OVERLEAF_URL}/login',
        json={'email': email, 'password': password, '_csrf': csrf},
        timeout=15, allow_redirects=False)
    assert resp.status_code in (200, 302), f'Login failed: {resp.status_code}'

# --- Step 1: Create session user ---
session_id = uuid.uuid4().hex[:12]
session_email = 
session_password = 

admin = requests.Session()
do_login(admin, ADMIN_EMAIL, ADMIN_PASSWORD)
csrf = get_csrf(admin)
resp = admin.post(,
    json={: session_email, : csrf}, timeout=)
activate_url = resp.json()[]


pw_session = requests.Session()
pw_resp = pw_session.get(activate_url, timeout=)
pw_csrf = re.search(, pw_resp.text).group()
pw_token = re.search(, activate_url).group()
pw_session.post(,
    json={: pw_token, : session_password, : pw_csrf},
    timeout=, allow_redirects=)


session = requests.Session()
do_login(session, session_email, session_password)




buf = io.BytesIO()
 zipfile.ZipFile(buf, )  zf:
    zf.writestr(, .strip())

    zf.writestr(, .strip())
buf.seek()


csrf = get_csrf(session)
resp = session.post(,
    files={: (, buf.getvalue(), )},
    data={: },
    headers={: csrf},
    timeout=)
project_id = resp.json()[]


state = {
    : project_id,
    : OVERLEAF_URL,
    : session_email,
    : session_password,
    : ADMIN_EMAIL,
    : ADMIN_PASSWORD,
}
 (, )  f:
    json.dump(state, f)

()
()


 ():
    env = os.environ.copy()
    env[] = 
    subprocess.Popen(shlex.split(command),
        stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, env=env)
    time.sleep(delay_sec)

launch_gui(, delay_sec=)
()

---

6. golden_patch.py Template

CRITICAL: Unlike mock_websites, there is no set_current API. The golden state is created by uploading a new project with the expected final content under the same user account.

Strategy: Delete the initial project, create a new project with the golden content, and update the state file with the new project_id.

"""
Golden Patch: <task_description>
Task ID: <task_id>
Domain: overleaf
Changes: <brief list of what this patch does>
"""
import io
import json
import re
import zipfile

import requests

# --- Config ---
OVERLEAF_URL = 'https://cua-gym-overleaf.xlang.ai'

# --- Load state ---
with open('/tmp/task_overleaf_state') as f:
    state = json.load(f)

def get_csrf(session):
    resp = session.get(f'{OVERLEAF_URL}/login', timeout=10)
    match = re.search(r'name="ol-csrfToken"\s+content="([^"]+)"', resp.text)
    return match.group(1)

def do_login(session, email, password):
    csrf = get_csrf(session)
    resp = session.post(f'{OVERLEAF_URL}/login',
        json={'email': email, 'password': password, '_csrf': csrf},
        timeout=15, allow_redirects=False)
    assert resp.status_code in (200, 302)

# --- Login as session user ---
session = requests.Session()
do_login(session, state['session_email'], state['session_password'])

# --- Delete old project ---
old_pid = state['project_id']
csrf = get_csrf(session)
session.delete(f'{OVERLEAF_URL}/Project/',
    headers={: csrf}, timeout=)



buf = io.BytesIO()
 zipfile.ZipFile(buf, )  zf:
    zf.writestr(, .strip())

    zf.writestr(, .strip())
buf.seek()


csrf = get_csrf(session)
resp = session.post(,
    files={: (, buf.getvalue(), )},
    data={: },
    headers={: csrf},
    timeout=)
new_pid = resp.json()[]


state[] = new_pid
 (, )  f:
    json.dump(state, f)

()

---

7. reward.py Template

"""
Reward Script: <task_description>
Task ID: <task_id>
Domain: overleaf
Scoring: <brief rubric>
"""
import io
import json
import re
import sys
import zipfile

import requests

# --- Load state ---
try:
    with open('/tmp/task_overleaf_state') as f:
        state = json.load(f)
except Exception as e:
    print(f'CRITICAL: Cannot read state: {e}')
    print('REWARD: 0.0')
    sys.exit(0)

OVERLEAF_URL = state['overleaf_url']
PROJECT_ID = state['project_id']

# --- Login ---
def get_csrf(session):
    resp = session.get(f'{OVERLEAF_URL}/login', timeout=10)
    match = re.search(r'name="ol-csrfToken"\s+content="([^"]+)"', resp.text)
    return match.group(1)

try:
    session = requests.Session()
    csrf = get_csrf(session)
    resp = session.post(f'{OVERLEAF_URL}/login',
        json={'email': state['session_email'], 'password': state['session_password'], '_csrf': csrf},
        timeout=15, allow_redirects=False)
    assert resp.status_code in (, )
 Exception  e:
    ()
    ()
    sys.exit()


:
    zip_resp = session.get(, timeout=)
    zip_resp.raise_for_status()
    project_zip = zip_resp.content
 Exception  e:
    ()
    ()
    sys.exit()

 ():
    
     zipfile.ZipFile(io.BytesIO(project_zip))  zf:
         zf.read(filename).decode()

 ():
    
     zipfile.ZipFile(io.BytesIO(project_zip))  zf:
         zf.namelist()


 ():
    total_score = 

    
    :
        main_tex = read_tex()
        
           main_tex:
            ()
            total_score += 
        :
            ()
     Exception  e:
        ()

    
    :
        
        csrf = get_csrf(session)
        compile_resp = session.post(
            ,
            json={: , : , : , : csrf},
            timeout=)
        result = compile_resp.json()
         result.get() == :
            ()
            total_score += 
        :
            ()
     Exception  e:
        ()

    
    :
        
        main_tex = read_tex()
           main_tex    main_tex:
            ()
            total_score += 
        :
            ()
     Exception  e:
        ()

    final_score = (total_score, )
    ()
    ()
     final_score

verify_task()

---

8. Cleanup Template

Every task must clean up after reward verification. Place this in the orchestrator or as a post-reward step.

"""Cleanup: delete project and session user."""
import json
import re
import requests

with open('/tmp/task_overleaf_state') as f:
    state = json.load(f)

OVERLEAF_URL = state['overleaf_url']

def get_csrf(session):
    resp = session.get(f'{OVERLEAF_URL}/login', timeout=10)
    match = re.search(r'name="ol-csrfToken"\s+content="([^"]+)"', resp.text)
    return match.group(1)

# Login as session user
session = requests.Session()
csrf = get_csrf(session)
session.post(f'{OVERLEAF_URL}/login',
    json={'email': state['session_email'], 'password': state['session_password'], '_csrf': csrf},
    timeout=15, allow_redirects=False)

# Delete project
csrf = get_csrf(session)
session.delete(f'{OVERLEAF_URL}/Project/{state["project_id"]}',
    headers={'X-CSRF-Token': csrf}, timeout=10)

# Delete user (self-delete removes all remaining projects too)
csrf = get_csrf(session)
session.post(f'{OVERLEAF_URL}/user/delete',
    json={'password': state['session_password'], '_csrf': csrf},
    timeout=15)

print(f'Cleaned up: user=, project=')

---

9. Verification Techniques Reference

9.1 Content Verification (Text Matching)

main_tex = read_tex('main.tex')

# Check section exists
has_section = r'\section{Related Work}' in main_tex

# Check command exists
has_package = r'\usepackage{hyperref}' in main_tex

# Check specific content with regex
import re
tables = re.findall(r'\\begin\{tabular\}.*?\\end\{tabular\}', main_tex, re.DOTALL)
num_tables = len(tables)

# Check bibliography entries
bib = read_tex('references.bib')
entries = re.findall(r'@\w+\{(\w+),', bib)

9.2 File Structure Verification

files = list_files()

# Check specific files exist
assert 'main.tex' in files
assert 'figures/plot.png' in files

# Check directory structure
figure_files = [f for f in files if f.startswith('figures/')]
section_files = [f for f in files if f.startswith('sections/')]

9.3 Compilation Verification

csrf = get_csrf(session)
result = session.post(f'{OVERLEAF_URL}/project/{PROJECT_ID}/compile',
    json={'rootDoc_id': '', 'draft': False, 'check': 'silent', '_csrf': csrf},
    timeout=120).json()

# Check compilation status
compile_ok = result.get('status') == 'success'

# Check for specific warnings/errors in log
for f in result.get('outputFiles', []):
    if f['path'] == 'output.log':
        log = session.get(f'{OVERLEAF_URL}{f["url"]}', timeout=30).text
        has_warnings = 'LaTeX Warning' in log
        has_errors = '! ' in log

9.4 PDF Content Verification

Download the compiled PDF and verify its content using PyMuPDF (fitz).

# Download PDF
compile_result = compile_project(session, PROJECT_ID)
pdf_bytes = download_pdf(session, PROJECT_ID, compile_result)

# Verify with PyMuPDF (must be installed on VM)
import fitz  # PyMuPDF
doc = fitz.open(stream=pdf_bytes, filetype='pdf')

# Page count
num_pages = len(doc)

# Extract text
full_text = ''
for page in doc:
    full_text += page.get_text()

# Check specific content in rendered PDF
assert 'Quarterly Sales Report' in full_text
assert 'North America' in full_text

# Check for images
for page in doc:
    images = page.get_images()
    # images is a list of (xref, smask, width, height, ...) tuples

doc.close()

9.5 Word Count Verification

wc = get_wordcount(session, PROJECT_ID)
text_words = wc['texcount']['textWords']
math_inline = wc['texcount']['mathInline']
math_display = wc['texcount']['mathDisplay']

9.6 Project Settings Verification

Project settings (compiler, language) can be checked via the entities API response or by inspecting the project page meta tags.

# Check via entities API (project_id is in response)
resp = session.get(f'{OVERLEAF_URL}/project/{PROJECT_ID}/entities', timeout=10)
# Settings are not directly in entities — use compile behavior as proxy:
# If xelatex is required, compile with xelatex-only features and check success

---

10. Bitter Lessons

1. CSRF in multipart uploads MUST use the X-CSRF-Token header. Putting _csrf in the data dict for file uploads returns 403 Forbidden. This is the #1 integration bug.

2. PDF download requires the full URL from compile results. The simple path /project/{id}/output/output.pdf returns 404. You must compile first, then use the url field from the outputFiles array in the compile response.

3. The entities API returns flat paths, not nested trees. Format is [{"path": "/main.tex", "type": "doc"}, ...]. There are no folder IDs or doc IDs in this response. To get IDs for folder/doc operations, parse the project editor page's ol-project meta tag.

4. Session users start as holdingAccount: true. You MUST visit the activate URL and POST a password before the user can log in. Attempting to login before setting a password returns 401.

5. User self-delete (/user/delete) removes everything. All projects, history, and associated data are purged. This is the cleanest cleanup method and should always be used instead of deleting projects individually.

6. CSRF tokens change after login. The token obtained before login is invalidated when the session regenerates. Always call get_csrf() again after login().

7. Compilation is CPU-intensive and can take 30+ seconds. Set timeout=120 for compile requests. For documents with heavy packages (tikz, listings), compilation may take even longer.

8. ZIP upload creates projects atomically. All files in the ZIP are created at once. This is much more reliable than creating a blank project and adding files one by one (which requires folder IDs and multiple API calls).

9. LaTeX content in Python strings needs raw strings or double backslashes. Use r"""\documentclass{article}...""" or escape backslashes as \\documentclass. Forgetting this silently corrupts LaTeX source.

10. Cloudflare has a 100-second WebSocket idle timeout. Long-idle editor sessions may disconnect. This doesn't affect API calls but may impact the CUA agent's browser editing experience. Overleaf's built-in keepalive usually handles this.