Skip to main content
Run OpenCode against a repository in a CoreWeave sandbox. Send a task from your terminal, check the resulting files, and save the workspace for later. The agent process, workspace, and commands run in the sandbox. Model requests go to your configured provider.

​
Prerequisites

Before you begin, you need the following:
  • A Forge API key or CoreWeave API access token.
  • Access to a model through Serverless Inference or another OpenCode provider. Provider access and billing are separate from sandbox access.
  • A public repository URL. Private repositories require Git credentials inside the sandbox.
  • cws-agent installed by following its installation instructions.

​
Choose sandbox credentials

These examples use serverless capacity. Both credentials support serverless sandboxes. See Choose and get credentials to obtain either credential. Agent and model-provider credentials are configured separately.
Replace [WANDB-API-KEY] with your Forge API key and export it in your local terminal:
cws-agent selects Forge authentication when CWSANDBOX_API_KEY is unset.

​
Launch OpenCode with cws-agent

Use cws-agent to install OpenCode in a sandbox, clone your repository into the /workspace/project directory, and configure a snapshot mount for file system snapshots. Choose one of the following provider options. Replace [SANDBOX-NAME] with a session name containing 1 to 40 lowercase letters, digits, or hyphens. Start the name with a letter or digit. Replace [REPOSITORY-URL] with your public repository URL. Serverless Inference is the preferred provider for this guide. You can use it to access hosted open models. You can use any model and provider supported by OpenCode instead. Follow Use another model provider. Complete the Serverless Inference prerequisites, including a Forge project, and check your available inference credits. Set a Forge API key for inference. This example selects GLM 5.2 explicitly:
The --wandb preset configures Forge’s inference endpoint and limits OpenCode to that provider. This CLI preset reads WANDB_API_KEY and forwards it into the sandbox for inference. Sandbox access uses the credential selected in Choose sandbox credentials. To choose a different Forge model, replace zai-org/GLM-5.2 with an ID from the available models list.

​
Use another model provider

To use another provider, omit --wandb and --wandb-model when you create the sandbox. Export that provider’s API key locally. For example, choose one of these alternatives and replace the key placeholder:
Replace [PROVIDER-ID]/[MODEL-ID] in both fields with your OpenCode model identifier, using the anthropic/ or openai/ provider prefix as appropriate. The small_model field selects the model for lightweight tasks such as title generation. See OpenCode models.
If they’re set, cws-agent forwards ANTHROPIC_API_KEY and OPENAI_API_KEY. For providers whose keys aren’t forwarded automatically, follow their OpenCode provider configuration and use --env-passthrough [VARIABLE-NAME] for additional environment variables. Both launch options print session ready. after setup. --detach leaves the sandbox running without opening the terminal interface or importing local skills and Model Context Protocol (MCP) configuration. The 2-hour lifetime is a wall-clock limit, including setup. Stop compute when you finish.

​
Run a task and check the result

From your local terminal, ask OpenCode to write and read a file:
This runs OpenCode without an interactive terminal. --permission-mode native keeps OpenCode’s configured permissions. Without it, cws-agent defaults to accepting approval requests. If your OpenCode policy requires approval for the task, use an interactive session to approve it. See OpenCode permissions. Check the actual file independently of the agent’s response:
The output should be Hello from CoreWeave. Before you stop compute, retrieve a local copy:

​
Optional: Work interactively

From an interactive terminal on macOS or Linux, open OpenCode in the same workspace:
The --no-config-sync flag skips local skills and MCP imports. Send prompts and approve actions in OpenCode, then use /exit to return to your local terminal. When you exit OpenCode, the sandbox continues to run. Repeat the connection command to open OpenCode again. It doesn’t automatically select a previous conversation. For conversation history and resume commands, see cws-agent sessions.

​
Save, stop, and restore

After the agent finishes, snapshot the workspace and stop compute:
down saves the /workspace directory before stopping the sandbox. If the snapshot fails, the sandbox remains running. Inspect the error and retry after resolving it. To stop without waiting for an explicit snapshot, run:
Don’t rely on this command to save changes. Copy results elsewhere or confirm a completed snapshot before stopping. Restore requires a completed snapshot. To return to a workspace saved with Forge inference, make sure WANDB_API_KEY is still exported in your local terminal, then run:
Use the same --wandb-model value you launched with. If you omit it while using --wandb, restore selects the preset’s default model. For another provider, re-export its key and OPENCODE_CONFIG_CONTENT, then run:
Restore creates a new sandbox from the saved workspace. Supply environment-only credentials again. Snapshots can contain saved OpenCode logins and conversation data, but they don’t preserve running processes. Run the file check again to confirm the sandbox-proof.txt file survived. Continue with cws-agent run or the interactive connection command. Stop the restored sandbox with cws-agent down when you finish.

​
Troubleshoot

If setup or a task fails, use the following checks:
  • Sandbox authentication fails: Check the selected sandbox credential and account access.
  • Forge model requests fail: Check inference access, credits, and the model ID. Sandbox access alone doesn’t establish inference access.
  • Another provider isn’t available: Start a new session without --wandb. The Forge preset is saved in the workspace, so omitting --wandb on restore doesn’t remove it. For an existing workspace, see Forge preset configuration.
  • A headless task needs approval: Connect interactively and use OpenCode’s approval prompts before continuing.

​
Next steps

For more information, see these guides:
Last modified on October 20, 2026