Desktop Material

Agent API

The local agent request path through authentication, validation, exact repository resolution, and app safeguards

Desktop Material ships a built-in agent control surface so an AI agent can drive the app programmatically. It is exposed as an MCP server with a local HTTP + CLI fallback for environments where an MCP transport isn't convenient.

Status: shipped. The versioned command contract below is implemented on main and shared by MCP, REST, the stdio proxy, and the command-line client.

Enable and connect

  1. Open Settings → Agent access.
  2. Turn on Enable local agent server. The status changes to Listening and the panel displays the random loopback address and bearer token.
  3. Connect an HTTP-capable MCP client to the displayed /mcp URL and send Authorization: Bearer <token>.
  4. For a stdio-only client, run node script/agent/mcp-stdio-proxy.js from the checkout. For direct scripting, start with node script/agent/desktop-agent.js info or list tools with node script/agent/desktop-agent.js tools.

The proxy and CLI read the restricted local connection file written by the running app. Use Regenerate token in Settings to invalidate existing clients immediately.

Agent access connection and token controls

What it exposes

The agent surface maps onto the same operations the UI uses, routed through the Dispatcher and AppStore (see the Developer Guide) so agent-initiated actions obey the same state flow and safety checks as human ones:

Where the app already gates an action (for example the Automation preconditions), the agent path is subject to the same gates — it cannot force an operation the UI would refuse.

Clone to a saved SSH host

First save and test a host in Repository Settings → Remote → SSH Working Copy. The agent commands do not create hosts or accept connection credentials. list-ssh-hosts takes an empty object and discovers validated definitions attached to repositories currently available to the profile. It returns only bounded display metadata:

[
  {
    "id": "0123456789abcdef0123456789abcdef",
    "name": "Build host",
    "address": "build.example.test:2222",
    "available": true
  }
]

The response deliberately omits the SSH user, identity-file path, saved destination, source remote, and deployment settings. A duplicate host identifier from different repository definitions is ambiguous and is omitted rather than guessed.

Call clone-to-ssh with one returned hostId, a credential-free Git URL, an absolute or home-relative POSIX destination, and an optional branch:

{
  "hostId": "0123456789abcdef0123456789abcdef",
  "url": "ssh://git@code.example.test/team/project.git",
  "path": "~/work/project",
  "branch": "main"
}

The URL may use HTTPS, SSH, Git, or SCP-style SSH syntax, but embedded passwords, tokens, query strings, fragments, local paths, and option-shaped values are rejected. The destination must start with / or ~/, may not contain empty, . or .. segments, and must not already exist. Branches are validated before reaching the remote shell.

Desktop Material executes the saved OpenSSH definition with agent forwarding and connection sharing disabled. Passwords and key passphrases remain in the operating-system credential flow; they are not command arguments or results. Common private-key, credential-URL, bearer, password, passphrase, and provider-token shapes are redacted from failures before an agent response is returned.

Named API app functions

Create a function from the repository rail's API → App functions panel. The source must be a matching REST catalog operation or a named GraphQL operation; Desktop Material derives a closed JSON argument schema and records the assessed read/write/destructive risk. The definition follows the active profile and is capped with the rest of the catalog at 64 functions.

There are three equivalent discovery/invocation paths:

Function names start with a lowercase letter, contain only lowercase letters, numbers, _, or -, and are at most 64 characters before the github_api_ transport prefix. Argument schemas use additionalProperties: false; undeclared, missing, wrongly typed, oversized, prototype-shaped, or credential-shaped values are rejected rather than forwarded.

Exact binding and fail-closed behavior

A definition stores a stable account reference, never an account token, and is bound to all of the following:

Every invocation resolves the repository and account again, recomputes the binding, validates the arguments and request template, and checks that the current risk still matches the stored risk. A missing repository/account, changed remote/endpoint, stale fingerprint, malformed profile document, unknown operation, or schema/risk mismatch fails closed. Invalid restored profile state publishes an empty dynamic catalog, so an older function cannot remain runnable from stale UI state.

Read functions can execute through the agent transports. Write and destructive definitions remain visible in discovery, but invocation returns an error directing the user to the API tab's interactive mutation review; no agent argument can confirm that review. Credential-shaped keys, Bearer/Basic values, provider tokens, password-bearing URLs, and credential-like GraphQL fields are rejected when definitions or calls are validated. The bounded/redacted API workbench response and the agent server's normal output redaction still apply after a successful read.

Security model

The agent server is designed to be safe-by-default:

Transports

All transports share the same token gate, the same loopback binding, and the same rule that account tokens are never disclosed.

See also: Developer Guide · Automation