Cloud dev (Claude Code on the web)

Running this repo end-to-end inside Claude Code on the web — credential flows, env panel, network allowlist, MCP servers.

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

The env channel is a transport, not a process.env map — different credential types are consumed by different actors (tools, agent, or vercel pull). See Cloud credentials → How each credential is actually used for the canonical breakdown of which is which, and why variable names often under-represent the real scope.

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.

Variable	Where to get it
`VERCEL_TOKEN`	vercel.com/account/tokens — scope to today-platform team
`VERCEL_ORG_ID`, `VERCEL_PROJECT_ID_*`	Pre-filled constants in `.env.cloud.example`
`GH_TOKEN`	github.com/settings/tokens?type=beta — fine-grained, `contents:read` on `todayai-labs/*`
`E2E_OTP_ENDPOINT_URL`, `E2E_OTP_ENDPOINT_SECRET`, `E2E_USER_EMAIL`, `E2E_ADMIN_EMAIL`	GitHub Actions secrets — copy from `.github/workflows/e2e-*.yml` env, or ask in #engineering
`VERCEL_AUTOMATION_BYPASS_SECRET`	Vercel project → Settings → Deployment Protection → "Protection Bypass for Automation". Despite the name, the same value works for any client (Playwright, curl, manual testing). Mirrors the per-app `VERCEL_DEPLOYMENT_PROTECTION_BYPASS_HEADER_SECRET`
`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION`	IAM user with read-only CloudWatch Logs access
`SLACK_BOT_TOKEN`, `SLACK_TEAM_ID` (optional)	Slack app config, only if you want the Slack MCP server

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)

Script	Purpose
`pnpm cloud:bootstrap`	Pull env from Vercel for `web`
`pnpm cloud:pull <app>`	Pull env for one app — derives project ID from env
`pnpm cloud:logs`	`aws logs tail` wrapper for CloudWatch backend logs

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:

Create a Slack app at api.slack.com/apps.
Scopes: channels:history, channels:read, groups:history, users:read. Install to your workspace.
Add SLACK_BOT_TOKEN (xoxb-…) + SLACK_TEAM_ID to the cloud env panel.
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.

On this page