Getting Started

This guide starts with the zero-config local path and then switches to an explicit config.yaml.

Install

Homebrew

brew install valon-technologies/gestalt/gestaltd
brew install valon-technologies/gestalt/gestalt

Binary releases

Download the latest binaries from the GitHub releases page and place them on your PATH.

Docker

The published image is valontechnologies/gestaltd. It expects /etc/gestalt/config.yaml and defaults to serve --locked --config /etc/gestalt/config.yaml. See Docker for the container layout and mount expectations.

Run A Local Server With No Config

gestaltd

If you do not pass --config and no local config exists, Gestalt writes a new file at ~/.gestalt/config.yaml and starts immediately.

The generated local config uses:

• auth.provider: none
• datastore.provider: sqlite
• secrets.provider: env
• telemetry.provider: stdout
• server.port: 8080

The generated SQLite database lives at ~/.gestalt/gestalt.db.

Write An Explicit Config

Save this as openapi/httpbin.yaml:

openapi: 3.0.3
info:
  title: HTTPBin
  version: 1.0.0
servers:
  - url: https://httpbin.org
paths:
  /ip:
    get:
      operationId: get_ip
      responses:
        "200":
          description: OK
  /headers:
    get:
      operationId: get_headers
      responses:
        "200":
          description: OK

Save this as config.yaml:

server:
  port: 8080
  base_url: http://localhost:8080
  encryption_key: dev-only-change-me
 
auth:
  provider: none
 
datastore:
  provider: sqlite
  config:
    path: ./gestalt.db
 
providers:
  httpbin:
    display_name: HTTPBin
    description: Public request and response inspection API
    connections:
      public:
        mode: none
        auth:
          type: none
    surfaces:
      openapi:
        document: ./openapi/httpbin.yaml
        connection: public
    mcp:
      enabled: true
      tool_prefix: httpbin_

This is the smallest useful Gestalt config:

• one explicit server block
• no platform auth
• SQLite storage
• one inline OpenAPI provider

Validate And Start It

gestaltd init --config ./config.yaml
gestaltd validate --config ./config.yaml
gestaltd serve --locked --config ./config.yaml

init writes gestalt.lock.json. With this inline config there are no packaged artifacts to fetch, but the same workflow scales to packaged providers and UI plugins.

Call The Integration

HTTP API

curl http://localhost:8080/api/v1/httpbin/get_ip

Client CLI

gestalt --url http://localhost:8080 integrations list
gestalt --url http://localhost:8080 invoke httpbin get_headers

Because auth.provider is none, no login step is required.

Next Steps

• Configuration explains config discovery, defaults, environment expansion, and locked startup.
• Integrations covers inline, packaged, and hybrid providers.
• Plugin Manifests shows how YAML manifests work for packaged plugins.
• Run Locally walks through local development patterns.