Local API

Gardn exposes a newline-delimited JSON control interface over a local socket. It is intended for same-user automation on the machine running the Gardn server.

The Local API is not HTTP, REST, or OpenAPI. It is separate from the binary protocol used by interactive clients for rendering, input, and direct terminal attachment.

Choose an integration surface

The Local API is the lowest-level public automation surface. It is not safer or more stable than the CLI: callers own socket selection, framing, timeouts, retries, and reconciliation.

Transport

A client opens the session's Local API socket, writes one JSON request followed by a newline, and reads one JSON response line. A normal request uses one connection with this envelope:

{ "id": "example:ping", "method": "ping", "params": {} }

The response echoes the caller-selected id:

{ "id": "example:ping", "result": { "type": "pong", "version": "0.2.19", "protocol": 13 } }

events.subscribe is the one exception to the one-response lifecycle. The server returns a subscription acknowledgement, then keeps the connection open and writes matching event lines until either side closes it.

Each request is limited to 1 MiB. The server waits up to five seconds for the initial request, for an app-handled response, and for each stream write. Individual wait operations can expose their own caller-selected timeout.

Socket selection

Commands resolve the socket for the active Gardn session by default. --session <name> selects a named session before command dispatch. GARDN_SOCKET_PATH overrides the resolved path when no explicit session is supplied.

The active socket path is reported by gardn status --json.

Trust model

The Local API has no network listener, bearer token, or per-method authorization layer. On Unix, Gardn creates the socket with mode 0600. Any process that can connect acts with the user's Gardn authority and can read terminal content, send input, start local or SSH-hosted processes, manage SSH connection profiles, change workspace state, or stop the server.

Treat the socket path and access to the local user account as security-sensitive. Do not forward the socket to another machine, expose it through a web server, or give untrusted plugins or subprocesses access unless they should receive the same authority.

Compatibility

The generated reference is versioned by the Gardn product version that produced it. Use the immutable schema URL for the version you target. The latest alias is updated only by a successful release deployment.

The protocol value reported by ping and schema metadata is the interactive client wire protocol version. It tells callers whether a binary can attach to a running server. It does not turn Local API JSON into that binary protocol.

Additive Local API shape changes can occur within a generated schema version. Consumers should ignore unknown object properties and result variants unless they need them. A schema_version change means schema consumers must review the generator contract before accepting the new document.

Reference

Start with the authored method guides for behavior, defaults, side effects, errors, and runnable examples:

• Sessions, workspaces, groups, and tabs
• Panes and agents
• Execution-host connections, extensions, integrations, server control, and subscriptions

Use the generated pages for exhaustive wire shapes from the current binary:

• Request parameter schemas
• Successful result variants
• Operational and subscription event variants
• Error response shape
• Enum values

For a first integration, continue with Send a request from a local script. Error semantics covers transport failures, API failures, retries, and streaming recovery.