Execution targets

Overlord needs to know where agent work runs: your laptop, a remote workstation, a devbox, or a hosted runner. That machine or environment is an execution target. The checkout path for a project on that target is a project resource directory. Together they let the runner resolve a consistent working directory for every launch.

A project can expose more than one target, and each launch uses an eligible target for the acting member. If a mission is queued but does not start, check that its project has an available target and a linked directory on it.

Core concepts

Concept	What it is
Execution target	A machine or environment agents execute on, identified by a device fingerprint (not a label).
Project resource directory	A checkout path for a project on a specific target.
Primary resource	The default directory used when a launch does not name an explicit resource. There is one primary per (project, target) pair.

An execution target is not owned by a single user or organization. The same physical machine can appear in multiple organizations with different labels; identity is the fingerprint, so two VMs on one host are two targets.

Environments vs disposable containers

A container never registers a target of its own. A container that shares its host’s filesystem — AgentPod mounting the host checkout — adopts the host’s target instead: it runs a runner against the target the host already has, so the resources it resolves are literally the host’s resources.

Point the container at the host target and give it its own runner identity:

OVERLORD_EXECUTION_TARGET_ID=<host target id>
OVERLORD_RUNNER_INSTANCE_ID=<stable per-container id>
OVERLORD_RUNNER_RELATION=adopted

The target id is resolved and authorized, never created; if it does not exist or you cannot access it, the runner fails with no_execution_target_registered rather than inventing a target. One target can be served by several runners at once — the host’s own runner plus every container adopting it — and any healthy one may claim its work.

A genuinely independent VM or sandbox is the other case: run ovld add-et inside it so it becomes its own target.

Local vs remote targets

Local targets are registered deliberately, never as a side effect. Logging in, installing a runner, or starting one does not make a machine an execution target — container images ship the CLI and a token, so capability cannot be the trigger. Exactly two acts register one: linking a checkout from the machine that holds it (ovld add-cwd, ovld create-project --directory, the desktop local bridge), and announcing the machine explicitly:

ovld add-et --name "CI runner 01"

ovld add-et provisions (or reuses) this machine’s local execution target and sets --name as its display label; re-running with a new name renames the same target. It is workspace-scoped — when you belong to one workspace it registers there, otherwise pass --workspace-id <id-or-name> (or the command lists your workspaces and asks you to choose).

Remote targets can be configured before the machine that will run the work has registered: the web app creates the target and its resource directories, and when Overlord next runs on that machine it reconciles the real fingerprint without changing the target’s identity.

When a target is reachable

A local target is online while one of its runners has reported in recently. A machine with no runner installed is not reachable, however much other CLI traffic it produces — that is what keeps queued work from sitting against a target that can never claim it. Start a runner there (ovld runner start, or ovld runner service install for a persistent one) to bring the target online.

Link a directory to a project

From the repository directory, link the current checkout on this target:

ovld add-cwd --project-id <project-id>

Use --directory <path> to link a different folder, --key <resource-key> to identify the same logical resource across targets, and --primary true|false to control whether it is the primary. To add a remote Git source instead of a local checkout:

ovld add-url --url <git-url> --project-id <project-id>

Primary resource semantics

Primary means “use this path when the execution request does not specify a resource.” A few rules keep it predictable:

• At most one primary per (project, target) pair.
• Primary is project topology, not per-user — teammates on the same project and target share the same primary checkout path.
• The first directory added for a (project, target) auto-promotes to primary. If you remove the primary, the next oldest directory is promoted automatically.

Target ownership

Who may manage directories on a target depends on how the target is owned:

• Personal (owned by a user) — only the owner may add, remove, or change the primary for any project on that target within the organization.
• Organization-owned — any user with an ADMIN or MANAGER role on the project may manage directories; VIEWER is read-only.

In both cases every member can read the primary so they can see the project’s working directory. Self-registered local targets default to personal ownership; targets added from the web app can be organization-owned.

How targets reach the runner

When you click Run or auto-advance enqueues an objective, the execution request stores which target should run the agent and, optionally, which resource. The runner claims requests whose target matches its fingerprint and resolves the working directory in priority order:

1. an explicit working directory on the request
2. the named resource, verified to live on the claiming target
3. the primary directory for the (project, target) pair

If no primary is found the request is skipped and an event is recorded, rather than launching in an unknown directory.

See Retries and blocked work for the full queue lifecycle, and Terminal and IDE preferences for the per-target terminal profile and launch settings.