Create a Viam application

Create and deploy a custom web interface for your machines without managing hosting and authentication. Once deployed, your application is accessible from a dedicated URL (appname_publicnamespace.viamapplications.com), and hosting and authentication is handled for you.

Users log into your application and select a machine they have access to. The application then renders your custom interface for interacting with the user’s machine.

Requirements

brew tap viamrobotics/brews
brew install viam

sudo curl -o /usr/local/bin/viam https://storage.googleapis.com/packages.viam.com/apps/viam-cli/viam-cli-stable-linux-arm64
sudo chmod a+rx /usr/local/bin/viam

sudo curl -o /usr/local/bin/viam https://storage.googleapis.com/packages.viam.com/apps/viam-cli/viam-cli-stable-linux-amd64
sudo chmod a+rx /usr/local/bin/viam

brew tap viamrobotics/brews
brew install viam

go install go.viam.com/rdk/cli/viam@latest

echo 'export PATH="$HOME/go/bin:$PATH"' >> ~/.bashrc

viam login

viam login api-key --key-id <api-key-id> --key <organization-api-key-secret>

Build a custom web interface

You can build a custom web interface to access your machines using your preferred framework like React, Vue, Angular, or others.

Access machines from your application

When logging into a Viam application and selecting a machine to use it with, the machine’s API key is stored as a cookie. You can access the data from your browser’s cookies as follows:

import Cookies from "js-cookie";

let apiKeyId = "";
let apiKeySecret = "";
let host = "";
let machineId = "";

// Extract the machine identifier from the URL
const machineCookieKey = window.location.pathname.split("/")[2];
({
  apiKey: { id: apiKeyId, key: apiKeySecret },
  machineId: machineId,
  hostname: host,
} = JSON.parse(Cookies.get(machineCookieKey)!));

Local development

For developing your application on localhost:

1. Run your web server.

2. Run the following command specifying the address where your app is running on localhost and a machine to test on. The command will proxy your local app and open a browser window and navigate to http://localhost:8012/machine/<machineHostname> for the machine provided with –machine-id.

   • Template
   • Example

   viam login
   viam module local-app-testing --app-url http://localhost:<PORT> --machine-id <MACHINE-ID>
   

   viam login
   viam module local-app-testing --app-url http://localhost:3000 --machine-id a1b2c3d4-e5f6-7890-abcd-ef1234567890
   

Configure routing

When using your deployed application, static files will be accessible at https://your-app-name_your-public-namespace.viamapplications.com/machine/<machineHostname>/. If your HTML file loads other files, use relative paths to ensure your files are accessible.

Deploy your web interface as a Viam application

To deploy your application with Viam you must package it as a module and upload it using the Viam CLI.

{
  "module_id": "your-namespace:your-module",
  "visibility": "public",
  "url": "https://github.com/your-org/your-repo",
  "description": "Your module description",
  "applications": [
    {
      "name": "your-app-name",
      "type": "single_machine",
      "entrypoint": "dist/index.html"
    }
  ]
}

{
  "module_id": "acme:dashboard",
  "visibility": "public",
  "url": "https://github.com/acme/dashboard",
  "description": "An example dashboard for a fictitious company called Acme.",
  "applications": [
    {
      "name": "dashboard",
      "type": "single_machine",
      "entrypoint": "dist/index.html"
    }
  ]
}

viam module create --name="app-name" --public-namespace="namespace"

viam module create --name="air-quality" --public-namespace="naomi"

tar -czvf module.tar.gz <static-website-files> meta.json
viam module upload --upload=module.tar.gz --platform=any --version=0.0.1

Access your application

After uploading your module with the application configuration, your application will be available at:

https://your-app-name_your-public-namespace.viamapplications.com

Users will be prompted to authenticate with their Viam credentials before accessing your application:

1. User navigates to your-app-name_your-public-namespace.viamapplications.com.
2. User authenticates with Viam credentials.
3. User selects an organization, location, and machine.
4. User is redirected to your-app-name_your-public-namespace.viamapplications.com/machine/<machineHostname>.
5. Your application is rendered with access to the selected machine. The credentials for that one machine are provided in the cookies.

Example

For a TypeScript example see Monitor Air Quality with a Fleet of Sensors.

For a React application that shows camera feeds for a machine, see Viam Camera Viewer.

Limitations

• Applications currently only support single-machine applications.
• All modules with applications must have public visibility.
• The page will always render the latest version.
• Browsers with cookies disabled are not supported.
• Viam applications serve static files. If you are building an application with server-side rendering or need other back-end capabilities, Viam applications is not the right choice.

Security considerations

• Customer applications are stored publicly on the internet, so avoid uploading sensitive information in your application code or assets.
• API keys and secrets are stored in the browser’s cookies.
• Users authenticate with FusionAuth.

FAQ

Can I use a custom domain?

Viam does not currently support using custom domains (for example: app.mycustomdomain.com/machine/<machineHostname>) to serve your Viam application. You can, however, redirect from your domain to your Viam application (app.mycustomdomain.com -> your-app-name_your-public-namespace.viamapplications.com). You can configure a redirect (HTTP 301) on your web server or hosting provider from app.mycustomdomain.com/* to your-app-name_your-public-namespace.viamapplications.com/*.