Cloud dev (Claude Code on the web)

Setup guide for running this repo end-to-end inside Claude Code on the web (claude.ai/code) — read Slack, edit code, run tests, push, CI, merge — without a local machine.

Codespaces / local devcontainer support has been removed (rationale). For the rare cases that need it, fork and add your own.

How credentials flow

Most things in .env.cloud.example are not process.env.X that the app reads at runtime. The env channel is just the only way the cloud agent accepts secrets — what each value really does varies:

The variable name often reflects a historical CI use case, not the real scope. VERCEL_AUTOMATION_BYPASS_SECRET works for any client (Playwright, curl, manual testing) despite the "automation" wording. The skill makes the real scope explicit per credential.

Setup

1. Connect the repo

https://claude.ai/code → connect GitHub → grant access to todayai-labs/today-platform-web. The cloud agent clones it into an isolated VM on each session.

2. Configure the cloud environment

Settings → Environment → create one named today-platform-web.

Setup Script field — paste the contents of scripts/cloud/setup-once.sh verbatim. Runs once at environment creation, cached ~7 days.

Environment Variables — fill in .env.cloud.example and paste each row.

⚠ No proper secrets store yet — anyone with environment-edit access can read these. Use scoped tokens, rotate quarterly. Track rotations with the maintain-cloud-dev skill.

3. Network access

Network → limited with these allowed hosts:

# Core
api.github.com
github.com
api.vercel.com
registry.npmjs.org

# Today backend
api.todayai.dev
auth.todayai.dev

# AWS CloudWatch
logs.us-west-2.amazonaws.com
sts.us-west-2.amazonaws.com

# Tooling installers (used by setup-once.sh)
cli.github.com
awscli.amazonaws.com

# Optional
slack.com

Allow package managers: npm ✓, pip ✓.

4. Verify

Start a session and ask:

Run pnpm typecheck and tell me if it passes.

The agent should find the cached environment, run typecheck, report results. If env vars are missing the agent will tell you which one to add to the cloud env panel.

End-to-end flow

You (any browser)
   │  "Refactor X based on Slack thread Y"
   ▼
Claude Code on the web
   │
   ├─ slack MCP → reads Slack thread
   ├─ pnpm cloud:logs → tail CloudWatch for failing endpoint
   ├─ edits files in cloned repo
   ├─ pnpm test            (vitest in sandbox)
   ├─ pnpm typecheck
   ├─ pnpm test:e2e:smoke  (optional — see skill §2)
   ├─ git commit + push to a new branch
   └─ gh pr create         (uses GH_TOKEN)
   ▼
GitHub
   ├─ CI runs (.github/workflows/*.yml)
   └─ Vercel preview deploy
   ▼
You — review PR, click Merge.

Nothing here requires your laptop to be on.

Limitations

• No port forwarding — pnpm dev runs but :4060 isn't reachable from your browser. Verify behavior via pnpm test, pnpm typecheck, Playwright in headless mode, or by deploying to a Vercel preview.
• No long-running processes — anything started in a session dies with the session. mitmproxy is unreachable; use MSW for in-process mocking.
• No persistent filesystem between sessions — push branches early.
• No SSH key support — for cross-repo access, use GH_TOKEN.
• No dedicated secrets store — env values are visible to anyone with environment-edit access.

pnpm scripts (alphabetical)

That's it. For everything else (cross-repo clone, E2E, manual curl against preview URLs, etc.), the agent loads use-cloud-credentials which has the recipes inline.

Slack integration (optional)

The cloud agent reads Slack via the @modelcontextprotocol/server-slack MCP server declared in .claude/settings.json.

Setup:

1. Create a Slack app at api.slack.com/apps.
2. Scopes: channels:history, channels:read, groups:history, users:read. Install to your workspace.
3. Add SLACK_BOT_TOKEN (xoxb-…) + SLACK_TEAM_ID to the cloud env panel.
4. The agent can now do things like:

   Read the latest 20 messages in #engineering and summarize the open bugs that need attention this week.

Why no devcontainer

The earlier version of this PR shipped a Codespaces/devcontainer configuration as a parallel "Path B". It was removed under the minimal principle:

• Cloud Code on the web is the primary target — Codespaces support forced two parallel paths to maintain.
• Codespaces had its own setup script, env wiring, and post-attach banner — ~180 lines that duplicated cloud-side work.
• The cloud agent has no port forwarding regardless, so pnpm dev preview was the only thing Codespaces actually added — and you can always click the Vercel preview URL instead.

If you specifically need browser-previewable local dev, prefer running pnpm directly on your machine. The repo's regular pnpm install && pnpm dev works.

Maintenance

Run maintain-cloud-dev monthly to audit for drift:

/skill maintain-cloud-dev
/schedule "first day of month, 9am" /skill maintain-cloud-dev

It probes credential liveness, env-var drift, MCP package reachability, cloud product capability shifts, and doc freshness.