Skip to Content
Getting Started

Getting Started

This guide gets you from zero to invoking your first operation. It takes about five minutes.

Prerequisites

Install gestaltd (the server) and gestalt (the client CLI) using the installation instructions.

Start the server

Run gestaltd with no arguments:

gestaltd

When no config file exists, gestaltd generates one at ~/.gestaltd/config.yaml and starts immediately with SQLite storage via the RelationalDB  implementation of the IndexedDB provider, the default UI  mounted at /, no authentication, and an HTTPBin  implementation of the plugin provider on port 8080.

2026/04/10 10:00:00 INFO generated default config path=~/.gestaltd/config.yaml
2026/04/10 10:00:01 INFO gestaltd ready url=http://localhost:8080

Using the client

In a separate terminal, run the setup wizard:

gestalt init

The wizard prompts for the server URL. Enter http://localhost:8080 and it saves the connection to your local config.

Verify the connection:

gestalt plugin list
╭─────────────────────────────────────────────────────────────────────╮
│ Name       Description                                   Connected  │
╞═════════════════════════════════════════════════════════════════════╡
│ httpbin    HTTP request and response testing service.    -          │
╰─────────────────────────────────────────────────────────────────────╯

List operations

See what the httpbin plugin can do:

gestalt plugin invoke httpbin
╭─────────────────────────────────────────────────────────────────────────╮
│ Name              Description                                   Method  │
╞═════════════════════════════════════════════════════════════════════════╡
│ get_headers       Return the request headers                    GET     │
│ get_ip            Return the origin IP address                  GET     │
│ get_user_agent    Return the user agent string                  GET     │
│ get_anything      Return anything passed in the request         GET     │
│ post_anything     Return anything passed in the request body    POST    │
╰─────────────────────────────────────────────────────────────────────────╯

Invoke an operation

gestalt plugin invoke httpbin get_ip
╭──────────────────────────╮
│ key       value          │
╞══════════════════════════╡
│ origin    203.0.113.42   │
╰──────────────────────────╯

The CLI renders responses as a key-value table.

Both access the same underlying operation. Anything you can do with gestalt plugin invoke you can also do with curl or any HTTP client.

Connecting over MCP

Gestalt exposes all MCP-enabled plugins at a single endpoint: http://localhost:8080/mcp. Any MCP-compatible client can connect to it.

Add the following to your ~/.claude.json (user) or .claude/settings.json (project-level):

{
  "mcpServers": {
    "gestalt": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

Or via the CLI:

claude mcp add --transport http gestalt http://localhost:8080/mcp

Once connected, your agent can call any operation exposed by the server. The same auth model applies: when plugins require credentials, users connect through the Gestalt UI or CLI before the agent can invoke those tools.

Next steps

You have a running Gestalt server and you know how to invoke operations from the CLI, HTTP, and MCP. From here:

  • Configuration explains the config model, how to add plugins, set up auth, and configure connections.
  • Providers covers writing your own provider packages.
  • Deploy walks through production deployment with Helm and Docker.
Build from SourceConfiguration