Agent harnesses

A harness here is any coding agent that talks to an OpenAI-compatible or Ollama endpoint. Chalupa hosts the model and tunnels its endpoint to your laptop. Your agent runs locally with your tools and workspace.

Complete GPU inference setup and install your chosen agent before launching it. launch opens the tunnel and checks the model; it does not provision compute. When the agent exits, the tunnel closes and compute stays running until you run chalupa down.

Supported by default

These harnesses have built-in endpoint and model configuration:

Model and context defaults come from inference.model and inference.contextSize. Pass agent arguments after --, for example chalupa launch omp -- --no-session. Use --context auto before -- to negotiate context at connection time; see context limits.

Any other tool

Use chalupa exec -- <cmd> to run a local tool while Chalupa owns its tunnels. The child receives these variables:

Configure your tool to read those values or map them to its own settings. exec cannot infer an arbitrary tool's flags or provider configuration. OLLAMA_HOST remains inherited for other tools; only omp and ollama receive a replacement, so local embeddings can keep their own daemon.

For manual wiring, chalupa exec --format env prints shell exports without opening a tunnel or modifying files. It is an alias for chalupa connect --format env. Keep chalupa tunnel running in another terminal, then use this three-line example with a tool named my-agent that reads the exported values:

chalupa exec --format env
eval "$(chalupa exec --format env)"
my-agent

Alternatively, chalupa exec -- my-agent manages the tunnel and passes the variables directly to the child process. Configure the tool's endpoint mapping before using either path. No prompts or inference requests are sent by the export command.

Per-agent overrides

Put overrides in inference.agents.<agent>.config in your project's chalupa.yml. OpenCode and oh-my-pi accept configuration overrides; these keys are not a registry for arbitrary tools.

inference:
  model: qwen3.8:27b
  contextSize: 32768
  maxModelBytes: 25769803776
  agents:
    default: opencode
    opencode:
      config:
        small_model: chalupa/qwen3.8:27b
    omp:
      config:
        modelRoles:
          smol: ollama/qwen3.8:27b

This is an excerpt; keep the provider, SSH and session settings from setup. Nested objects merge over the generated configuration; arrays and scalars replace the generated values. Overrides win, so check any endpoint or model changes you declare. OpenCode gets the merged inline JSON; launch omp gets the merged temporary overlay. Generic exec -- omp supplies environment variables but does not create that overlay.

inference.agents.default selects the agent for a bare chalupa launch. Agent args precede arguments passed after --; env applies only to the child process and cannot override reserved CHALUPA_* variables. See the configuration reference.

Adding a first-class harness

Profiles live in src/cli/agent-profiles.ts. A profile must produce the agent's configuration or process environment from a validated InferenceEndpoint: model tag, local tunnel port and context size. Use the existing URL helpers and override merge behavior. Profile rendering must stay pure: no network, credentials, tunnel creation or edits to the agent's settings files.

To add launch support:

1. Add the name and supported override fields in src/config.ts.
2. Render the endpoint, model and context in src/cli/agent-profiles.ts.
3. Build the command in src/cli/agent-launch.ts and reuse runConnected from src/cli/exec.ts. If a temporary overlay is needed, restrict its permissions and remove it on both success and failure.
4. Add profile tests in tests/agent-profiles.test.ts for endpoint validation, URL mapping, model/context values, overrides and shell quoting. Add launch tests in tests/agent-launch.test.ts for arguments, environment, unchanged user settings and temporary-file cleanup. Cover CLI parsing in tests/inference.test.ts.
5. Update this table and CLI help. Run bunx tsc --noEmit and bun test ./tests/*.test.ts before submitting.

PRs are welcome. Include the harness version and a real tool-call check against the tunnelled endpoint. A rendered profile alone does not establish model compatibility. Receipt reporting is a separate contract; see reporting model turns.