Network Policy

Set Up Gmail With an App Password

View as Markdown

Use the gmail preset when a Python script needs to receive mail through IMAP or send mail through SMTP with a Gmail App Password. The preset allows only /usr/bin/python3 to open raw TLS connections to imap.gmail.com:993 and smtp.gmail.com:465.

OpenShell enforces the exact hosts, ports, and binary, but it cannot inspect individual IMAP or SMTP commands inside the encrypted connections. This preset does not grant Gmail REST API, Google OAuth, or service-account endpoints.

Google recommends App Passwords only for clients that cannot use Sign in with Google. This workflow stores the App Password inside the sandbox, where the agent can read it while the file exists. Create an App Password only for this workflow. Delete the uploaded file after the task. Revoke the App Password after the task.

Prerequisites

Prepare the Google Account before applying the preset:

  • Turn on 2-Step Verification for the Google Account.
  • Create an App Password for the sandbox workflow.
  • Confirm that the account or Google Workspace administrator permits IMAP and App Passwords.

Google documents the TLS endpoints and ports in IMAP, POP, and SMTP.

Apply the Preset

Run these commands from the host:

$nemohermes my-assistant policy-add gmail --dry-run
$nemohermes my-assistant policy-add gmail --yes

Upload the App Password

Create gmail_config.json on the host outside any source checkout:

1{
2  "email": "your-address@gmail.com",
3  "app_password": "<16-character-app-password>"
4}

Restrict the host file. Prepare a sandbox directory. Upload the file. Restrict the uploaded copy:

$chmod 600 /path/to/gmail_config.json
$nemohermes my-assistant exec -- mkdir -p /sandbox/hand
$nemohermes my-assistant upload /path/to/gmail_config.json /sandbox/hand/gmail_config.json
$nemohermes my-assistant exec -- chmod 600 /sandbox/hand/gmail_config.json

Do not commit gmail_config.json or paste its contents into chat, logs, issues, or pull requests.

Download Recent Attachments

Save this standard-library example as download_attachments.py on the host. It reads the 10 most recent messages without marking them as read and writes attachments under /sandbox/hand/gmail_attachments:

1import imaplib
2import json
3from email import policy
4from email.parser import BytesParser
5from pathlib import Path
6
7ROOT = Path("/sandbox/hand")
8CONFIG = json.loads((ROOT / "gmail_config.json").read_text(encoding="utf-8"))
9ATTACHMENTS = ROOT / "gmail_attachments"
10ATTACHMENTS.mkdir(mode=0o700, parents=True, exist_ok=True)
11ATTACHMENTS.chmod(0o700)
12
13with imaplib.IMAP4_SSL("imap.gmail.com", 993, timeout=30) as mailbox:
14    mailbox.login(CONFIG["email"], CONFIG["app_password"])
15    status, _ = mailbox.select("INBOX", readonly=True)
16    if status != "OK":
17        raise RuntimeError("Could not select the Gmail inbox")
18
19    status, search_data = mailbox.search(None, "ALL")
20    if status != "OK":
21        raise RuntimeError("Could not search the Gmail inbox")
22
23    for message_id in search_data[0].split()[-10:]:
24        status, message_data = mailbox.fetch(message_id, "(BODY.PEEK[])")
25        if status != "OK":
26            continue
27        raw_message = next(
28            (entry[1] for entry in message_data if isinstance(entry, tuple)),
29            None,
30        )
31        if raw_message is None:
32            continue
33
34        message = BytesParser(policy=policy.default).parsebytes(raw_message)
35        for part in message.walk():
36            filename = part.get_filename()
37            payload = part.get_payload(decode=True)
38            if part.get_content_disposition() != "attachment" or not filename or payload is None:
39                continue
40            safe_name = Path(filename.replace("\\", "/")).name
41            destination = ATTACHMENTS / f"{message_id.decode()}-{safe_name}"
42            destination.write_bytes(payload)
43            destination.chmod(0o600)
44            print(destination)

Upload the script. Run the script. Copy the attachment directory back to the host:

$nemohermes my-assistant upload ./download_attachments.py /sandbox/hand/download_attachments.py
$nemohermes my-assistant exec -- python3 /sandbox/hand/download_attachments.py
$nemohermes my-assistant download /sandbox/hand/gmail_attachments/ ./gmail_attachments/

Treat every downloaded attachment as untrusted content. Do not execute an attachment in the sandbox or on the host without reviewing it.

Send a Test Message

Save this standard-library example as send_email.py on the host. The example sends a test message back to the configured account:

1import json
2import smtplib
3from email.message import EmailMessage
4from pathlib import Path
5
6config = json.loads(
7    Path("/sandbox/hand/gmail_config.json").read_text(encoding="utf-8")
8)
9message = EmailMessage()
10message["From"] = config["email"]
11message["To"] = config["email"]
12message["Subject"] = "NemoClaw Gmail policy test"
13message.set_content("Sent through the NemoClaw Gmail policy preset.")
14
15with smtplib.SMTP_SSL("smtp.gmail.com", 465, timeout=30) as smtp:
16    smtp.login(config["email"], config["app_password"])
17    smtp.send_message(message)

Run these commands:

$nemohermes my-assistant upload ./send_email.py /sandbox/hand/send_email.py
$nemohermes my-assistant exec -- python3 /sandbox/hand/send_email.py

Remove Credentials and Access

Delete the host and uploaded credential files, along with the temporary sandbox files, after downloading any attachments you need:

$rm -f /path/to/gmail_config.json
$nemohermes my-assistant exec -- rm -f /sandbox/hand/gmail_config.json
$nemohermes my-assistant exec -- rm -f /sandbox/hand/download_attachments.py /sandbox/hand/send_email.py
$nemohermes my-assistant exec -- rm -rf /sandbox/hand/gmail_attachments
$nemohermes my-assistant policy-remove gmail --yes

Removing the preset does not delete uploaded files or revoke the App Password. Revoke the dedicated App Password in your Google Account when the sandbox no longer needs it.