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:

Crush integration was checked with v0.92.0 using its official configuration contract. Install Crush separately, then use chalupa launch crush or set inference.agents.default: crush. chalupa connect --format crush exports the JSON for manual configuration. JSON is supported by this version, although upstream now recommends crushrc for hand-written configuration.

Launch replaces global configuration and global selection state for the child process only; temporary files are removed on exit. Existing project Crush configuration still loads and can override these defaults. Put launch-specific changes in inference.agents.crush.config, .args, or .env. The launcher uses local process mode so an existing Crush server cannot retain another session's endpoint. Normal tool permissions remain in effect.

A local protocol smoke verified that the installed Crush sends requests to the configured /v1/chat/completions endpoint and model. This does not establish GPU model quality or tool-calling reliability. Crush sessions and logs are local; Chalupa inference receipts still require explicit reporting.

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.

MCP clients and service briefs

This page is about running a coding agent against a model on a GPU. The read-only MCP server (chalupa mcp), the action contract (chalupa explain --json) and the read-only service briefs (agentAccess with chalupa connect --format app-brief) work with any environment, not only GPU ones, so they have their own page: Chalupa for agents.

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. The env-only agents (local-agent, sonar, vecai) accept args and env only — they generate no config document to merge into.

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 agent dir. Generic exec -- omp supplies environment variables but does not create that agent dir.

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 agent dir 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.