# What remote workspace gives you


A remote workspace puts the agent, terminal, and optional browser IDE inside Zerops, next to private networking and ZCP access.

The `zcp@1` service runs the same `zcp` binary used by local setup, but broad shell permissions and private service access stay in a clean Zerops service instead of on your laptop.

Use remote setup when you want the default workspace, a safer boundary for broad agent permissions, or a preconfigured environment with Claude Code and Browser VS Code.

App code still deploys to your app runtime services. The `zcp` service is the workspace and control surface; it is not the application runtime.

Taking over is straightforward in this setup. You open the same workspace, terminal, files, and workflow status the agent used, then continue, inspect, or stop the work from there.

## What it includes

- **`zcp@1` workspace service.** Runs ZCP inside Zerops and gives the agent project-scoped operations.
- **Platform-injected `ZCP_API_KEY`.** Zerops injects the token into the workspace; you normally do not set it by hand.
- **Bundled Claude Code when enabled.** The **Include Coding Agent** option installs and preconfigures Claude Code. You authenticate with your own Claude subscription login or API key.
- **Browser VS Code when enabled.** The **Cloud IDE** option gives you a browser editor, terminal, and a place to supervise or take over the agent session.
- **Private networking.** The workspace can reach managed services by hostname without laptop VPN.
- **Open workspace model.** You can add other agent CLIs, private MCP servers, helper processes, dotfiles, package installs, or a derived team image.

For the local alternative, see [Run locally](/zcp/setup/local-agent-bridge). For the tradeoffs, see [Remote or local setup](/zcp/setup/choose-workspace).

## Choose a starting point

### First-time trial

Use the [Quickstart](/zcp/quickstart) when you want the guided recipe route. It covers the recipe catalog, **AI Agent** environment, Claude Code authentication, Browser VS Code, first product prompt, and proof.

After provisioning, continue with a product prompt in [Build and ship](/zcp/workflows/build-with-zcp).

### Recipe with AI Agent environment

Use this when you want a guided stack baseline for development or staging. A recipe with an **AI Agent** environment creates app services, managed services, and the `zcp@1` workspace together.

Keep **Coding Agent** enabled when you want bundled Claude Code. Keep **Cloud IDE** enabled when you want Browser VS Code.

### New Zerops setup with remote setup enabled

Use this when you want blank services or a custom stack.

1. Open [Add new project](https://app.zerops.io/dashboard/project-add).
2. Enter the project name, region, and tags.
3. Enable the `zcp@1` remote setup service.
4. Keep **Include Coding Agent** enabled if you want bundled Claude Code.
5. Keep **Cloud IDE** enabled if you want browser VS Code.
6. Create the project.

This gives you the `zcp@1` workspace. App runtimes and managed services may still be created later by normal ZCP app work.

### Existing development or staging setup

Use this when runtime or managed services already exist in development or staging. Do not add `zcp` to production; promote verified work through your release process.

Add a `zcp` service from the dashboard the same way you add another Zerops service. The workspace appears next to the existing services and receives ZCP access from the platform.

The agent should still read current state before changing anything. Existing services are context, not instructions for the next task.

## Open the workspace

For a returning remote workspace, open the existing `zcp` service:

1. Open the project in the [Zerops dashboard](https://app.zerops.io/).
2. Open the `zcp` service.
3. Use **Browser VS Code** when **Cloud IDE** is enabled.
4. Complete the Claude Code login or API-token flow if prompted.

After authentication, Claude Code is connected to ZCP and ready to work from the Browser VS Code terminal. If the workspace was already authorized, use the same route to resume, supervise, or take over work.

First load can take a minute while the image, Cloud IDE, and bundled agent finish starting. If the page opens before the service is ready, wait until the service is running and reload.

## Use your own editor or tools

Browser VS Code is the quickest entry point, not the only one.

Editors that support remote development can connect to the workspace or runtime services over SSH, depending on how your team wants to work. Common options include VS Code Remote SSH, JetBrains Gateway, Cursor, Zed, and plain SSH.

This keeps the agent and private network inside Zerops while letting you use a desktop editor UI. Broader editor patterns live in [Local & Remote Development](/features/local-remote-development#native-ide-over-ssh).

You can also install another agent CLI or additional MCP servers inside the `zcp` service. The bundled Claude Code flow is a convenience, not a closed product boundary.

## Advanced customization guardrails

Tools installed inside the `zcp` service may see workspace environment variables, private networking, and any runtime files mounted into the workspace. Use trusted and pinned tools. Keep model credentials, git delivery tokens, external API keys, and production credentials out of the workspace unless the current task explicitly needs them.

## What belongs where

| Concern              | Where it belongs                                                                                                            |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Agent workspace      | The `zcp@1` service: agent CLI, browser VS Code, shell tools, MCP servers, helper processes, dotfiles.                      |
| App code deploys     | Your app runtime services; not the `zcp` workspace service.                                                                 |
| `ZCP_API_KEY`        | Injected by Zerops into the `zcp` workspace.                                                                                |
| Agent account        | Your Claude subscription login or model API credential. Zerops wires the agent to ZCP, but the agent account remains yours. |
| Git credentials      | Configured inside the workspace when the agent should commit or push from remote setup.                                     |
| Production release   | A separate production project and release process.                                                                          |

## Runtime file access

Remote setup can mount runtime service filesystems into the `zcp` workspace after the first setup pass. Each mounted runtime appears as its own folder. Editing a mounted file changes the file inside that runtime service, with no upload step from your laptop.

Filesystem reach is narrower than network reach. The workspace can reach services over the private network, but it only sees runtime files mounted into it.

## Make customization persistent

The `zcp@1` service is a normal Zerops service. One-off shell installs disappear when the service is rebuilt unless you make them part of the service setup.

Use these patterns:

- **Small additions:** put package installs, dotfiles, or bootstrap scripts into service init commands.
- **Team-standard workspace:** build a derived image based on `zcp@1` with required tools already present.
- **Helper processes:** run private helpers next to the agent and editor workspace when your team needs internal integrations.

Keep app runtime build steps with the runtime services. The remote workspace carries the agent, tools, and ZCP access; runtime services own app builds and deploys.

## Next steps

- [Build and ship](/zcp/workflows/build-with-zcp) - normal app work after setup.
- [Tokens and credentials](/zcp/security/tokens-and-project-access) - how `ZCP_API_KEY`, git credentials, and CI secrets differ.