Cloud Workers

Optional, beta. You do not need Cloud Workers to use AgentD. AgentD runs entirely on your machine: chat, workers, checks and review need no cloud key and no Cloud Workers. Cloud Workers are an optional beta for AgentD accounts with beta access.

A Cloud Worker runs one AgentD handoff on LibraOS infrastructure instead of on your machine. Use one when you do not want to keep a local worker running, for example while your machine is busy or off. Use a local worker when the job must reach services, files, or hardware on your machine.

Before you start

• AgentD v0.1.6 or newer, set up with agentd init (What AgentD is).
• A GitHub repository with the LibraOS GitHub App installed. The repository's owner installs the App once for that repository. A job on a repository without it fails with failed_verification and says so.
• Console credits. A job holds its dollar budget from your balance while it runs (Costs and budget holds).

Get access

1. Sign in to the LibraOS Console with the account that has AgentD beta access.

2. Open the AgentD page. Under Add Cloud Workers when you need them, choose Create or rotate cloud key. The key is shown once. It is not a model API key.

3. Save the key alone in a file that only you can read:

   mkdir -p ~/.config/agentd
   install -m 600 /dev/null ~/.config/agentd/cloud.key
   nano ~/.config/agentd/cloud.key

4. Add the Cloud Worker settings to ~/.local/share/agentd/config.toml:

   [cloud]
   url = "https://cloud-api.libraos.com"
   key_file = "~/.config/agentd/cloud.key"

5. Check that the key works:

   agentd cloud balance

The key file must have mode 0600. Rotate or revoke the key from the Console AgentD page. When you redeemed your invitation, the Console also showed a cloud key once; you can use that one, or create a new one at any time.

Offer a job

A cloud job needs a dollar budget cap and a GitHub repository:

agentd handoff offer --cloud --budget '$10' \
  --goal 'Fix the failing checkout test' \
  --project OWNER/REPO

You can include a time limit too:

agentd handoff offer --cloud --budget '60m,$10' \
  --goal 'Add tests for the new parser' \
  --project OWNER/REPO

The job queues if your account already has a running job. The beta allows one running job per account. A job with no time limit in its budget runs for at most one hour. A time limit can be up to 24 hours.

What runs where

Each job runs in its own isolated virtual machine. It receives repository access for that job only. The worker checks out the named repository, makes its changes, and pushes an agentd/<handoff-id> branch back to the repository.

The branch is not merged. Review its commits and checks, then merge it through your normal review process.

Your code runs on LibraOS machines during the job. The job workspace is destroyed after the job ends. Repository and model credentials are limited to the job and are revoked when it ends.

Costs and budget holds

Cloud Workers use the same Console credit balance as other LibraOS services. One credit equals US$1. A job's cost has two parts:

• Worker Cost is US$0.04 per active minute. A minute is active while the job's worker is running. Time in the queue is not charged.
• Inference is the model use the job makes, metered at list price like your model API calls.

When you offer a job, its full dollar budget is held from your available credits. A hold is not a charge. When the job ends, the actual bill is charged and the unused part of the hold is released.

The settlement rules are:

Outcome	Worker Cost	Inference
Completed or stopped at the budget	Charged	Charged
Your task or verification failed	Charged	Charged
Unknown failure	Charged	Charged
Model refusal, rate limit, or provider outage	Credited	Charged
Worker, network, check environment, or service failure	Credited	Credited

Check status and costs

Show a job and its latest result:

agentd handoff show HANDOFF_ID

Show your balance, holds, charges, and credits:

agentd cloud balance

The Console Credits & billing page shows the same balance and a receipt for each job under Cloud Worker jobs.

Troubleshooting

• 402 insufficient credit: Your available credits do not cover the budget cap. Add credits in the Console or offer the job with a lower cap.
• 401 unknown key: The file in key_file does not hold your current cloud account key: a model API key (lk_… from API keys) does not work here, and rotating the cloud key revokes the old one. Save the current cloud key in the file. A job offered with the wrong key waits in submitting and is sent again once the key works.
• 403 revoked: Your Cloud Worker access or cloud account key was revoked. Check the Console AgentD page. Create a new key if access was restored.
• budget_exceeded: The job reached its budget cap and stopped. Review the partial result. Raise the handoff budget if you want it to continue.
• failed_verification: The job ended without a verified result. agentd handoff show HANDOFF_ID gives the reason:
  • The worker's run failed or reached the job's time limit. Inspect the output before you use the branch.
  • no repository access: the worker could not read or push to the repository. Ask the repository's owner to install the LibraOS GitHub App on that repository, then offer the job again.