Using voar

1. Open the app's page on GitHub and pick your organization. Personal accounts aren't supported yet.

   Install voar on GitHub

2. Choose which repositories can use voar: all of them or just some. You can change this later in the app's settings on GitHub.

3. In your workflow, set the job's runs-on to a voar label:

   name: CIon: push jobs:  test:    runs-on: voar-2vcpu-ubuntu-2404    steps:      - uses: actions/checkout@v7      - run: npm ci      - run: npm test

   Copy

4. Push a commit. Then sign in to the dashboard with your GitHub account: the jobs page shows each job, its machine, how long it took and what it cost.

   Open the dashboard

The label tells voar which machine the job wants. Each size takes its full form or a short one.

• Use one voar label per job.
• You can list self-hosted, linux and x64 next to it. Any other label in the same runs-on leaves the job waiting.
• Case doesn't matter: GitHub compares labels case-insensitively.

Ubuntu 24.04 on x64, with sudo. Already installed:

• Docker, with Compose and Buildx
• sudo and git
• Node 22 and 24
• Bun
• Python 3
• GitHub CLI (gh)
• AWS CLI

It isn't the full image GitHub's runners use. Install anything else in the job itself:

- run: sudo apt-get update && sudo apt-get install -y postgresql-client

Every job starts on a new machine. Nothing from the previous job is left on it.

A cache saves files so the next job can reuse them instead of downloading or building them again. voar uses GitHub's own cache. Keep any actions/cache steps your workflow already has.

For npm, put these steps after actions/checkout. Your repository needs a package-lock.json:

- uses: actions/setup-node@v7  with:    node-version: '24'    cache: npm- run: npm ci

setup-node reuses downloaded packages, not the node_modules folder. Keep the npm ci step.

Docker layers

Use Buildx's gha cache to reuse layers across builds. Add these steps after checkout in a repository with a Dockerfile:

- uses: docker/setup-buildx-action@v4- uses: docker/build-push-action@v7  with:    push: false    cache-from: type=gha,version=2    cache-to: type=gha,version=2,mode=max

GitHub stores the cache files. They are not hosted by voar in São Paulo. Storage limits, removal rules and charges follow GitHub's rules for your repository.

The first job saves the cache. If you see Cache not found, let the job finish, then run it again with the same key. Check the path and the dependency file used in the key too. Keep passwords and tokens out of the cache.

• A job can run for up to 6 hours. At that mark the machine shuts down.
• Organizations only. Personal accounts aren't supported yet.
• Linux x64 only (Ubuntu 24.04), in São Paulo (AWS sa-east-1).
• Up to 2 jobs at once before your first purchase, and 10 after. For more, email [email protected].

Public repositories

By default only private repositories can use voar: GitHub's default runner group doesn't serve public ones. To allow them, an organization admin opens Settings > Actions > Runner groups, goes into the Default group and checks Allow public repositories.

In a public repository, a pull request from outside your team can make a job run on voar, and its cost comes out of your balance. Before you allow them, check in GitHub's Actions settings who needs approval to run workflows from forks.

The voar app asks only for what it needs to create runners and hear about jobs. It doesn't ask for access to your repositories' contents.

• Self-hosted runners (read and write), on the organization: to create each job's runner and remove it at the end.
• Members (read): to know who the organization's admins are.
• Actions (read): to receive job events.
• Metadata (read): GitHub asks for it along with the others.
• The email address of whoever signs in to the dashboard: for account notices, such as a low balance.

• Each job is billed on its own, rounded up to the whole minute, the way GitHub does it. A job that takes 3 min 10 s counts as 4 minutes.
• Bigger machines count more minutes per minute: each minute on the 4 vCPU machine counts as 2, and on the 16 vCPU one as 8.
• Every organization gets 3,000 free minutes a month, counted on the 2 vCPU machine. They come back at midnight on the 1st, São Paulo time.
• After that, each job is paid from your balance. Add credit in the dashboard, in packs from $10. There's no plan or subscription.
• Your organization's first payment fixes its currency: reais, dollars or euros.
• With no balance and no free minutes left, jobs wait in GitHub's queue until you add credit. GitHub cancels a job that waits more than 24 hours.
• Organization owners and admins add credit and change settings. Members see the jobs and the balance.

See prices

Organization owners and admins create API keys (voar_...) in the dashboard's Settings. Each organization can hold up to 10 active keys, all read-only.

curl -H "Authorization: Bearer voar_..." https://api.voar.dev/v1/account

Endpoints and tools

• GET /v1/account (MCP tool get_account, scope account:read): organization summary, credit balance, the month's free units and how many are used, concurrency limit, active machines and queued jobs.
• GET /v1/jobs (MCP tool list_jobs, scope jobs:read): recent jobs for the organization (limit from 1 to 100 and before in ISO 8601), with machine size, duration, cost and any reason a job did not start.
• GET /v1/usage (MCP tool get_usage, scope usage:read): finished jobs, billed units and paid cost for the month (month as YYYY-MM in America/Sao_Paulo), day by day. costMicros is in the currency that get_account returns.
• GET /v1/openapi.json (or ?lang=pt-BR): public OpenAPI 3.1 specification.

A unit is one minute on the 2 vCPU machine. The 4, 8 and 16 vCPU machines count 2, 4 and 8 units a minute. Money fields end in Micros: 1,000,000 micros is 1.00 of the currency.

Connect over MCP

Point Claude, ChatGPT or Codex to https://api.voar.dev/mcp. The app opens voar's authorization screen so you can pick the organization, and receives its own voar_ key.

From a terminal agent without a local browser, start a device code sign-in (RFC 8628) and approve it at https://app.voar.dev/device:

curl -X POST https://api.voar.dev/oauth/device_authorization \  -d "client_id=voar-agent"

When you connect an AI app to voar with OAuth or a terminal code, it receives a read-only API key bound to the organization you picked.

• The app only reads the organization summary (account:read), the jobs list (jobs:read) and monthly usage (usage:read). It cannot change limits, buy credit packs or create other keys.
• voar's GitHub App has no permission to read your repositories' contents, and what the API returns holds no source code, job logs or workflow secrets.
• Your jobs run on voar's machines. While a job runs, its machine holds the code and the secrets your workflow uses, as any runner does. When the job ends, the machine and its disk are deleted.
• Card details go to Stripe, not to voar.
• Every connected app appears in the API keys list in the organization's Settings, where any owner or admin can rotate or revoke the key right away.
• If the person who authorized the app leaves the GitHub organization or is no longer an owner or admin, the key stops working right away.

Change runs-on back to ubuntu-latest, or to whichever GitHub runner you used before. Nothing else changes.

To switch every workflow at once, read the runner from an organization variable:

runs-on: ${{ vars.CI_RUNNER || 'ubuntu-24.04' }}

Create the CI_RUNNER variable in your organization (Settings > Secrets and variables > Actions > Variables) with the value voar-2vcpu-ubuntu-2404. Without it, jobs run on GitHub's ubuntu-24.04.

My job is stuck in Queued

Open the jobs page in the dashboard. It says why each waiting job hasn't got a machine yet. The possible reasons:

• The label is misspelled, like voar-3vcpu. Check the labels table.
• The runs-on has another label besides the voar one. Only self-hosted, linux and x64 can go with it.
• Your balance and the month's free minutes are gone. Add credit and the job starts.
• The organization is running as many jobs at once as it can. The job waits its turn.
• voar couldn't start the machine. Run the job again. If it happens again, email [email protected].
• The app was uninstalled or suspended on GitHub. Install voar on the organization again.

If the repository is public, also check that the runner group allows public repositories.

My job doesn't show up in the dashboard

The app isn't installed on that repository. Add the repository in the app's settings on GitHub and run the job again.