Execution Targets & Resources

Overlord needs to know where agent work runs: your laptop, a remote workstation, a devbox, or any future hosted runner. That machine or environment is an execution target. The checkout path for a project on that target is a project resource directory.

Targets and paths live in dedicated tables so the runner can resolve a consistent working directory for ovld launch and ovld runner.

Core concepts

An execution target is not owned by a single user or organization. Instead:

• execution_targets holds canonical identity (fingerprint or placeholder key, host, port, transport).
• organization_execution_targets adds org-scoped labels.
• user_execution_targets records which users may use the target.
• project_execution_targets links targets to projects.
• project_resource_directories is the path authority: every resource points at exactly one execution_target_id.

Local vs remote targets

Local targets register when ovld runs on the machine. ovld protocol get-device (or the runner on startup) upserts execution_targets with a real device_fingerprint, transport=local, and the hostname from the OS.

Remote targets can be configured before the machine that will run the work has ever registered:

1. The web app or protocol creates the target and its project resource directories.
2. When ovld runs on the target machine, get-device registers the real fingerprint.
3. Overlord reconciles the pending row to that fingerprint without changing execution_target_id.

The same physical server can appear in multiple organizations with different labels. Identity is the fingerprint, not the label — two VMs on one host are two targets if agents execute inside each VM.

How targets connect to the runner

When you click Run or auto-advance enqueues an objective, execution_requests stores:

• target_execution_target_id — which machine should run the agent
• target_resource_id — optional explicit resource; otherwise the primary directory for that project/target pair

ovld runner claims rows whose target matches its fingerprint (from the shared ~/.ovld/device.json). Desktop reads that same file and migrates its legacy app-support fingerprint into it on first access. The runner is org-agnostic: a single runner process serves queued work across every organization the user belongs to that also shares the claiming target. claim-execution computes the intersection of (user's member orgs) and (orgs that include the target) to scope the queue, so a developer's laptop can pick up requests from all their organizations without separate runner instances.

claim-execution resolves the working directory from the target resource, or falls back to the primary project_resource_directories row for (project_id, execution_target_id). If no primary exists, the request is skipped and a backstop event is recorded rather than launching in an unknown directory.

See Agent Execution & Runner for the full queue lifecycle, leasing, and launch sequence. See Terminal & IDE for the per-target terminal profile and launch settings.

Data model

The diagram below shows how canonical targets relate to org/user/project layers and resource directories.

Primary resource semantics

Primary means “use this path when the execution request does not specify a resource.” Constraints:

• At most one is_primary=true row per (project_id, execution_target_id) — enforced by a partial unique index.
• Primary is project topology, not per-user: two teammates working on the same project on the same target share the same primary checkout path.
• Registration metadata is per target; only the directory path is shared at the project/target level.
• The first directory added for a (project, target) auto-promotes to primary. If you remove the primary, the next oldest directory for that pair is promoted automatically.

When you add a resource from the desktop app or protocol, setting is_primary clears any other primary on that same project and target.

Target ownership

organization_execution_targets has a nullable owner_user_id that controls who may manage directories on the target within that organization.

In both cases, all org members may read the primary (so they can see the project's working directory). The write authority is enforced in both application code (assertCanManagePrimary) and RLS (can_manage_project_resource_directory() SQL helper).

Self-registered targets (local ovld runner startup) default to personal (owner = the registering user). Targets added from the web app can be marked organization-owned at creation time. Ownership can be transferred later by an org admin or the current owner.

Registration flow

Use pending targets when you know the machine and checkout path before the remote machine has registered with Overlord.

Protocol and CLI surface

Agents and the desktop app maintain targets and paths through protocol routes (also available via ovld protocol):

# Register or refresh the current machine (writes execution_targets + associations)
ovld protocol get-device --device-fingerprint "$OVERLORD_DEVICE_FINGERPRINT"

# List checkout paths for a project on this target
ovld protocol list-project-resources \
  --project-id <project-uuid> \
  --device-fingerprint "$OVERLORD_DEVICE_FINGERPRINT"

# Add or update a directory on the current target
ovld protocol add-project-resource \
  --project-id <project-uuid> \
  --directory-path /path/to/checkout \
  --device-fingerprint "$OVERLORD_DEVICE_FINGERPRINT"

ovld protocol update-project-resource --resource-id <uuid> --is-primary true

ovld runner start uses the same fingerprint and registered resources when claiming queued requests. Use --device-fingerprint or OVERLORD_DEVICE_FINGERPRINT when matching a specific target.

For ticket routing (agent vs human work), --for-human on ovld protocol create is a separate concept — see the CLI reference.

Mental model

Project
  └── execution target (laptop | remote workstation | …)
        └── resource directories (/path/a, /path/b, …)
              └── one primary → default cwd for launch/runner

Execution target answers which machine. Resource directory answers which folder on that machine. Execution request ties an objective to both so the runner can spawn ovld launch in the right place.

Related pages

• Agent Execution & Runner
• Tickets
• Objectives
• CLI Reference
• Workflow overview