Skip to content
Vectis
Esc
↑↓navigate↵open⌘Jpreview
Download
On this page

Quickstart

From a freshly installed app to your first GitHub Actions job in a Vectis VM.

This walkthrough uses an Ubuntu guest, the fastest to prepare. Each step shows the app first and the CLI equivalent after it. You need the app installed with its service running, and a GitHub repository where you can change workflows.

1. Prepare an Ubuntu environment

In the app, open Environments, choose Add environment, select Ubuntu 24.04 and pick two folders: one for the base image and one for the disposable VMs. Keep the suggested CPU, memory and disk, or adjust them. The ID you choose, for example ubuntu, becomes part of the runner label.

vectis environment prepare-linux ubuntu \
  --image-directory ~/VMs/images --storage-path ~/VMs/clones --wait --timeout 3600000

Vectis downloads the official Ubuntu cloud image, checks its SHA-256 and installs Git, Docker and the GitHub runner’s dependencies. This takes a few minutes. Follow it in Overview. Details: Prepare Ubuntu.

2. Connect this Mac to your account

In Connections, choose Connect in browser under This Mac. Your browser opens vectis.kerd.dev/connect. Sign in, check that the verification code matches the one in the app, and approve. Back in the app, choose Finish connecting.

vectis cloud pair --json     # open the link it prints, compare the code, approve
vectis cloud finish --json

Approve only requests you started yourself, and never share the link.

On the connect page, open Overview and follow the steps:

  1. Link GitHub proves which GitHub account is yours.
  2. Install App installs the Vectis GitHub App on the account or organization that owns your repository. Choose the repositories it may access.
  3. Link again to refresh so Vectis sees the new installation.

The CLI prints the same page with vectis github connect.

4. Connect the repository

In the app, open Repositories and choose Connect a repository. Pick your GitHub account, the repository and the ubuntu environment. You can also do this on the connect page under Repositories, where you also choose which Mac runs the jobs.

vectis github accounts --json
vectis repository connect my-repo --account <account-id> --environment ubuntu --wait

For a repository owned by an organization, add --owner <organization>. Public repositories have extra requirements; see Repositories and labels.

5. Point a workflow at Vectis

Set runs-on to the label shown next to the connection, vectis-<environment-id>:

jobs:
  test:
    runs-on: vectis-ubuntu
    steps:
      - uses: actions/checkout@v5
      - run: echo "Hello from a disposable VM"

6. Turn on automatic runners

In Repositories, switch Automatic on for the connection.

vectis repository enable-auto <binding-id> --wait

Push the workflow. Your Mac notices the queued job within a minute, boots a fresh VM, registers a single-use runner, runs the job and deletes the VM. Watch the operation in Overview and the job under the repository in Repositories, or on GitHub.

If the job keeps waiting, work through Troubleshooting.

Next