Gramine documentation

Gramine is a lightweight guest OS that is designed to run a single Linux application with minimal host requirements. Gramine can run applications in an isolated environment with benefits comparable to running a complete OS in a virtual machine, including guest customization, ease of porting to different host OSes, and process migration.

Gramine supports running Linux applications using the Intel SGX (Software Guard Extensions) technology. Gramine is able to run unmodified applications inside SGX enclaves, without the toll of manually porting the application to the SGX environment. Applications running inside the Gramine SGX enclave become protected against a malicious host. For more information, refer to the Introduction to SGX article.

This page provides an overview of this documentation. Each section is outlined below with a brief explanation and links to specific sub-sections. This page mimics the table of contents in the left-side menu.

Gramine deployment options

There are two deployment options for Gramine: protect your container and protect your application. Each option has a dedicated section in the menu, and an introduction is provided below.

Protect your container

In this section, we describe how you can protect your Docker container using Gramine Shielded Containers (GSC) and how you can use ready-made SGX images for popular open source projects.

  • Gramine Shielded Containers

    Docker images are used to run applications in the cloud. The Gramine Shielded Containers (GSC) tool transforms a base Docker image into a graminized Docker image that includes the Gramine Library OS and the Gramine-specific app configuration. It enables you to run an application in a Docker container and keep it protected against a malicious host. See the Gramine Shielded Containers article for more information.

  • Ready-made SGX images

    Users can create ready-made SGX Docker images with the help of the “Confidential Compute for X” project. This project provides an interactive script to transform base Docker images to Gramine-protected Docker images. See the Ready-made SGX images article for more information.

Protect your application

Use this option to protect an existing application against a malicious host with Gramine. Little to no additional modification of your application is usually needed.

The following steps can be performed to protect your application with Gramine:

  • Install Gramine - Install official Gramine packages from the repository of your Linux distribution.
  • Run a sample application - Run a sample application to ensure your environment is configured correctly.

You can also check Gramine tutorials.

Configure Gramine

To run an application with Gramine, the host platform must be correctly set up first. Further, to achieve security and performance guarantees, Gramine must be configured appropriately for each application.

Develop Gramine

This section describes how to develop Gramine. It contains instructions on how to build and install Gramine from source, install dependencies, set up debugging and other processes necessary for Gramine development.

We also provide manual pages for Gramine tools.

Contribute to Gramine

We encourage anyone who is interested to contribute to Gramine. The below articles contain helpful material for prospective contributors:

  • Contributing to Gramine - The Contributing to Gramine page outlines the procedures for performing pull requests, reviews, and regression tests.
  • Onboarding - This page describes the knowledge needed to efficiently contribute high-quality PRs to the Gramine project. This page also describes typical flows that Gramine developers should follow to make the process of PR review consistent for everyone involved.
  • Development setup - Learn the Emacs and Vim configurations used for Gramine.
  • Coding style guidelines - This document describes coding conventions and formatting styles we use in Gramine. All newly committed code must conform to them to pass a review.
  • How to write documentation - This section describes how the Gramine documentation is constructed and provides directions on how to contribute to it.
  • Developer Certificate of Origin - Affirm that the source code you will submit was originated by you and/or that you have permission to submit it to the Gramine project.

Resources

The Gramine project provides resources to help you understand and develop it. The resources page contains a description of features of Gramine, a list of maintainers, a list of users of Gramine, introduction to the Intel SGX technology and a glossary to help you with any questions you may have.

  • Gramine features – This page has a comprehensive description of implemented and unimplemented features of Gramine, including the lists of available system calls and pseudo-files.
  • Management Team (Maintainers) - This page lists maintainers of Gramine.
  • Users of Gramine - See what companies use Gramine for their confidential computing needs.
  • Introduction to SGX - Learn about the Intel SGX technology and software stack.
  • Glossary - Become familiar with the terms used in Gramine.

Getting help

For any questions, please use GitHub Discussions or join us on our Gitter chat.

For bug reports and feature requests, post an issue on our GitHub repository.

If you prefer emails, please send them to users@gramineproject.io (public archive).

Indices and tables