Devsy
Troubleshooting

Linux Troubleshooting

Known issues and fixes on Linux.

Files owned by an unknown user after using a local folder

When you start a workspace from a local folder and devcontainer.json sets remoteUser or containerUser, Devsy changes the folder's ownership to that user so the container can write to it. On the host the owner then shows as an unknown user. After the workspace stops, restore it:

sudo chown -R $(id -un):$(id -gn) .

Use a local folder for early work. After the devcontainer works, push it to a Git repository and use that instead.

SSH host login shells

The SSH provider supports Bash, Zsh and Fish login shells on Linux. Devsy installs the agent through the host's executable /bin/sh. Interactive terminals and environment probing use the account's configured shell. The workspace container's shell is configured separately.

In Dockerless containers, Devsy installs the agent before the image filesystem exists. When DOCKERLESS=true and /bin/sh is not executable, Devsy uses the bundled /.dockerless/bin/sh if it is executable. /bin/sh is preferred when it exists. The SSH host still needs /bin/sh.

The host needs standard bootstrap tools, including mkdir, mktemp, head with -c, wc, chmod, mv and rm. A download uses curl or wget. When neither is available, Devsy transfers the agent over the SSH connection. The agent directory must permit execution and either be writable by the account or allow noninteractive privilege escalation.

The external OpenSSH client and the built-in SSH transport use the same bootstrap launcher. Switching transports does not fix a missing /bin/sh or a restricted account.

For locked-down accounts, ask the administrator to permit /bin/sh and the required tools, provide a writable executable agent directory, and check forced-command restrictions. Keep noninteractive shell startup output off stdout, because stdout carries the bootstrap protocol and the live SSH tunnel. Send diagnostics to stderr and limit banners and prompts to interactive sessions.

VS Code SSH connection timeout

If Remote - SSH reports Connection timed out during banner exchange, a slow provider connection can exceed the default timeout. Increase remote.SSH.connectTimeout in VS Code user settings, for example to 60 seconds, and reconnect. The setting applies to all Remote - SSH hosts.

Workspace waits for the Devsy agent

If container logs repeatedly report waiting for devsy agent to be available, check whether the container's DEVSY_AGENT_PATH exists and whether its agent volume is mounted. A container created without the agent mount must be recreated after you update Devsy. Restarting it cannot change its mounts.

If a configured mount uses /opt/devsy or a path inside it, Devsy preserves that mount and installs the agent after the container starts. Docker mount flags in runArgs also use post-start installation.

Recreating a container discards changes in its writable layer. Back up any data outside persistent workspace mounts before recreating it.

Fish startup configuration

Anything in config.fish runs on every fish -c call, which can interfere with devsy internal agent workspace up. Move your customizations inside the if status is-interactive block:

if status is-interactive
    eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
    # customizations
end

SELinux

With SELinux, a mounted volume can fail with "Permission denied" even when ownership is correct. Add :Z to the volume:

{
    "workspaceMount": "",
    "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
    "runArgs": [
        "--volume=${localWorkspaceFolder}:/workspaces/${localWorkspaceFolderBasename}:Z"
    ]
}

Generic application icon on GNOME

GNOME on Wayland links a running app to its installed desktop entry. Devsy uses the desktop file name sh.devsy.app.desktop and the window identity sh.devsy.app. The Flatpak package exports a theme icon named sh.devsy.app. The DEB and RPM packages use the icon name devsy-desktop. The icon name must match the package's desktop entry.

Running an AppImage directly does not install its desktop entry. Choose Add to applications in the first-launch prompt, or open Settings > Applications menu. Devsy writes $XDG_DATA_HOME/applications/sh.devsy.app.desktop and copies the 128-pixel icon to $XDG_DATA_HOME/icons/hicolor/128x128/apps/sh.devsy.app.png (default data home: ~/.local/share). The launcher uses the permanent AppImage path, not its temporary mount.

If you decline, the AppImage still works, but GNOME Wayland can show a generic icon. Devsy does not create a launcher when a third-party integrator already manages the AppImage, or when a system or Flatpak Devsy launcher exists. Remove the conflicting installation or manage its launcher yourself, then retry.

If you move the AppImage, launch it once from the new path to update the launcher. Settings also offers Update launcher and Remove. A path containing = cannot be used in a desktop launcher, so move the AppImage elsewhere.

If you edit a launcher that Devsy created, Devsy leaves the file unchanged, including during updates and removal, and Settings reports the conflict. Manage that launcher yourself, or move it aside, before you use Add to applications again. Devsy never deletes a customized, shared or existing icon.

For manual setup, install both the desktop entry and a persistent icon file. Do not reference an icon in /tmp/.mount_*, which disappears when the AppImage exits. Use the package icon name above, or copy an icon to the user's icon-theme directory and reference that name.

After you upgrade from v1.24.0, an old pinned launcher can still reference a previous desktop file name. Unpin that launcher and pin Devsy again. Check the applications directories for older devsy-desktop.desktop entries before you create another launcher, and do not delete entries owned by another package.

ENAMETOOLONG when opening a workspace in VS Code

On some distributions the PATH is long enough to make the SSH connection string too long. Set the SSH binary explicitly in VS Code. See issue #1045.

Docker permission denied or daemon unreachable

If devsy workspace up fails with a permission error on docker.sock, add your user to the docker group and log in again:

sudo usermod -aG docker $USER

If the daemon is not running, start it:

sudo systemctl start docker

Podman

Rootless socket

Rootless Podman uses the socket $XDG_RUNTIME_DIR/podman/podman.sock. If Devsy cannot connect, start the user socket:

systemctl --user start podman.socket

Or point Devsy at it:

devsy provider set podman --option PODMAN_HOST=unix:///run/user/$(id -u)/podman/podman.sock

podman compose

podman compose hands off to an external provider, either podman-compose or a standalone docker-compose. Install one:

sudo apt-get install -y podman-compose

Install it on the host that runs Podman to support Compose-based workspaces. If scripts inside the workspace container call docker-compose or podman compose, install those tools in the container too.

BuildKit syntax

podman build uses buildah, so Dockerfiles with the # syntax=docker/dockerfile:1 line or RUN --mount fail. Remove the syntax line and avoid BuildKit mounts.

Volume permissions in rootless mode

Rootless Podman maps user IDs, so files created in the container can appear owned by nobody on the host. With SELinux, use :Z as above. Without it, fix ownership:

podman unshare chown -R $(id -u):$(id -g) /path/to/volume

On this page