Skip to main content

Remote development

If your local machine does not meet all requirements for development with the VIKTOR platform you can choose to use a remote development environment. A remote development environment is an environment that is hosted in the cloud and can often be used together with an IDE in the browser. Examples of remote development environments are GitHub Codespaces, GitPod, and Replit.

Setup instructions

Follow the steps below to set up a GitHub codespace and get started with developing on the VIKTOR platform:

  1. Create a new repository:

  2. Create a codespace:

    • In the repository created in step 1 click "Code" -> "Codespaces" -> click the three dots -> "New with options..."

    • Under "Recommended secrets" specify the 3 values:

      • VIKTOR_ENV:
        • Free users:
        • Paid users: {company} (substitute {company} with the name of your company)
      • VIKTOR_DEV: the email address that your VIKTOR account is registered on.
      • VIKTOR_TOKEN: your development token.

      How do I obtain a token?

      You can generate a token by logging in to your development environment. If you are logging in for the first time, use the link from the activation mail to generate a password to log in to the development environment. Alternatively, you can click "Forgot Password" to receive a mail to (re)set your password. After logging in close the first-time user modal (this modal is shown when you have not activated your account yet) and go to the settings page by clicking the three dots next to your name in the top-right corner and after that clicking 'Settings'. Select the 'Developer Account' tab and click the 'Generate new token' button.

      How to generate a new token

    • Click "Create codespace"

      In case you need to update these settings in the future, you will find them stored under "Codespaces secrets" in your GitHub settings.

  3. Run the following command to verify the configuration:

    viktor-cli check-system

    This should print: V Your system is ready to use VIKTOR with isolation mode 'venv'.

You can find all your codespaces, grouped by repository, in the dashboard: For more info about codespaces please refer to the official codespaces docs.

Congratulations, you are now ready to start coding your first VIKTOR app! 🚀

Build a simple app

Once your cloud IDE is running, you can enter the following commands in the terminal to create, install, and start an empty app template.

viktor-cli create-app --app-type editor

Once you have your VIKTOR files, you can clear the database with:

viktor-cli clear

Install the app with:

viktor-cli install

And start the app with:

viktor-cli start

If all went well, your empty app is installed and running in your development workspace. Do not close the terminal as this will break the connection with your app.

Your terminal should show something like this:

 INFO     : Connecting to platform...
INFO : Connection is established: <---- here you can see your app, the exact URL might be different for you
INFO : The connection can be closed using Ctrl+C
INFO : App is ready
Re-starting your app
  • You need to create a repository using the template for each app that you make. To start developing a new app, you can repeat the steps in 'Build a simple app'.
  • The app will update automatically once you start adding code in, as long as you don't close the terminal or codespaces.
  • Did you close your terminal? Use viktor-cli start to start the app again. No need to install, clear, etc.

Adding a 3D geometry

Lets jump into our file and start working on our VIKTOR application. The first thing we will do is make sure we can see all our progress in the 3D view. To do this we will start by importing VIKTOR's SquareBeam, GeometryResult and GeometryView.

from viktor.geometry import SquareBeam 
from viktor.views import GeometryView, GeometryResult

For now we will leave the Parametrization as is. In the Controller, lets add the GeometryView. The geometry that we will display is the SquareBeam, for now, lets make it a 1-by-1-by-1 block.

class Controller(ViktorController):
label = "your entity type"
parametrization = Parametrization

@GeometryView("3D Geometry", duration_guess=1)
def get_geometry(self, params, **kwargs):
block = SquareBeam(
return GeometryResult(block)

Save your, if you closed the terminal enter viktor-cli start and go to your cloud environment (e.g. and enter your developement workspace by clicking the open button to see your cube.

If all went well you should now see a simple cube in the middle of your screen similar to the image below. You can zoom and pan around it with your mouse. If you click the three dots on the top right you can see some options that come standard with VIKTOR's GeometryView such as exporting the model to a .obj. file.

Want to learn more?

If you would like to continue learning and expand this application into a parametric high-rise building, feel free to follow our parametric building tutorial from this point onwards!

Otherwise feel free to continue the 'Getting started' section here.