stablyai / stablyai/orca

[Feature]: Per-host agent launch commands

Open
#20,552 0 comments 1 reaction 0 assignees View on GitHub
Dominant language
TypeScript
Stars
72.1k
Forks
4.7k
Avg merge
14h 54m
Merged PRs (30d)
520

Description

### Problem or use case

Agent launch settings are client-global. Settings → Agents stores one command, one args string, and one env map per agent (`agentCmdOverrides`, `agentDefaultArgs`, `agentDefaultEnv`). Every execution host then receives that same string: local, SSH, and remote runtime.

That does not match how agents actually run. Each host is a different machine, so the launch line should be able to differ even when the agent brand is the same.

Two common cases:

1. **Install layout.** A command that is a bare binary name on this machine may need an absolute path or a wrapper on an SSH host. There is no way to keep the local command as-is and give another host its own executable.
2. **Launch configuration.** Hosts also need different argv and environment: model flags, provider/base-URL settings, config-dir or home-dir env vars, and similar host-owned launch options. A laptop and a remote host often should not start the same agent with the same model or the same config directory. Today changing those settings for one host changes them for every host.

The existing per-host settings surface (`hostSettingOverrides`) already treats some values as host-owned — display labels and the workspace directory — because those cannot be shared across machines. Agent launch command, args, and env have the same shape, but they are not in that map.

This is not a request for multiple named profiles of the same agent on one machine. Issues such as #2284, #12930, and #9136 cover that. This request is: one agent brand, independent launch settings per execution host.

Related, but different:

- #15320: per-host Workspace Directory is saved, then unused when resolving worktree paths. That shows host-scoped settings exist, but only for directories, and even that path is incomplete.
- #9370: the new-tab menu listed locally detected agents for a remote workspace. That is detection falling back to the client PATH, not per-host launch config.

### Proposed solution

Give each execution host its own agent launch command, args, and env, falling back to the current client defaults.

Effective values for a host:

```text
host override ?? client setting ?? catalog default
```

Concretely:

1. Extend `hostSettingOverrides[hostId]` with per-agent command, args, and env overrides.
2. Resolve that map on every launch that already knows the execution host: new tab, composer, SSH/runtime startup, resume, orchestration worker-start, mobile, and automations.
3. In Settings → Agents, reuse the existing “Apply to: \” pattern from Workspace Directory so a host can be edited without changing the client default.
4. Leave the current global values as the default for hosts with no override, so existing profiles keep working.

A host override must not replace the client default. Launching an agent locally should still use the local command, args, and env after an SSH host is given a different launch line.

### Alternatives or additional context

Workarounds that are not acceptable as the product answer:

- Changing the global Command, args, or env to values that only make sense on a remote host. That breaks the local host (and the reverse: local-only model or path settings leak onto every SSH host).
- Putting a binary on the remote PATH, or adding a symlink, so the global name happens to resolve. That mutates the machine instead of the Orca config, and does not cover hosts that need different models or env.
- Named command profiles (#16798 / #5754 style). Those are extra global commands for one agent, not one launch configuration per execution host.

`hostSettingOverrides` is the existing place for values that are meaningless to share across hosts. Agent launch command, args, and env belong there the same way workspace directory does.

Contributor guide

Open the contributing guide

Research direction

Start with the existing hostSettingOverrides handling and the Settings → Agents and Workspace Directory surfaces described in the issue. Trace how launch settings are resolved for new tabs, composer, SSH/runtime startup, resume, orchestration worker-start, mobile, and automations; done means each host can override command, args, and env while retaining client defaults as fallback.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
developer-experience, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.