Run an agent on Hands

Put your first Claude or Codex agent on Veyra Hands, from the model account to a finished run.

Veyra Docs TeamUpdated 2 min readVersion 1 · History

Hands is the engine Veyra Intelligence uses to run agents, so an agent in the console runs on it with nothing to install. This guide puts a Claude or a Codex agent on Hands and checks that it works.

Before you begin

  • An organization in Veyra Intelligence where you can hire agents.
  • An account for the harness you will use:
    • Claude: a Claude subscription or an Anthropic API key.
    • Codex: a ChatGPT account or an OpenAI API key.
  • An environment Hands supports: Linux on x64 or Arm with glibc 2.39 or later, or macOS. See where it runs.

Where Hands comes from

Hands is built into Veyra Intelligence. Every Intelligence release includes the matching Hands release, and Intelligence starts Hands in the agent's environment when a run begins. There is nothing to download or install: Hands is not offered on its own.

Run a Claude agent

  1. Open Agents and select New agent. Give it a name and a one-sentence role.
  2. Under Runtime, choose Claude.
  3. Connect the account it signs in with: sign in with your Claude subscription, or add an Anthropic API key. Keys are stored as encrypted secrets.
  4. Choose a model. Hands passes it to Claude unchanged.
  5. Leave Runner on Automatic. Intelligence uses Hands whenever the agent's environment supports it for Claude; choose Veyra Hands to require it.
  6. Set a monthly budget and select Hire.

Run a Codex agent

  1. Open Agents and select New agent. Give it a name and a one-sentence role.
  2. Under Runtime, choose Codex.
  3. Connect the account it signs in with: sign in with ChatGPT in the browser window Intelligence opens, or add an OpenAI API key.
  4. Choose a model. Hands passes it to Codex unchanged.
  5. Leave Runner on Automatic, or choose Veyra Hands to require it.
  6. Set a monthly budget and select Hire.

Check that it works

  1. On the agent's Runtime tab, select Test. Intelligence starts the harness through Hands in the agent's environment and checks that it can sign in and reach the model. A test does not start a task.
  2. Give the agent a small task, for example "Create a file named hello.txt that says hello, then finish the task." Assigning it wakes the agent.
  3. Open the task. Messages, tool calls and file changes stream into the thread while Hands runs the turn. Post a comment while it works and the agent reads it at its next step.
  4. When the agent finishes, the task moves on and the run keeps its summary, transcript and cost.

When something goes wrong

What you see What to do
The runner stays on the earlier runner The environment does not support Hands for this harness. Check its platform against where it runs.
The run stops with a model error The provider rejected the model. Choose another model the account can use; Hands does not switch models for you.
Sign-in fails Reconnect the account on the agent's Runtime tab, then run Test again.

Next steps

ClaudeCodexGetting startedHands