Getting Started

You’ll get started with Heim by going through a few simple steps. Read on to find out how to get the Heim runtime going, and how to get started with using your own applications in Heim.

1. Install required software

   Install any software required for working with the language or framework you are interested in.

   Heim currently supports working with C#, Python, JavaScript / TypeScript, Rust, C and Go .

   Read more about installing the respective requirements for the currently supported languages, and how to install the Heim tools in the Heim Installation documentation.

   
   

2. Install Heim

   Heim can be downloaded and installed in multiple ways. Depending on your operating system, Heim may be installed as an app, from an installer package, or by downloading an archive and unpacking it, and then running a script included in the package.

   We currently support installing Heim on Windows, macOS, and Linux.

   
   

   Troubleshooting

   The Heim installer, or installation script, may add path variables to your operating system.

   In some instances it may be necessary to reboot your operating system after installing, or even re-run the installer with elevated access for the necessary environment variables to be available for Heim to use. Try this if Heim commands aren’t working, or if folders referred to in the steps below appear to be missing after installing Heim.

   
   

3. Start Heim runtime.

   Assuming that Heim has been correctly installed, starting the Heim runtime is as easy as running the following simple command in a terminal or console window:

       heim start

   
   

   Alternatively, you may access the heim-runtime file directly, by typing the following command in a terminal or console window:

       heim-runtime

   
   

   Output

   When you start and use the Heim runtime, it will output information about successful and unsuccessful operations in the window you start it in.

   
   

4. Using applications

   There are two ways of getting started using applications in Heim. In broad strokes, the options are to either copy an existing application into Heim, or to create an application from a template.

   Click the tabs below to read more about how to start using applications in Heim.

   
   
   use existing application

   <OPTIONAL> Place valid application folder in Heim directory

   If you want to use an existing, valid application that has been created elsewhere, start by placing the application folder in the directory you want to mount the application from.

   In the examples to follow, we’ll assume that you are using windows, and that you place your application folder in the C:\heim-applications directory.

   
   

   Deploy the application

   To deploy your application, use the following command in a terminal or console window, while standing in the application folder you’ve chosen:

   heim deploy

   
   

   Windows

   The following example is created on Windows, using a powershell terminal window.

   The process will be the same in Linux or macOS, but using the appropriate default or custom terminal in the operating system you’ve chosen.

   
   

   Assuming that your application directory is C:\heim-applications and the application folder is a-new-api, you should be looking at something like this in your terminal window.

   PS C:\heim-applications\a-new-api> heim deploy

   
   

   Heim runtime

   In order to use, or test your deployed application, you need to have your Heim runtime running.

   See the previous section about how to start the Heim runtime, for information.

   
   
   create application from template

   <OPTIONAL> Install your own templates

   Place valid template folders in the templates directory in your Heim root folder.

   Windows

   On Windows, the path would be %USERPROFILE%/.heim/templates

   
   

   Create application from a template

   use heim new

   Use the command:

   heim new

   
   

   Examples

   The following examples are created on Windows, using a powershell terminal window.

   The process will be the same in Linux or macOS, but requires using the appropriate default or custom terminal in the operating system you’ve chosen.

   
   

   select template

   Running heim new will trigger a template selection menu:

       PS C:\heim-applications> heim new
       ? Select template:  ›
       csharp-http
       rust-graphql
       rust-http

   Use the up and down arrow keys on your keyboard to navigate to the template you want to use. Press enter to confirm your choice.

   
   

   set options

   After confirming your choice of template, you will next need to set any template-specific options.

   For instance, if the selected template will generate an http API, you might see something like this:

   PS C:\heim-applications> heim new
   ✔ Select template:  · csharp-http
   ? Http trigger method POST/GET, Default (GET) ›

   You may type out your selection, in this case a valid HTTP method, or ALL to allow for any HTTP method. Press enter when done. If you press enter without typing anything, the selection will be the given default value. In the example above, the default value would be GET.

   
   

   set trigger path

   As you’ve set your options, you’ll next need to decide on the trigger path for your application:

   PS C:\heim-applications> heim new
   ✔ Select template:  · csharp-http
   ✔ Http trigger method POST/GET, Default · GET
   ? Http trigger path /??? , Default (/hello) ›

   Type in a path value and press enter to confirm your trigger path. Press enter without typing in a value to select the indicated default path.

   
   

   set package name

   Next, you’ll need to select a package name:

   PS C:\heim-applications> heim new
   ✔ Select template:  · csharp-http
   ✔ Http trigger method POST/GET, Default · GET
   ✔ Http trigger path /??? , Default · my-api
   ? Package name, (Required) ›

   Note that you have to pick a name for your application package. There is no default value to use.

   
   

   Heim runtime

   If you’ve already started the Heim runtime in the previous step, your application should now be ready to deploy.

   If not, now is a good time to start the Heim runtime.

   
   

   Deploy the application

   
   

   To deploy your application, use the following command in a terminal or console window, while standing in the application folder you’ve created by going through the application creation process:

   heim deploy

   If you’ve gone through the process, as hitherto described, deploying the application would look as follows:

   PS C:\heim-applications\a-new-api> heim deploy

   
   
   
   

5. Working with applications

   To successfully test and use an application in Heim, you need to have started the Heim runtime. You also need to deploy the application, which you can read about in the previous section about using applications.

   
   

   Test application

   Assuming that everything is up and running, your application should now be accessible through the trigger path assigned to it when it was created.

   should you happen to be unaware of the path for a particular application, you can find it (and edit it) in the application.toml in the root folder for that application.

   
   

   The full path for an application will be something like:

   ${server-address}/${trigger-path}

   
   

   For instance, if you are running a local installation of Heim, and you start it on port 3000, a valid address for an application with the http trigger path my-api will be something like:

   127.0.0.1:3000/my-api

   From there, you’ll be able to access, and test any endpoints you’ve created for the application.

   
   

   Edit application code

   Once you’ve worked with Heim for a while, you will no doubt have your own applications, perhaps stretching over multiple files, structured according to your own standards and requirements.

   However, during your first steps with Heim, you’ll likely download an example application, or create one from a template. You can read more about how to use an existing application, and how to create your own application from a template in the section about using applications, above.

   Read on for information about how to start working with one of our example applications, or an application created from a template.

   
   
   C-Sharp

   A basic Heim C# application, created from a template or copied from one of our examples, should be structured something like this:

   • Directory{application-name}

     • Directorywit

       • Directorydeps

         • …
       • world.wit
     • .gitignore
     • component.toml
     • application.toml
     • {application-name}.csproj
     • Program.cs

   
   

   • Edit the Program.cs file, if you want to change the source code of your application.
   • Edit the component.toml file, if you want to change your application component metadata, define environment variables, or alter your build configurations.
   • Edit the application.toml file, if you want to change your application definitions, set values to environment variables, or alter application triggers.
   Rust

   A basic Heim Rust application, created from a template or copied from one of our examples, should be structured something like this:

   • Directory{application-name}

     • Directorysrc

       • lib.rs
     • Directorytarget

       • …
     • .gitignore
     • Cargo.toml
     • component.toml
     • application.toml

   
   

   • Edit the contents of the src folder, if you want to change the source code of your application.
   • Edit the component.toml file, if you want to change your application component metadata, define environment variables, or alter your build configurations.
   • Edit the application.toml file, if you want to change your application definitions, set values to environment variables, or alter application triggers.
   Python

   A basic Heim Python application, created from a template or copied from one of our examples, should be structured something like this:

   • Directory{application-name}

     • Directorywit

       • …
     • Directory__pycache__

       • …
     • .gitignore
     • app.py
     • component.toml
     • application.toml

   
   

   • Edit the contents of app.py, if you want to change the source code of your application.
   • Edit the component.toml file, if you want to change your application component metadata, define environment variables, or alter your build configurations.
   • Edit the application.toml file, if you want to change your application definitions, set values to environment variables, or alter application triggers.
   TypeScript

   A basic Heim TypeScript application, created from a template or copied from one of our examples, should be structured something like this:

   • Directory{application-name}

     • Directorynode_modules

       • …
     • Directorywit

       • …
     • Directorytypes

       • …
     • Directorysrc

       • http.ts
     • .gitignore
     • package.json
     • tsconfig.json
     • vite.config.ts
     • component.toml
     • application.toml

   
   

   • Edit the contents of the src folder, if you want to change the source code of your application.
   • Edit the component.toml file, if you want to change your application component metadata, define environment variables, or alter your build configurations.
   • Edit the application.toml file, if you want to change your application definitions, set values to environment variables, or alter application triggers.
   C

   A basic Heim C application, created from a template or copied from one of our examples, should be structured something like this:

   • Directory{application-name}

     • Directorybindings

       • proxy.h
     • Directorywit

       • Directorydeps

         • …
       • deps.lock
       • deps.toml
       • handler.wit
       • proxy.wit
       • types.wit
     • .heimignore
     • component.toml
     • application.toml
     • app.c

   
   

   • Edit the app.c file, if you want to change the source code of your application.
   • Edit the component.toml file, if you want to change your application component metadata, define environment variables, or alter your build configurations.
   • Edit the application.toml file, if you want to change your application definitions, set values to environment variables, or alter application triggers.
   Go

   A basic Heim Go application, created from a template or copied from one of our examples, should be structured something like this:

   • Directory{application-name}

     • Directorywasi

       • …
     • Directorywit

       • proxy.wit
     • .gitignore
     • application.toml
     • component.toml
     • go.mod
     • go.sum
     • main.go

   
   

   • Edit the main.go file if you want to change the source code of your application.
   • Edit the component.toml file, if you want to change your application component metadata, define environment variables, or alter your build configurations.
   • Edit the application.toml file, if you want to change your application definitions, set values to environment variables, or alter application triggers.
   
   

The Heim command line interface (CLI)

You can control everything Heim does through our CLI. When reading through the previous sections of this document, you’ve found out how to start the Heim runtime, all as how to deploy applications, and how to create applications from a template, all of which can be done through our CLI.

But the CLI can do so much more! Have a look at our CLI reference documentation, to find out what else the CLI is capable of.

---

Summary

To get going with heim, you need to go through a few simple steps:

1. Install required software – you’ll likely need software for building and working with a programming language.

2. Install Heim – you’ll need to install the Heim tools. There are different options for installing Heim, depending on your operating system.

3. Start Heim runtime – the Heim runtime can be started with the CLI command heim start, or heim-runtime.

4. Start using an application – you’ll need to create an application from a template, or deploy an existing application.

5. Work with an application – edit your application source code, or test your application through its trigger path.

CLI reference

Check out our CLI reference documentation for more information about using Heim, and what else you can do, once you’ve gotten started with Heim.