claude-code-on-the-web.md +57 −7
47When you start a task on Claude Code on the web:47When you start a task on Claude Code on the web:
48 48
491. **Repository cloning**: Your repository is cloned to an Anthropic-managed virtual machine491. **Repository cloning**: Your repository is cloned to an Anthropic-managed virtual machine
50502. **Environment setup**: Claude prepares a secure cloud environment with your code2. **Environment setup**: Claude prepares a secure cloud environment with your code, then runs your [setup script](#setup-scripts) if configured
513. **Network configuration**: Internet access is configured based on your settings513. **Network configuration**: Internet access is configured based on your settings
524. **Task execution**: Claude analyzes code, makes changes, runs tests, and checks its work524. **Task execution**: Claude analyzes code, makes changes, runs tests, and checks its work
535. **Completion**: You're notified when finished and can create a PR with the changes535. **Completion**: You're notified when finished and can create a PR with the changes
227 227
228When you start a session in Claude Code on the web, here's what happens under the hood:228When you start a session in Claude Code on the web, here's what happens under the hood:
229 229
2302301. **Environment preparation**: We clone your repository and run any configured Claude hooks for initialization. The repo will be cloned with the default branch on your GitHub repo. If you would like to check out a specific branch, you can specify that in the prompt.1. **Environment preparation**: We clone your repository and run any configured [setup script](#setup-scripts). The repo will be cloned with the default branch on your GitHub repo. If you would like to check out a specific branch, you can specify that in the prompt.
231 231
2322. **Network configuration**: We configure internet access for the agent. Internet access is limited by default, but you can configure the environment to have no internet or full internet access based on your needs.2322. **Network configuration**: We configure internet access for the agent. Internet access is limited by default, but you can configure the environment to have no internet or full internet access based on your needs.
233 233
239 Claude operates entirely through the terminal and CLI tools available in the environment. It uses the pre-installed tools in the universal image and any additional tools you install through hooks or dependency management.239 Claude operates entirely through the terminal and CLI tools available in the environment. It uses the pre-installed tools in the universal image and any additional tools you install through hooks or dependency management.
240</Note>240</Note>
241 241
242242**To add a new environment:** Select the current environment to open the environment selector, and then select "Add environment". This will open a dialog where you can specify the environment name, network access level, and any environment variables you want to set.**To add a new environment:** Select the current environment to open the environment selector, and then select "Add environment". This will open a dialog where you can specify the environment name, network access level, environment variables, and a [setup script](#setup-scripts).
243 243
244244**To update an existing environment:** Select the current environment, to the right of the environment name, and select the settings button. This will open a dialog where you can update the environment name, network access, and environment variables.**To update an existing environment:** Select the current environment, to the right of the environment name, and select the settings button. This will open a dialog where you can update the environment name, network access, environment variables, and setup script.
245 245
246**To select your default environment from the terminal:** If you have multiple environments configured, run `/remote-env` to choose which one to use when starting web sessions from your terminal with `--remote`. With a single environment, this command shows your current configuration.246**To select your default environment from the terminal:** If you have multiple environments configured, run `/remote-env` to choose which one to use when starting web sessions from your terminal with `--remote`. With a single environment, this command shows your current configuration.
247 247
254 ```254 ```
255</Note>255</Note>
256 256
257### Setup scripts
258
259A setup script is a Bash script that runs when a new cloud session starts, before Claude Code launches. Use setup scripts to install dependencies, configure tools, or prepare anything the cloud environment needs that isn't in the [default image](#default-image).
260
261Scripts run as root on Ubuntu 24.04, so `apt install` and most language package managers work.
262
263<Tip>
264 To check what's already installed before adding it to your script, ask Claude to run `check-tools` in a cloud session.
265</Tip>
266
267To add a setup script, open the environment settings dialog and enter your script in the **Setup script** field.
268
269This example installs the `gh` CLI, which isn't in the default image:
270
271```bash theme={null}
272#!/bin/bash
273apt update && apt install -y gh
274```
275
276Setup scripts run only when creating a new session. They are skipped when resuming an existing session.
277
278If the script exits non-zero, the session fails to start. Append `|| true` to non-critical commands to avoid blocking the session on a flaky install.
279
280<Note>
281 Setup scripts that install packages need network access to reach registries. The default network access allows connections to [common package registries](#default-allowed-domains) including npm, PyPI, RubyGems, and crates.io. Scripts will fail to install packages if your environment has network access disabled.
282</Note>
283
284#### Setup scripts vs. SessionStart hooks
285
286Use a setup script to install things the cloud needs but your laptop already has, like a language runtime or CLI tool. Use a [SessionStart hook](/en/hooks#sessionstart) for project setup that should run everywhere, cloud and local, like `npm install`.
287
288Both run at the start of a session, but they belong to different places:
289
290| | Setup scripts | SessionStart hooks |
291| ------------- | ------------------------------------------------- | -------------------------------------------------------------- |
292| Attached to | The cloud environment | Your repository |
293| Configured in | Cloud environment UI | `.claude/settings.json` in your repo |
294| Runs | Before Claude Code launches, on new sessions only | After Claude Code launches, on every session including resumed |
295| Scope | Cloud environments only | Both local and cloud |
296
297SessionStart hooks can also be defined in your user-level `~/.claude/settings.json` locally, but user-level settings don't carry over to cloud sessions. In the cloud, only hooks committed to the repo run.
298
257### Dependency management299### Dependency management
258 300
259301Custom environment images and snapshots are not yet supported. As a workaround, you can use [SessionStart hooks](/en/hooks#sessionstart) to install packages when a session starts. This approach has [known limitations](#dependency-management-limitations).Custom environment images and snapshots are not yet supported. Use [setup scripts](#setup-scripts) to install packages when a session starts, or [SessionStart hooks](/en/hooks#sessionstart) for dependency installation that should also run in local environments. SessionStart hooks have [known limitations](#dependency-management-limitations).
302
303To configure automatic dependency installation with a setup script, open your environment settings and add a script:
304
305```bash theme={null}
306#!/bin/bash
307npm install
308pip install -r requirements.txt
309```
260 310
261311To configure automatic dependency installation, add a SessionStart hook to your repository's `.claude/settings.json` file:Alternatively, you can use SessionStart hooks in your repository's `.claude/settings.json` file for dependency installation that should also run in local environments:
262 312
263```json theme={null}313```json theme={null}
264{314{
611 661
612## Best practices662## Best practices
613 663
6146641. **Use Claude Code hooks**: Configure [SessionStart hooks](/en/hooks#sessionstart) to automate environment setup and dependency installation.1. **Automate environment setup**: Use [setup scripts](#setup-scripts) to install dependencies and configure tools before Claude Code launches. For more advanced scenarios, configure [SessionStart hooks](/en/hooks#sessionstart).
6152. **Document requirements**: Clearly specify dependencies and commands in your `CLAUDE.md` file. If you have an `AGENTS.md` file, you can source it in your `CLAUDE.md` using `@AGENTS.md` to maintain a single source of truth.6652. **Document requirements**: Clearly specify dependencies and commands in your `CLAUDE.md` file. If you have an `AGENTS.md` file, you can source it in your `CLAUDE.md` using `@AGENTS.md` to maintain a single source of truth.
616 666
617## Related resources667## Related resources