Create Workspace Page

The Create Workspace form with the section navigation sidebar (Workspace settings, Host, Image, Configuration, and so on).

The Create Workspace page deploys a new container from an image onto a host. The form is split into sections, listed in a sidebar so you can jump between them. Most sections stay locked until you pick a host, because the available CPU, memory, GPUs, runtimes, networks, and volumes all come from the selected host.

Form sections

Workspace settings

• Icon an optional avatar image for the workspace. If not filled it will default to the avatar of the creator.
• Name required.
• Description optional free text.
• Auto start when enabled, the workspace is deployed and started. Disable it to create the workspace without starting it.

Host

Pick the host to deploy on. You only see hosts where you are allowed to create workspaces. Selecting a host shows its live resource metrics and resets the resource sliders, networks, and volumes to that host’s options.

Image settings

Choose what to run, in one of two modes:

• Existing pick an image already built in Trailer.
• OCI reference an external OCI image by name.

Caution

Deploying an Existing Trailer image onto a host other than the one it was built on is not recommended. A built image lives only on the host that built it. If you select the workspace host to be a different one, the image may not be present there.

The exception is an image built with the Push after build option enabled. In that case the image was uploaded to its registry, so Trailer will attempt to pull it onto the target host before deploying. For this to work, the host must be able to reach and authenticate with that registry.

Workspace configuration

• CPU and Memory requested limits, set with range sliders bounded by the host’s totals.
• Shared memory size (/dev/shm) size.

Tip

The default shared memory size is small. Some workloads need more: PyTorch, for example, uses /dev/shm for inter-process data loading and crashes with “bus error” or “out of shared memory” when it runs out. If your workspace uses PyTorch, raise this value.

To make this automatic, we recommend the official trailer-pytorch-shm-size recommendation from our catalog. When enabled, it sizes shared memory appropriately whenever PyTorch is detected in the source image (Trailer images only).

• GPUs shown only when the host reports GPUs.

Note

GPUs are detected by scanning the host’s hardware, so they appear here even when no driver is installed. Without a driver you get a basic listing (one entry per physical GPU). Installing the NVIDIA driver enriches each entry with the model name, memory, and live metrics. If the listing looks bare or a GPU is missing details, install the driver through Trailer in the host’s NVIDIA driver settings.

• Advanced settings (collapsed): container runtime, hardware acceleration, nested virtualization, nested hypervisor, and an init process toggle. Nested virtualization and nested hypervisor require the host to expose /dev/kvm; they are forced off and the toggles disabled when the host lacks KVM.

Startup configuration

Override the container’s startup command and arguments.

Caution

This overrides the image’s entire startup, so anything the image was built to run on boot no longer runs. For a Trailer image that defines its own startup, you usually want to leave this empty and configure the boot behavior on the image instead, where you can define more than one startup application. Setting an override here on such an image will likely break it.

External URLs

Define URLs (scheme, domain, subdomain, port, description) that route external traffic to a workspace port. Each URL can be left open, protected with HTTP basic auth, or restricted to specific Trailer users (internal authentication). The domain you pick also determines how the URL is served (through the agent proxy or through Traefik). See Workspace URLs and routing.

Note

Trailer prefills URL entries when the selected image ships a web interface:

• A Virtual Desktop image gets a desktop URL pointing at the desktop viewer (port 3001 for Linux, 8006 for Windows).
• An image built with one of the web-facing applications gets one URL per application: Code Server (code, port 3003), Jupyter Lab (jupyter, port 8888), and Nginx (nginx, port 8080).

Prefilled entries are ordinary rows: you still pick their domain, and you can edit or remove them like any other URL. A prefill never overwrites a URL you already added for the same port.

Environment variables

Add name/value pairs. A GUI mode and an advanced bulk-entry mode are available. In GUI mode you can also load variables from an uploaded .env file (up to 50 KB).

The bulk-entry mode is a text editor that accepts the standard .env format, one variable per line:

# comments and empty lines are skipped
DATABASE_URL=postgres://db:5432/app
DEBUG=false

Names must start with a letter or underscore and contain only letters, digits, and underscores. The value is everything after the first =, so values may themselves contain =. Quote characters are stripped from values, and lines that do not fit the format are ignored. Edits made in one mode carry over to the other.

Port configuration

Publish container ports to the host. Each mapping has a protocol (TCP or UDP), an optional host IP, a host port, and the workspace port.

Caution

The host port must be free on the host. If it is already taken, or the host will not allow the workspace to claim it, the deployment fails: the workspace goes to an error state and the reason appears in its Messages section. Fix the mapping to use a free host port, then redeploy the workspace.

Volumes

Attach volumes and bind mounts at chosen mount points.

• You do not have to leave the form to get a new volume: typing a new name into the volume picker creates it when the workspace is saved. This requires permission to create volumes (or bind mounts) on the selected host.
• After creation, only a volume’s name and description can be edited. Its type, its host, and (for bind mounts) the path on the host are fixed. See Volume Details.
• The workspace container’s own filesystem is disposable: configuration changes can rebuild the container from its image, discarding everything written inside it. Keep anything that must survive on an attached volume; volumes persist across restarts, recreations, and image changes.

See also Volumes and Create Volume.

Networks

Attach the workspace to one or more networks, with optional static IPv4 per network.

• Like volumes, networks can be created from the form: type a new name into the network picker and it is created when the workspace is saved (requires permission to create networks on the selected host). Networks created this way are always plain bridge networks; a macvlan network must be created on the Create Network page.
• After creation, only a network’s name and description can be edited. The driver and the macvlan settings (parent interface, subnet, gateway, IP range) are fixed; to change them, create a new network. See Network Details.

See also Networks.

Permissions

Grant other users view, modify, or delete access to the new workspace. View covers logs and opening the workspace; the Attach and Exec terminals need modify. See Permissions and access control for the full model, including what a workspace grant transitively reveals.

Saving

The submit button has two modes:

• Deploy create the workspace and deploy it.
• Save as template save the configuration as a reusable template instead of deploying.

Recommendations

A recommendation badge next to the submit button watches your draft. Shortly after every change, the draft is checked against the workspace recommendations installed on this instance. Recommendations are small checks that recognize common software and setups and suggest configuration: sensible resource settings for the chosen image and host, or fixes for known pitfalls (for example raising the shared memory size when the image contains PyTorch).

A matching recommendation either applies automatically (you are notified, and the change lands in the form where you can still adjust it) or appears as a suggestion. Open the badge to review the results, apply or ignore suggestions, retry one, or bring back a suggestion you ignored earlier.

Which recommendations are available is up to the administrators, who install them from catalog servers configured on the Settings page. See Recommendations for the full story.

Related Pages

• Workspaces Workspace listing
• Workspace Details View and edit a workspace
• Workspace Templates Reusable workspace definitions
• Workspace Logs Stream container logs
• Workspace Attach Attach to the main process
• Workspace Exec Run a command in the container