diff --git a/content/manuals/ai/sandboxes/cloud/environment-files.md b/content/manuals/ai/sandboxes/cloud/environment-files.md new file mode 100644 index 0000000000..32bf6d37d4 --- /dev/null +++ b/content/manuals/ai/sandboxes/cloud/environment-files.md @@ -0,0 +1,289 @@ +--- +title: Use environment files in the cloud +linkTitle: Environment files +description: Create a repeatable cloud sandbox with sbx env, copy in your project, work with an agent, and retrieve your changes. +keywords: docker sandboxes, cloud sandbox, sbx env, sbxenv, environment file +weight: 25 +--- + +Use an environment file to share a cloud sandbox's agent, tools, environment +variables, and resource limits with your project contributors. Run +`sbx --cloud env` to apply that configuration on Docker-managed infrastructure. + +A cloud environment has its own filesystem. It doesn't mount or synchronize +directories from your machine, so leave `workspace` out of the file. Copy your +project into the sandbox or clone it there, and copy the results back or push +your commits before removing the sandbox. Credentials and network policy are +also separate from your local sandbox configuration. Host lifecycle commands +still run on your machine, with your privileges. + +> [!NOTE] +> `sbx env` is experimental. The command interface and file format may change. + +## Prepare your environment + +Complete the [cloud prerequisites](_index.md#prerequisites), including activating +cloud access and signing in with `sbx login`. Cloud compute charges apply. + +This walkthrough uses Claude Code to work on a local project named `web-app`. +Configure an Anthropic API key in the cloud secret store before creating the +sandbox: + +```console +$ sbx --cloud secret set anthropic +``` + +The command prompts for the key. For other agents and authentication options, +see [Authenticate cloud agents](credentials.md). A credential configured for a +local sandbox isn't available in the cloud. + +If you want the agent to push changes to GitHub, configure a GitHub token +before creating the sandbox: + +```console +$ sbx --cloud secret set github --sandbox cloud-web-app +``` + +The command prompts for a token. Use one with write access to your repository. +The `--sandbox` value must match the environment's `name`. Cloud environments +select their credentials at creation: adding a GitHub secret afterward won't +make it available to an existing environment. If you decide to push later, +copy your work out first, then recreate the environment with the secret. + +Save the following as `cloud.sbxenv.yaml` in your project's root directory. +You can keep the file elsewhere if you prefer: its location doesn't determine +which files are available in the cloud sandbox. + +```yaml +schemaVersion: "1" +name: cloud-web-app +agent: claude + +env: + NODE_ENV: test + +sandboxOptions: + cpus: 2 + memory: 4g +``` + +This selects Claude Code, sets `NODE_ENV` for the sandbox, and requests two +CPUs and 4 GiB of memory. Resource limits must match a +[cloud size](usage.md#choose-resources-and-platform). You can also add +[`kits`](../configuration/environment-files.md#kits) to install project tools. + +## Create the sandbox and add your project + +From your project directory, review the plan and create the sandbox without +attaching: + +```console +$ sbx --cloud env plan ./cloud.sbxenv.yaml +$ sbx --cloud env create --ttl 2h --on-timeout delete ./cloud.sbxenv.yaml +``` + +The plan shows the configuration and inherited cloud credentials. Creation +asks you to approve the plan before applying it. This example explicitly +deletes the sandbox after two hours, so retrieve your work before then. +Without timeout flags, a cloud sandbox expires after one hour, and the service +stops sandboxes that can be resumed and deletes the rest. See +[Configure expiration](usage.md#configure-expiration) for other options. + +Copy your project into the sandbox's workspace: + +```console +$ sbx --cloud cp . cloud-web-app:/home/agent/workspace/web-app +``` + +Use a destination that doesn't already exist for this first copy. Copying a +directory to an existing directory nests it under its source name. Review the +files you're uploading: `cp .` doesn't respect `.gitignore`. It includes hidden +files such as `.env`, Git history, dependencies, and build output. For larger +projects, prepare a clean staging directory containing only the files you want +to upload, and copy that directory instead. Copying is a one-time transfer: +later edits on either side aren't synchronized. Directory uploads skip symbolic +links and empty directories and report what was skipped. Install dependencies +inside the sandbox rather than copying a local dependency directory. + +For a Git workflow, you can instead clone a repository inside the sandbox and +push commits to your remote. Configure [cloud credentials](credentials.md) for +private repository access and [cloud network policy](network-policy.md) for +the destinations your project needs. Copying includes uncommitted local work; +cloning a specific commit gives contributors a reproducible starting point. + +### Automate the initial upload + +To upload your project whenever you create a fresh sandbox, add a `postCreate` +command to the environment file. This automates the initial upload as part of +setup. + +```yaml +lifecycle: + postCreate: + - name: Upload project + command: sbx --cloud cp . "$SBX_SANDBOX_NAME:/home/agent/workspace/web-app" +``` + +Here, `.` resolves to the directory containing the environment file. If you +keep the file elsewhere or upload from a staging directory, set the command's +`workdir` to the project or staging directory. The same file selection rules +as the manual copy apply, including copying ignored files and skipping symbolic +links and empty directories. + +The command runs on your machine after sandbox creation and before `run` +attaches to the agent. `SBX_SANDBOX_NAME` contains the sandbox name, including +any `--name` override. Reconnecting skips `postCreate`, preserving the agent's +work. Later local edits aren't uploaded automatically. + +With this block in place, use `sbx --cloud env run ./cloud.sbxenv.yaml` to create +the sandbox, upload the project, and attach to the agent. It replaces the manual +upload step for future sandbox creation. + +If the upload fails, the sandbox has already been created and remains available. +Inspect it and finish transferring files manually, or remove it with +`sbx --cloud env rm ./cloud.sbxenv.yaml` before trying a fresh creation. + +See [Automate setup with host commands](#automate-setup-with-host-commands) for more +about lifecycle commands and approval. + +## Work with the agent + +Attach to Claude Code using the same environment file: + +```console +$ sbx --cloud env run ./cloud.sbxenv.yaml +``` + +For example, ask the agent: + +```text +Work in /home/agent/workspace/web-app. Find the test and lint commands in +package.json, install the dependencies, and run those checks. Fix any failures +and explain your changes. Ask before changing dependencies. +``` + +Use `run` again to reconnect to the existing sandbox. It creates a sandbox if +one doesn't exist. Pass `--ttl` and `--on-timeout` only when creating a sandbox: +`run` rejects those flags when attaching to an existing one. + +Press `Ctrl+\` to detach while leaving the agent running. You can also run a +command without an agent session, for example to inspect the working tree of +a copied Git project: + +```console +$ sbx --cloud env exec ./cloud.sbxenv.yaml -- \ + git -C /home/agent/workspace/web-app diff --stat +``` + +For subsequent environment commands, keep the same machine, cloud endpoint, +Docker account, and ordered environment file paths. The CLI records the cloud +sandbox's identity locally to manage it across invocations. + +## Retrieve your work and clean up + +After the agent finishes, copy the project back to a separate local directory +so you can review it before updating your original files: + +```console +$ sbx --cloud cp cloud-web-app:/home/agent/workspace/web-app ../web-app-result +``` + +Use a destination that doesn't already exist. + +### Push changes to GitHub instead + +If you configured the GitHub secret before creating the environment, you can +retrieve changes through Git instead of copying files. This works with a +repository cloned inside the sandbox or a copied Git repository whose +`.git` directory contains the repository history. Use an HTTPS GitHub remote +that your token can push to. + +For example, ask the agent: + +```text +In /home/agent/workspace/web-app, review the diff, create a branch named +cloud-fixes, commit the changes for this task, and push that branch to origin. +``` + +Then, from your local checkout, fetch the branch and check it out for review: + +```console +$ git fetch origin +$ git switch --track origin/cloud-fixes +``` + +The commits are available on GitHub even after the sandbox is removed. + +### Remove the environment + +When you've saved your work, remove the environment: + +```console +$ sbx --cloud env rm ./cloud.sbxenv.yaml +``` + +Removal asks for approval and deletes the sandbox and secrets provisioned by +this environment. Inherited credentials, such as the Anthropic key configured +earlier, remain. Global bindings remain unless you pass `--prune-bindings`. +Files stored only in the sandbox are lost on deletion. + +For unattended commands, use `--force` with `create`, `run`, or `rm` to approve +the plan for that invocation. Use `run --detach` when no interactive terminal +is available. + +## Adapt an existing environment file + +Cloud environments support agents, kits, environment variables, CPU and memory +limits, credentials for supported providers, and host lifecycle commands. +They support a subset of the [environment file fields](../configuration/environment-files.md#file-reference). +Use the following checks before reusing a local file. + +### Remove local settings + +Remove these declarations: + +- `workspace`, `additionalWorkspaces`, and clone options +- `ports`, `registries`, and `mcp.servers` +- `sandboxOptions.template`, `profile`, `pullPolicy`, `skills`, `display`, + `gpu`, `usb`, and `writableEnvFiles` + +Unsupported settings are rejected before host commands or provisioning run. +Pass the cloud file path explicitly to avoid loading local settings from +`~/.sbxenv.yaml`. For services and integrations, use the cloud commands to +[expose ports](usage.md#expose-a-port) and [load MCP servers](usage.md#load-an-mcp-server). + +### Automate setup with host commands + +Lifecycle commands connect the cloud environment’s lifecycle to work on your +machine. They’re useful when setup or cleanup depends on local files, tools, or +credentials. Including those steps in the environment file makes the workflow +repeatable, even when it spans your machine and the cloud sandbox. + +Use `initialize` to prepare files before creation and `preRemove` to retrieve +results when you run `sbx --cloud env rm`. `preRemove` doesn't run when the +cloud service deletes an expired sandbox, and a failed command doesn't prevent +removal. Save work you need to keep before removing the environment. + +Host commands appear in the plan and require approval. See +[Lifecycle commands](../configuration/environment-files.md#lifecycle) for phase +timing, working directories, and approval options. + +### Configure cloud credentials + +The plan shows inherited cloud credentials. Sandbox-scoped credentials override +account defaults, and credentials declared in `secrets` override both. Use +[`snapshot: true`](../configuration/environment-files.md#secrets) to resolve a +host command or vault reference once and upload the value. Snapshots don't +refresh. Dynamic secret sources and custom credential providers aren't +supported. Credential bindings require cloud support for kit credentials and +explicit approval of the kit's injection domains. + +### Apply changes and recover interrupted creation + +Changes to secrets, bindings, kits, or resource limits require recreating the +sandbox. Updated `env` values apply to subsequent sessions. Rejoining a running +agent keeps that process's environment. + +If creation is interrupted, retry the same command and unchanged declaration +within 23 hours. Unresolved requests prevent removal. Follow the recovery +message and retain its journal until the original requests are resolved. diff --git a/content/manuals/ai/sandboxes/cloud/local-vs-cloud.md b/content/manuals/ai/sandboxes/cloud/local-vs-cloud.md index 418ff29799..1f4521efeb 100644 --- a/content/manuals/ai/sandboxes/cloud/local-vs-cloud.md +++ b/content/manuals/ai/sandboxes/cloud/local-vs-cloud.md @@ -42,7 +42,7 @@ following local features don't apply in cloud mode: The CLI rejects local-only flags used with `--cloud` instead of ignoring them. -You can use [environment files](../configuration/environment-files.md#use-a-cloud-environment) +You can use [environment files](environment-files.md) with `sbx --cloud env`. Cloud environments support a subset of the local configuration fields, including agents, environment variables, resource limits, and credentials. Remove host workspace and port mappings before using a local diff --git a/content/manuals/ai/sandboxes/cloud/usage.md b/content/manuals/ai/sandboxes/cloud/usage.md index 716312b1d6..99b3ae95bc 100644 --- a/content/manuals/ai/sandboxes/cloud/usage.md +++ b/content/manuals/ai/sandboxes/cloud/usage.md @@ -353,7 +353,7 @@ To load arguments from a file, pass `--kit-args-file ` with one with `--kit-arg` override values from the file. To declare reusable cloud configuration in a file, see -[Use a cloud environment](../configuration/environment-files.md#use-a-cloud-environment). +[Use environment files in the cloud](environment-files.md). ## Load an MCP server diff --git a/content/manuals/ai/sandboxes/configuration/environment-files.md b/content/manuals/ai/sandboxes/configuration/environment-files.md index 13f5e596a6..c15a6022ac 100644 --- a/content/manuals/ai/sandboxes/configuration/environment-files.md +++ b/content/manuals/ai/sandboxes/configuration/environment-files.md @@ -425,111 +425,15 @@ Commands and vault references under `secrets` resolve on the host, so the automation runner must provide the referenced tools and authentication. The secret values remain outside the environment file. -### Use a cloud environment +## Use a cloud environment -Use `sbx --cloud env` to manage a cloud sandbox from an environment file. For -account and CLI requirements, see [Cloud sandboxes](../cloud/_index.md). +Use `sbx --cloud env` to create a sandbox on Docker-managed infrastructure from +an environment file. Cloud sandboxes don't mount or synchronize local project +files, and local credentials aren't available to them. You copy files into the +sandbox or clone a repository there, then retrieve your work before removing it. -#### Create a cloud environment - -Save this as `cloud.sbxenv.yaml`: - -```yaml -schemaVersion: "1" -name: cloud-project -agent: shell - -env: - PROJECT_NAME: example - -sandboxOptions: - cpus: 2 - memory: 4g -``` - -Resource limits must match a [cloud size](../cloud/usage.md#choose-resources-and-platform). -Review the plan, create the sandbox without attaching, and run a command: - -```console -$ sbx --cloud env plan ./cloud.sbxenv.yaml -$ sbx --cloud env create ./cloud.sbxenv.yaml -$ sbx --cloud env exec ./cloud.sbxenv.yaml -- printenv PROJECT_NAME -``` - -To attach to the agent, use `sbx --cloud env run ./cloud.sbxenv.yaml`. - -#### Adapt a local environment file - -Cloud environments support agents and kits, environment variables, CPU and -memory limits, credentials for supported providers, and host lifecycle commands. -Lifecycle commands still run on your machine with your privileges. - -Before using a local file in cloud mode, remove: - -- `workspace`, `additionalWorkspaces`, and clone options -- `ports`, `registries`, and MCP server definitions -- Local sandbox options: GPU, USB, display, shared skills, templates, and - governance profiles - -Unsupported settings are rejected before host commands or provisioning run. -Transfer project files with [`sbx --cloud cp`](../cloud/usage.md#transfer-files) -or clone a repository inside the sandbox. - -#### Set expiration - -Set expiration when creating a cloud environment with `--ttl` and -`--on-timeout`. For example, restart the sandbox when it expires: - -```console -$ sbx --cloud env create --ttl 4h --on-timeout restart ./cloud.sbxenv.yaml -``` - -The `restart` action stops and immediately starts the sandbox. With this action, -an explicit `--ttl` must be at least one hour. You can also choose `stop` or -`delete`; see [Configure expiration](../cloud/usage.md#configure-expiration). - -These flags apply only when creating a cloud sandbox. `sbx --cloud env run` -accepts them when creating a sandbox, but rejects them when attaching to an -existing one. Local environment commands reject both flags. - -#### Configure credentials - -The plan shows inherited cloud credentials. Sandbox-scoped credentials override -account defaults, and credentials declared in `secrets` override both. - -Declare literal values or use [`snapshot: true`](#secrets) to resolve a host -command or vault reference once. Dynamic secret sources and custom credential -providers aren't supported. Credential bindings require cloud support for kit -credentials and explicit approval of the kit's injection domains. - -Changes to secrets and bindings require recreating the sandbox. - -#### Reuse the environment - -For later commands, use the same machine, cloud endpoint, and ordered file -paths, and sign in with the same Docker account using `sbx login`. - -Updated `env` values apply to subsequent sessions. Rejoining a running agent -keeps that process's environment. - -#### Remove the environment - -Remove the environment when you're finished: - -```console -$ sbx --cloud env rm ./cloud.sbxenv.yaml -``` - -Removal deletes the sandbox and only the secrets provisioned by this -environment. Inherited secrets remain. Global bindings remain unless you pass -`--prune-bindings`. For unattended runs, use `--force` with `create`, `run`, or -`rm` to approve the plan. - -#### Recover from interrupted creation - -If creation is interrupted, retry the same command and unchanged declaration -within 23 hours. Unresolved requests prevent removal. Follow the recovery -message and retain its journal until the original requests are resolved. +For a walkthrough, supported settings, and lifecycle differences, see +[Use environment files in the cloud](../cloud/environment-files.md). ## Review an environment plan