Agent-guided local setup

Paste one prompt. Set up Canvas Pilot locally.

Copy the setup brief into Codex or another local agent with shell and file access. It can clone the public repo, prepare the local runtime, and guide configuration. You still complete Canvas login, 2FA, course choices, and every approval decision.

Local agent requiredNot a browser-only chatbot.

Login stays with youEnter secrets only in the Canvas browser.

Setup stops before workNo assignment plan, execution, or submission.

Go to the prompt Inspect the repo first

canvas-pilot-setup.txt

Setup prompt for your local agent

Install and configure Canvas Pilot locally for me from the canonical public repository:

https://github.com/X-isdoingreat/canvas-pilot.git

Scope and permission

- You may clone this public repository, create an isolated local Python environment, install its project dependencies and Playwright Chromium, and create gitignored local configuration inside the clone.
- This prompt authorizes installing project-local cryptography if it is needed to prevent weak base64 credential storage.
- Do not make system-wide package changes, alter PATH, or install a missing system dependency without explaining the change and asking me first.
- If an existing Canvas Pilot clone is present, inspect it and preserve its configuration and unrelated changes. Do not overwrite it blindly.

Hard boundaries

- Do not commit, push, publish, deploy, or modify .claude.
- Do not scan pending or due assignments, download assignment content, create assignments.json or plan.json, execute work, answer quizzes, upload files, or submit anything during setup.
- Never ask me to paste a Canvas username, password, API token, cookie, or 2FA code into chat or the terminal. I will enter login details only in the browser window opened by Canvas Pilot.
- Keep course names, course IDs, credentials, cookies, local configuration, and generated course details on this machine. Never place them in public artifacts, commits, deployment logs, or remote messages.

1. Preflight the machine

Verify Git, Python 3.11 or newer, a local shell with file access, and a desktop environment that can open an interactive browser. Use python3 instead of python where the operating system requires it. If a required system component is missing, report exactly what is missing and ask before changing the system.

Choose a sensible install directory with me only if the location is unclear. Clone the repository if no safe existing clone is present, then work from the repository root.

2. Read the current project instructions

Before changing anything, read:

- AGENTS.md
- README.md
- .agents/skills/canvas-setup/SKILL.md
- .agents/skills/canvas-bootstrap/SKILL.md

Do not use the manifest-only plugin as an installer. Do not run python setup.py or python -m src.canvas_login --auto. Those are not valid public-repo setup entry points.

3. Prepare an isolated runtime

Use an isolated Python environment. If you create a repo-local .venv, add .venv/ to .git/info/exclude before creating it so it can never be staged accidentally. Use that environment's Python interpreter for every command below.

Run:

python -m pip install -r requirements.txt
python -m playwright install chromium

Do not claim setup succeeded if either command fails.

4. Create only local, ignored configuration

Ask for my Canvas login-page URL only if you cannot determine the HTTPS Canvas origin safely. Preserve unrelated existing values, then create or update local .env settings:

CANVAS_AUTH=cookie
CANVAS_WEB_BASE=<Canvas HTTPS origin>
CANVAS_BASE=<Canvas HTTPS origin>/api/v1

If courses.yaml is absent, create it with:

pending_window_days: 7
routes: {}

Create SECRETS.md from SECRETS.example.md only if the current setup workflow actually needs it. Do not ask me to fill unrelated identity fields.

Confirm that .env, .cookies/, courses.yaml, SECRETS.md, _private/, runs/, sources/, final_drafts/, and any local virtual environment are ignored or locally excluded. Never stage or print their contents.

5. Fail closed on credential storage

Before opening the login browser, run:

python -c "from src import canvas_credentials as c; print(c._pick_method())"

If it prints base64, do not log in yet. Install cryptography into the isolated project environment, re-run the check, and continue only if it reports fernet or dpapi. If protected storage is still unavailable, stop and explain the blocker.

Tell me clearly that the current client captures the username and password entered into the Canvas SSO browser and stores them locally for future autofill after a successful login. Also tell me that retained Canvas session cookies are sensitive local credentials. The privacy-first default for this setup is to remove the saved username and password after login while retaining the local browser session.

6. Complete browser login and verify it

Run the real authentication probe:

python -m src.canvas_client --probe

Pause while I complete normal Canvas SSO and 2FA in the Chromium window. Do not echo secret values. Course names and IDs printed by the probe may appear only in this local setup session as needed for my course selection.

After the probe succeeds, run:

python -m src.canvas_client --forget-credentials

Then run the probe once more. Continue only if the retained local Canvas session still authenticates successfully without the saved username and password.

7. Configure the courses I choose

Follow the canvas-setup and canvas-bootstrap skills. Show me active courses and let me choose which recurring course workflows to configure and what to call them. For this local bootstrap only, you may inspect enrolled-course names and the minimum recurring assignment metadata needed to propose course patterns. Do not read assignment bodies or files, determine my pending workload, create a due-work plan, or execute anything.

Keep real course IDs only in local courses.yaml. Keep generated skill scaffolds public-safe: no real school, instructor, private URL, email, course ID, or assignment ID. Complete the skill design dialogue for each course I choose, and never leave an UNFILLED_SKELETON sentinel in a route you report as ready.

8. Verify, report, and stop

Run the focused setup tests that exist in the repository, including:

python tests/codex_runtime/run_setup_tests.py

Verify all of the following:

- the live Canvas probe succeeds;
- courses.yaml contains only the routes I selected;
- every selected route has a completed .agents/skills/canvas-*/SKILL.md;
- no ready skill contains UNFILLED_SKELETON;
- no secret, cookie, local config, run output, or virtual environment is staged by Git;
- no assignment scan, plan, execution, upload, or submission occurred.

Finish with a concise local setup report that separates verified facts from remaining manual steps. The next separate action is scan canvas. Do not run that scan until I explicitly ask.

Git + Python 3.11+ The agent checks local requirements before it changes anything.

SSO and 2FA stay human You complete authentication in Canvas, never inside the prompt.

Draft-first after setup Future work still follows scan, approval, and execute.

What happens next

Three checkpoints, with you in the loop.

The prompt gives the agent a complete operating contract. It also tells the agent exactly where it must pause for your input.

Local preflight

The agent checks the machine, clones the canonical repo, and prepares an isolated runtime without making silent system changes.

Private browser login

Canvas Pilot opens Chromium. You enter SSO and 2FA there, then the agent removes saved username and password by default.

Course setup

You choose courses and recurring patterns. The agent verifies local routes, reports what is ready, and stops before scanning work.

Privacy boundary

Your Canvas context stays local.

Canvas Pilot is a local workflow, not a hosted account service. Course configuration, browser sessions, downloaded sources, drafts, and run state stay on the machine running the agent.

Keep secrets out of chat. Passwords and 2FA belong only in the Canvas browser. Session cookies are sensitive too, even when they never leave your computer.

Before you start

This is for local-agent users.

You need

Codex or a similar local agent with shell and file access.
Git and Python 3.11 or newer.
A desktop that can open an interactive Chromium window.
Your normal Canvas login and 2FA method.

This prompt does not authorize

Reading or executing pending assignments during setup.
Uploading or submitting Canvas work.
Publishing private course or credential data.
Committing, pushing, or deploying from the local clone.