Configuration

This page contains the basic configuration options in Peek. All these settings are tweakable in both a settings.json as well as in the UI.

Workspaces & Connections

A workspace is just a group of connections, representing either different projects or environments. You could either set up a workspace for My weather app and My Todo App, or one workspace for Production and one for Staging.

Inside each workspace is a list of connections.

Workspaces are serialized and stored as json at ~/peek/{workspace}, so you can back them up via version control.

You can manage your workspaces via the workspace picker in the UI, or you can edit your settings file directly.

~/peek/settings.json

{
  "workspaces": [
    {
      "name": "My weather app",
      "connections": [
        {
          "name": "local",
          "color": "hsl(280deg, 50%, 50%)",
          "url": "postgres://dbuser:dbpass@localhost:5432/dbname",
          "ssh": {
            "host": "123.45.67.01",
            "port": 22,
            "local_port": 54321,
            "username": "user",
            "password": "password"
          }
        }
      ]
    }
  ]
}

Themes

Peek comes with three themes, two dark themes Pine and Midnight, and a light theme Midday. You can set your theme by using the command palette P and typing theme.

You can also set the theme in your ~/peek/settings.json by updating the theme key.

~/peek/settings.json

{
  "theme": "Pine"
}

AI

There are two main ways to interact with the AI features in Peek. The first is the built in AI agent and the second is using your own agent via MCP.

Both methods use the same underlying functions and have the same capabilities. They are also not exposed to the query results, so you can't accidentally leak information.

Agent

Bring your own model use the built in Peek agent. Peek currently requires you to run your own OpenAI compatible server via Ollama, llama.cpp, lmstudio or similar. Once you have that running you can just need to specify which model and endpoint to use in your settings.

~/peek/settings.json

{
  "ai": {
    "model": "gemma4:12b",
    "url": "http://localhost:11434"
  }
}

MCP

You can connect a coding agent, like Claude Code, Codex or Antigravity via Peek's MCP and have them create or update nodes, move the camera or analyze results. This is particularly useful for automating repetitive tasks, or inspect the database as you are collaborating with an agent.

First you need to ensure that the mcp is enabled in Peek. The default settings are that it's off and the default port is 13315, but it can be overriden. You will need to restart Peek for the MCP to initialize.

~/.peek/settings.json

{
  "ai": {
    "mcp": {
      "enabled": true,
      "port": 13315
    }
  }
}

After you've enabled the MCP, you can add it to your favorite coding agent.

Claude Code

claude mcp add --transport http peek http://localhost:13315

Codex

codex mcp add peek --url http://localhost:13315

~/.gemini/config/mcp_config.json

{
  "mcpServers": {
    "peek": {
      "serverUrl": "http://localhost:13315"
    }
  }
}

Multiplayer

You can invite a collaborator to join your session in Peek. You do this by sending them a ticket that includes all the dialing address to your computer.

There is no centralized routing or message passing from Peek itself, so all data is P2P between the session collaborators. This is to ensure that it's fully safe to query results and look at data (with trusted collaborators) without worrying if Peek would leak any sensitive information.

Invited guests also aren't given any connection info to your database, the connection stays opaque and the only thing they see is the connection name. When they execute a query it's done from your connection, and they are fed the results.