Workspace files

A workspace is a folder ending in .echolot with plain TOML files in it: one per request, environment, MCP server, mock and flow. The Finder shows it as one document; in Terminal, Git and your editor it is a normal folder. Echolot writes every file the same way every time (keys in a fixed order, nothing written that has its default value), so a change in the app is a small change in the diff. See Git and teams.

Alpenglow.echolot/
  workspace.toml                     the workspace: ID, name, variables, auth, agents, proxy, certificates
  environments/
    staging.toml                     one environment
  requests/
    _folder.toml                     the order of the top level
    _folder.pre.js                   the workspace's pre-request script (and _folder.test.js)
    auth/
      _folder.toml                   a folder: name, order, docs, variables, auth
      sign-in.req.toml               an HTTP request
      sign-in.body.json              its body
      sign-in.pre.js                 its pre-request script
      sign-in.test.js                its test script
    catalog/
      search-products.gql.toml       a GraphQL request
      search-products.graphql        its query
  mcp-servers/
    alpenglow-mcp.toml               an MCP server
  specs/
    alpenglow.yaml                   an OpenAPI document
    shop.graphql                     a GraphQL schema
    inventory.proto                  a protobuf file
  mocks/
    shop.toml                        a mock server: settings and routes
    shop.js                          its routes in JavaScript
  flows/
    place-test-order.flow.toml       a flow
  assistant/
    checking-orders.md               a shared Assistant conversation, to read
    checking-orders.json             the same, to open in the app

Rules for every fileCopy Anchor Link

• Files are TOML 1.0, UTF-8.
• Each starts with echolot = 1, the format's version. A file with a higher number was saved by a newer Echolot, which Echolot says instead of opening it.
• File names are slugs: lowercase letters, digits and hyphens, at most 80 characters, made from the item's name (Sign in is sign-in). The name itself is the name key.
• Paths between items are slugs joined by /, relative to requests/: auth/sign-in, orders.
• Text fields can hold {{variables}} and dynamic values.
• Lists of things are TOML arrays of tables ([[headers]]). Anything with enabled = false is kept but switched off; without the key it is on.

What never goes in the filesCopy Anchor Link

• Secret values. A secret variable is written by its name with secret = true and no value; the value lives in the Keychain on your Mac. Fields that need a secret (a password, a proxy password, a client secret) should hold a {{variable}} that is a secret. Echolot offers to move a password you type into the Keychain, and imports do so by themselves. See secrets.
• OAuth tokens and MCP sign-ins: in the Keychain.
• Values that scripts set with pm.environment.set and the like: they last for the window or the command.
• History and responses: in Application Support on your Mac, one history per workspace. See history.
• Your own layout: the pane layout and its sizes, the open tabs, the environment you chose.

So a workspace is safe to commit and share. A teammate sets their own secret values.

workspace.tomlCopy Anchor Link

# Echolot workspace. Requests live in requests/, one file each.
echolot = 1
id = "0b7d4c1e-2f6a-4e38-9c51-7a1e3d9b5f20"
name = "Alpenglow"

[[variables]]
name = "baseURL"
value = "https://demo.echolot.dev/v1"

[[variables]]
name = "token"
secret = true

ProxyCopy Anchor Link

CertificatesCopy Anchor Link

Each [[certificates]] table is a rule for one host:

AgentsCopy Anchor Link

[agents] sets what AI agents may do in this workspace, through Echolot's MCP server and the Assistant. See agents.

[agents]
allowed-hosts = ["demo.echolot.dev"]
max-requests = 200
max-requests-per-minute = 30

[agents.rules]
unsafe-send = "ask"
destructive = "refuse"

The kinds of action are read, safe-send, unsafe-send, protected-send, new-host, workspace-write and destructive. A stricter rule always counts. A looser one counts only once you trust it (the app asks; the command line needs --trust-workspace-policy). protected-send and new-host can never be set to allow.

environments/Copy Anchor Link

One file per environment; its file name is its slug, used by --env.

echolot = 1
name = "Production"
protected = true

[[variables]]
name = "baseURL"
value = "https://api.alpenglow.example/v1"

[[variables]]
name = "password"
secret = true

VariablesCopy Anchor Link

The same in workspace.toml, environments, folders and requests:

requests/Copy Anchor Link

The requests folder holds the tree you see in the sidebar. Each folder in it is a folder of the tree, each request file a request. The kind of request comes from the file's suffix:

Beside a request, sharing its slug:

_folder.tomlCopy Anchor Link

Every folder has one, and so does requests/ itself, for the top level.

echolot = 1
name = "Auth"
order = ["sign-in", "who-am-i", "client-credentials"]
docs = "Send \"Sign in\" first: it captures the access token into {{token}}."

Beside it, _folder.pre.js and _folder.test.js are the folder's scripts; in requests/ they are the workspace's. They run for every request inside, from the workspace's down to the request's own. A folder that follows a spec also has _spec-lock.json, what it last took from the spec; let Echolot keep it.

Keys of every requestCopy Anchor Link

echolot = 1
name = "Sign in"
method = "POST"
url = "{{baseURL}}/auth/token"

[body]
syntax = "json"
file = "sign-in.body.json"

[[headers]]
name = "Content-Type"
value = "application/json"

[[assertions]]
target = "status"
check = "equals"
expected = "200"

[[captures]]
variable = "token"
from = "json"
path = "$.access_token"
scope = "workspace"
secret = true

HTTP requests (.req.toml)Copy Anchor Link

The [body] table takes one of three forms:

GraphQL requests (.gql.toml)Copy Anchor Link

echolot = 1
name = "Search products"
url = "{{baseURL}}/graphql"
operation = "SearchProducts"
schema = "specs/shop.graphql"
query-file = "search-products.graphql"
graphql-variables = """
{
  "text": "ultralight"
}"""

gRPC requests (.grpc.toml)Copy Anchor Link

WebSocket requests (.ws.toml)Copy Anchor Link

Socket.IO requests (.sio.toml)Copy Anchor Link

MQTT requests (.mqtt.toml)Copy Anchor Link

The user name and password are the request's Basic auth.

MCP calls (.mcp.toml)Copy Anchor Link

echolot = 1
name = "search_catalog"
server = "alpenglow-mcp"
tool = "search_catalog"
arguments = """
{
  "query": "ultralight tent",
  "limit": 3
}"""

AssertionsCopy Anchor Link

See scripts and tests for which checks each target offers.

CapturesCopy Anchor Link

A response of 400 or more, or a value that isn't there, leaves the variable as it was. See captures.

SettingsCopy Anchor Link

See request settings.

AuthCopy Anchor Link

[auth] has a type, and the keys of that type. A request or folder without [auth] inherits; the workspace's default is no auth.

Write every password, token and key as a secret {{variable}}. See auth.

mcp-servers/Copy Anchor Link

One file per MCP server; the file name is the slug that MCP calls name.

echolot = 1
name = "Alpenglow MCP"
transport = "http"
url = "https://demo.echolot.dev/mcp"

See adding servers.

specs/Copy Anchor Link

Spec files as they are: OpenAPI documents (.yaml, .yml, .json), GraphQL schemas (.graphql SDL, or an introspection result as JSON) and protobuf files (.proto). Echolot edits them in place and keeps your formatting. Requests and mocks name them by their path, such as specs/alpenglow.yaml. See specs.

mocks/Copy Anchor Link

One file per mock server, and its JavaScript routes beside it.

echolot = 1
name = "Shop"
spec = "specs/alpenglow.yaml"
port = 4010
delay = 200

[[scenarios]]
operation = "GET /products/{sku}"
status = "404"

[[routes]]
id = "e5f6a7b8"
method = "GET"
path = "/users/{id}"
summary = "One user"

[[routes.responses]]
name = "OK"
status = 200
content-type = "application/json"
headers = [{ name = "X-Request-Id", value = "{{$randomUUID}}" }]
body = """
{
  "id": "{{request.params.id}}",
  "name": "{{$randomFullName}}"
}"""

[[routes.responses]]
name = "Not found"
status = 404
content-type = "application/json"
rules = [{ source = "path", name = "id", value = "0" }]
body = """{ "error": "no user {{request.params.id}}" }"""

mocks/<slug>.js holds the mock's routes in JavaScript, which answer before the routes made by hand and the spec. For the spec's operations, responses never live in the mock: examples go into the spec. See mocks, routes and fake data and scripted routes.

flows/Copy Anchor Link

One file per flow, <slug>.flow.toml. Echolot writes blocks, wires and notes in a fixed order, so moving a block changes two lines.

echolot = 1
name = "Place a test order"
description = "Places an order, then asks a person whether to keep it."

[mcp]
tool = "place_test_order"
description = "Places a test order on the demo shop, asking a person before keeping it."

[[blocks]]
id = "signin"
kind = "request"
title = "Sign in"
position = [330, 250]

[blocks.settings]
request = "auth/sign-in"

[[wires]]
from = "start.run"
to = "signin.run"

The block kinds and their settings are on blocks.

assistant/Copy Anchor Link

Conversations with the Assistant that you share in the workspace: <slug>.md to read in any editor, and <slug>.json for Echolot to open again.

Other filesCopy Anchor Link

Files Echolot doesn't know are left alone, so a README, a .gitignore or data files can live in the workspace. Data an agent or a flow saves (such as exports/products.csv) goes where it was asked to, inside the workspace.