Remote IDE: Using Theia IDE in your development environment

Remote IDE: Using Theia IDE in your development environment

Bildschirmfoto 2020-12-06 um 13.50.30.png

If you are working from multiple machines within the same network e.g. in your home office or within your company premise you probably have your project available within that environment. Colleagues can see the project within the network environment or you might simply switch the machine you are working on. There are multiple reasons to do this. While I absolutely love cloud services like CodeSandbox which come with tons of templates and community projects, it has its limits which are possible networking restrictions on your premise or regulatory concerns for external services.

What is Theia IDE ?

If you are familiar with Visual Studio Code you will find your way in as it "embraces many of the design decisions and even directly supports VS Code extensions". It runs as a web application in your browser and also provides docker containers - which is the way to go in this post.


  • Linux based computer which is accessible over your dev network
  • Docker installed on the machine
  • SSH Access to the machine
  • Your project checked out

First start

Connect to your machine and move to your projects location

cd ~/projects/your-project

Now you can start Theia IDE for Docker.

# Linux, macOS, or PowerShell
docker run -it --init -p 3000:3000 -v "$(pwd):/home/project:cached" theiaide/theia:next

There is a lot happening in that line. If you are not familiar with docker let me break it down:

docker run is the initial command to run a docker container. We are running theiaide/theia:next which is the default flavour of Theia. If you are running that command for the first time you will find that it is Unable to find image 'theia:latest' locally and starts downloading it.

-it tells Docker to run it interactively (-i) over our current SSH session (-t). Later we might want to let Theia run without an open SSH session but for now we want to see the output and if everything starts up correctly. You can end the session as normal with Ctrl+C.

--init Runs initial processes the Theia container comes with

-p 3000:3000 is used to define the ports. While the first is the host port and the second is the internal port. You want to leave the internal container port as it is and choose a port that fits your environment, e.g. -p 8080:3000

-v "$(pwd):/home/project:cached" tells Docker to use the current directory as workspace. You might choose something else like /home/username/projects but sticking to $(pwd) seems to be the most versatile. Because we are making an actual folder available to the Theia Docker container that might come with implications. Check the errors section below.

Typical errors I encountered:

Write permissions on your project

If you encounter issues saving your edited files this might have to do with the Theia Container not being able to write on the shared volume of your project. Add the following -u Parameter and a snippet which extracts your current user id and group id:

# Run Theia with your local user by adding -u USER_ID:USERGROUP_ID, e.g.: 
docker run -it --init -p 3000:3000 -u $(id -u ${USER}):$(id -g ${USER}) -v "$(pwd):/home/project:cached" theiaide/theia:next

Write permissions on Theia

If you set the host user with the -u parameter I encountered the issue of not being able to install plugins. For now I sticked to running Theia without that parameter to set things up and then switch back to -u for working on projects.

Port in use, take another port

docker: Error response from daemon: driver failed programming external connectivity on endpoint CONTAINER_NAME (CONTAINER_ID): Bind for failed: port is already allocated.

This can be solved by either stopping the process which uses the same port (possibly one of the web projects running on your dev server) or choosing another port, for example 8000: -p 8000:3000

Running it in the background

When we end the SSH session, chances are Theia stops as well. So exchange the -it parameter with -d which means detached.

docker run -d -u $(id -u ${USER}):$(id -g ${USER}) -p 3000:3000 -v "$(pwd):/home/project:cached" theiaide/theia

That way it will run in the background. To make sure it really runs go to your dev servers address: your-dev-server-ip:3000 or run docker ps and check for theiaide/theia being in the list.

Stopping Theia

If you run Theia in the background you might want to stop it. First check if its container is running and which ID it has by running docker ps

CONTAINER ID        IMAGE                COMMAND                  CREATED              STATUS              PORTS                                                                                                                            
27add3888c6f        theiaide/theia   "node /home/theia/sr…"   About a minute ago   Up About a minute>3000/tcp

Okay, so our container runs with a specific ID. Lets tell docker to stop it by executing docker stop CONTAINER ID, in my case: docker stop 27add3888c6f


Theia IDE Docker Repo: Here you might find language specific flavours of the IDE.

Docker and User permissions: