Working with Workspaces

OneDev workspaces let you review and write code from your browser with full terminal access. Start from a branch, tag, or commit to edit code, run builds, or use AI coding agents such as OpenCode, Claude Code, or Codex. You do not need to clone the repository or install development tools on your own computer. Closing the browser does not stop the workspace.

Choose a Workspace Environment

Sandbox and Docker are the two main options. Both provide isolation, with the same browser-based workflow for editing code, opening terminals, and accessing development servers.

Provision mode	Environment	Use it when
Sandbox	A virtual machine created by Docker Sandboxes	You need the flexibility of a VM to run development tools and services, including Docker Compose with a suitable template.
Docker	A Docker container, or a Kubernetes pod with the Kubernetes Provisioner	Your development tools and workflow fit a container image.

The less common Host mode runs directly on the host without this isolation. See Host Workspaces for cases that require direct operating-system or hardware access.

Prepare a Workspace Provisioner

A workspace spec defines the development environment; a workspace provisioner determines where and how it runs. Manage provisioners under Administration / Workspace Provisioners:

Environment	On the OneDev server (community edition)	On agents or Kubernetes (enterprise edition)
Sandbox	Server Sandbox Provisioner	Remote Sandbox Provisioner
Docker	Server Docker Provisioner	Remote Docker Provisioner, or Kubernetes Provisioner for pods

Prepare Sandbox Hosts

Follow Working with Sandbox to install Docker Sandboxes, meet its virtualization requirements, and configure login and security settings. Prepare the server or each selected agent host, running setup commands under the account that runs OneDev or its agent.

Prepare Docker Hosts

Install Docker on the server or each selected agent host, and ensure the server or agent process can use it. For Kubernetes workspaces, configure a Kubernetes Provisioner with access to the cluster instead.

Select a Provisioner

When no provisioners are configured, OneDev can auto-discover a Server Sandbox or Server Docker Provisioner if the corresponding runtime is available. Configure a provisioner explicitly to control applicable projects, resource limits, or concurrency, or to use agents or Kubernetes.

For a remote provisioner, select the agents that should run the workspaces. Enterprise provisioners require an active subscription; you can request and install a trial key under Administration / Subscription Management.

A spec can name a Provisioner or leave it empty. If provisioners are configured, an empty value selects the first enabled provisioner that matches the spec's provision mode and applies to the project. A named provisioner must meet those same conditions.

Define a Workspace Spec

Open Settings / Workspace Specs in your project. You can define multiple specs. Child projects inherit their parents' specs and can override them by using the same name.

For this walkthrough, create a spec from an OpenCode template:

1. Select Create from Template.
2. Select OpenCode.
3. Choose In Sandbox or In Container, according to the environment prepared above.
4. Give the spec a descriptive name, such as OpenCode in Sandbox or OpenCode in Docker.

Templates preconfigure the shell, shortcuts, user data, and task automation. OneDev's workspace images include the coding agent, tod CLI, and companion skills. You can choose another coding-agent template or define a spec from scratch.

Review Runtime Settings

The two OpenCode templates use the same image with different runtime settings:

Setting	Sandbox workspace	Docker workspace
Provision Mode	Sandbox	Docker
Image or template	Template: 1dev/opencode	Image: 1dev/opencode
Required tools	Shell, Git, Python 3, and tmux	Shell, Git, and tmux
Workspace user	The sandbox template image's default user	The user and group IDs in Run As, under More Settings

Sandbox configuration	Docker configuration

Customize the OpenCode image to include your project's tools, or follow Build a Sandbox Template to build and publish your own template with or without Docker support. Select a Provisioner if needed, following the rules above.

Review Shared Settings

These settings apply to both Sandbox and Docker workspaces:

• Shell — The OpenCode templates use Bash. Configure setup commands here to prepare the development environment and teardown commands for cleanup.
• Shortcuts — Commands you can launch from the workspace toolbar. OneDev opens the first shortcut automatically when creating a workspace. Without shortcuts, it opens a terminal using the configured shell.
• User Data — User-specific files that the same user's later workspaces can reuse through the same key and path. User data is saved only after the workspace is deleted.
• Exposed Ports — Ports for accessing services running in the workspace. Add 3000 for the development-server example below. OneDev displays links to the mapped ports on the workspace page.
• Task Automation — Lets AI users perform assigned work without an interactive terminal. An AI user assigned an issue or pull request can create a workspace and run the configured command with the task prompt.

Save the spec after reviewing these settings.

Create and Use a Workspace

From a branch, tag, or commit, create a workspace using your new spec. This requires the project's Create Workspace permission:

OneDev provisions the environment and opens the workspace.

Open Terminals and Shortcuts

The numbered toolbar controls let you:

1. Launch configured shortcuts.
2. Open another terminal tab.
3. Access services through the workspace's exposed ports.

tip

For Nerd Font icons in the terminal, install a Nerd Font on the machine running your browser. Safari blocks access to user-installed fonts, so use another browser for this feature.

Run a Development Server

In the OpenCode terminal, enter a prompt such as:

Install Node.js via nvm and create an example Next.js project

Adapt the prompt to the tools already in your image or template. Include frequently used tools in the image so they are ready in every workspace.

After OpenCode creates the project, open a terminal tab in the project directory and run npm run dev. Ensure the server listens on 0.0.0.0:3000 so it is reachable through the exposed port.

You can also define a shortcut to launch the development server. Its terminal tab will use the shortcut's name.

Open the port mapping menu to access the development server:

For a Docker Compose stack inside a sandbox, publish the application's port from its Compose service to the sandbox. Also add that port to the spec's Exposed Ports so OneDev can provide an access link.

Review Changes and Return Later

The Changes tab shows modified files and provides actions to stage, commit, and push them to the repository:

Return to an existing workspace from its associated branch or from the project's Workspaces page:

Delete the Workspace When Finished

Commit and push changes you want to keep, then delete the workspace. Deletion also saves the configured user data for reuse. Inspect saved data on the workspace data page:

Host Workspaces

Host mode is useful for specialized work such as iOS, Windows-native, or hardware-dependent development. Commands run directly on the server or agent with that process's privileges, without sandbox or container isolation. Enable it only for trusted projects.

Set Provision Mode to Host and configure a Server Host Provisioner or Remote Host Provisioner. The remote option requires an enterprise subscription and an agent selection. Install tmux and your development tools on each workspace host.