Mecatl

https://mecatl.dev/docs
Admin
Mecatl is an open-source, cloud-native agent harness for running AI agents across local...
Tokens:298,242
Snippets:2,829
Trust Score:5.3
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install mecatui with Homebrew and check version

Source: https://mecatl.dev/docs/mecatui/getting-started

Installs the mecatui client and mecatd server via Homebrew, then verifies the installation by printing the version. The version command should output a release tag.

```bash
brew install stacklok/tap/mecatl

mecatui --version
```

--------------------------------

### Start and check the Kind cluster

Source: https://mecatl.dev/docs/operating/kubernetes

Creates the local Kind cluster and checks its status. The env -u options keep the setup on the offline mock provider if provider keys are exported in the shell.

```bash
env -u ANTHROPIC_API_KEY \
  -u OPENAI_API_KEY \
  -u OPENROUTER_API_KEY \
  task mecak8s:kind-setup

task mecak8s:kind-status
```

--------------------------------

### Verify readiness and start embedded server

Source: https://mecatl.dev/docs/operating/microvm-environments

Run mecated microvm doctor to verify readiness, then start mecatui. This is done from the Git repository you want to work in.

```bash
mecated microvm doctor

mecatui
```

--------------------------------

### Run the OpenRouter example with provider dependency

Source: https://mecatl.dev/docs/building/getting-started/first-agent

Adds the OpenAI Responses-compatible provider dependency, sets the OpenRouter API key, and runs the example. The example uses openai/gpt-5.6-luna by default; set OPENROUTER_MODEL to use another model ID. This request may incur provider charges, so store the API key in a secret manager and keep it out of source code and command arguments.

```shell
go get github.com/stacklok/mecatl/provider/openai@latest

export OPENROUTER_API_KEY='<OPENROUTER_API_KEY>'

go run .
```

--------------------------------

### Start a daemon from Deno with spawn()

Source: https://mecatl.dev/docs/building/typescript-sdk/local-daemon

Imports spawn() from @stacklok-oss/mecatl-sdk/deno, creates a runtime directory, and starts a daemon with --mock. The client owns the readiness file and runtime directory, and closing it waits for the daemon to exit.

```typescript
import { spawn } from '@stacklok-oss/mecatl-sdk/deno';



await Deno.mkdir('.mecatl-runtime', { recursive: true });

await using client = await spawn({

  args: ['--mock'],

  tempDirectory: '.mecatl-runtime',

});



const session = await client.sessions.create({});

const result = await (await session.run('List the main packages')).result();



console.log(result.text);
```

--------------------------------

### Install adapters module with go get

Source: https://mecatl.dev/docs/building/extension-points/session-store

Pins the adapters module to v0.1.1. Requires Go 1.27 or later.

```bash
go get github.com/stacklok/mecatl/adapters@v0.1.1
```

--------------------------------

### Install mecatui via Homebrew

Source: https://mecatl.dev/docs/operating/kubernetes

Installs the mecatui client from the Stacklok Homebrew tap. Required to connect to the cluster in this tutorial.

```bash
brew install stacklok/tap/mecatl
```

--------------------------------

### Start embedded mecatui with mock provider

Source: https://mecatl.dev/docs/mecatui/troubleshooting

Starts the embedded mecatui server in offline mode with a mock provider, useful while learning the UI without provider credentials. Do not put provider secrets in command-line flags.

```bash
mecatui --mock --workspace "$PWD"
```

--------------------------------

### Create quickstart.ts

Source: https://mecatl.dev/docs/building/getting-started/typescript-sdk

Starts a private mecated process with --mock, creates a session, runs a prompt, and prints the result. Closes the client in a finally block to stop the daemon and remove its runtime directory.

```typescript
import { spawn } from '@stacklok-oss/mecatl-sdk/node';



const client = await spawn({ args: ['--mock'] });



try {

  const session = await client.sessions.create({});

  const run = await session.run('Say hello from Mecatl');

  const result = await run.result();



  console.log(result.text);

} finally {

  await client.close();

}
```

--------------------------------

### Rule with paths frontmatter

Source: https://mecatl.dev/docs/features/project-instructions-and-rules

Example rule with paths: frontmatter. The glob guides the model to apply the rule only to matching files; it does not restrict filesystem access. A rule without paths always applies.

```markdown
---

paths:

  - '**/*_test.go'

---



# Testing rule



Run the focused test and the full package test before reporting success.
```

--------------------------------

### Start mecated server with authentication and persistence

Source: https://mecatl.dev/docs/operating/mecated

Sets the MECATL_AUTH_TOKEN environment variable and starts the server with a store directory for session persistence and posture auto. The --store-dir path must be a physical directory, not a symlink. --posture auto permits unattended calls within configured permission rules.

```bash
export MECATL_AUTH_TOKEN="<SERVER_BEARER_TOKEN>"

mecated serve \

  --store-dir ~/.local/share/mecatl/sessions \

  --posture auto
```

--------------------------------

### Python executable reading Input JSON

Source: https://mecatl.dev/docs/mecatui/status-line

Example executable that reads raw Input JSON from stdin, extracts the context percentage, and prints a fixed StatusML document. Must be installed at the absolute path and made executable.

```python
#!/usr/bin/env python3

import json

import sys



status = json.load(sys.stdin)

percent = status["Context"]["Percent"]

print(f"<status><footer><text>ctx {percent}%</text></footer></status>")
```

--------------------------------

### Check server compatibility with client.server.compatibility()

Source: https://mecatl.dev/docs/building/typescript-sdk/server-discovery

Call `client.server.compatibility()` to get a current compatibility descriptor. Each call starts a fresh request, and the newest request becomes the shared compatibility check for subsequent SDK operations until it fails or another explicit call refreshes it.

```typescript
const compatibility = await client.server.compatibility({

  timeoutMs: 5_000,

});
```

--------------------------------

### mecated serve --posture examples

Source: https://mecatl.dev/docs/features/permissions-and-posture

Shows two example invocations of mecated serve with different posture settings. The first uses the default strict posture for interactive use, while the second uses auto for unattended deployments. Note that allow-all postures are refused when running as root unless MECATL_SANDBOX=1 or IS_SANDBOX=1 is set.

```bash
# Interactive, fail-closed default.

mecated serve --posture strict



# Unattended single-tenant deployment; review the trust implications first.

mecated serve --headless --posture auto
```

--------------------------------

### GET /v1/info

Source: https://mecatl.dev/docs/reference/http-sse-api

Documentation for the GET /v1/info endpoint, a process-wide identity probe.

```APIDOC
## GET /v1/info

### Description
Process-wide, state-free identity probe. Returns server build identity, implementation family, and optionally a sanitized display endpoint for a known provider.

### Method
GET

### Endpoint
/v1/info

### Parameters
#### Query Parameters
- **provider_id** (string) - Optional - Must be the caller's already-known active provider; may appear exactly once. Absent, repeated, or unknown selectors leave `llm_provider_display_endpoint` unavailable.

### Request Example
No request body.

### Response
#### Success Response (200)
- **build_id** (string) - Opaque linker-stamped build identity (`dev` in an unstamped source build).
- **server_implementation** (string) - Stable composition family: `mecated`, `mecak8s`, or embedded `mecatui`; a generic embedding uses `unknown`. Not an instance identifier or deployment label.
- **llm_provider_display_endpoint** (string, optional) - Sanitized display value for the supplied `provider_id`, or absent when unavailable. Retains only scheme, host, optional port, and escaped clean path; omits userinfo, query, fragment, invalid or control data, malformed values, and oversized values. Not connection configuration.

#### Response Example
```json
{
  "build_id": "dev",
  "server_implementation": "mecated",
  "llm_provider_display_endpoint": "https://api.example.com/v1"
}
```

### Error Handling
- **401** - Returned when required authentication is missing (when `--auth-token` or `MECATL_AUTH_TOKEN` is configured).
- **404** - Returned by older servers; clients should reduce that to their own safe unsupported status rather than display the response body.

### Notes
- The route is inside the normal API authentication boundary; send bearer token exactly as for other HTTP API routes; configured TLS or mTLS requirements also apply.
- The endpoint never returns configuration beyond the sanitized endpoint projection, nor capabilities, topology, listener details, authentication or TLS material, workspace paths, session or durable state, prompts, credentials, or raw errors.
- The route is additive; clients must tolerate an absent or blank `server_implementation` as `unknown`, and preserve an unfamiliar non-empty family for forward compatibility. `build_id` is not a semantic-version API.
```

--------------------------------

### Initialize Go module and add Mecatl engine dependency

Source: https://mecatl.dev/docs/building/getting-started/first-agent

Creates a project directory, initializes a Go module, and adds the Mecatl engine dependency. Requires Go 1.27 or newer.

```bash
mkdir first-agent

cd first-agent

go mod init example.com/first-agent

go get github.com/stacklok/mecatl/engine@latest

```

--------------------------------

### Install mecated via Homebrew and verify version

Source: https://mecatl.dev/docs/building/getting-started/typescript-sdk

Installs the released mecated executable from Stacklok's Homebrew tap and verifies it is available on PATH. The version command prints the installed release tag.

```bash
brew install stacklok/tap/mecatl

mecated --version
```

--------------------------------

### Install with Conda-forge using Mamba

Source: https://mecatl.dev/docs/mecatui/installation

Installs the mecatl package from Conda-forge using the Mamba package manager.

```bash
mamba install -c conda-forge mecatl
```

--------------------------------

### Construct Mecatl engine with adapters at composition root

Source: https://mecatl.dev/docs/building/extension-points

Shows how to create a store, policy, and engine with dependencies. The store can implement multiple interfaces (session persistence, pruning, durable events, tool-call recording). The exact dependencies depend on the Mecatl version and enabled features.

```go
store, err := yourstore.New(cfg.DatabaseURL)

if err != nil {

    return nil, err

}



policy := permpolicy.NewPolicy(rules, permstore.New())



engine := agent.NewEngine(agent.Deps{

    LLM:              provider,

    Catalog:          catalog,

    Store:            store,

    Policy:           policy,

    Hooks:            hooks,

    ToolCallRecorder: store,

    Diagnostics:      diagnostics,

    Clock:            wallclock.Clock{},

})
```

--------------------------------

### Install with Conda-forge using Conda

Source: https://mecatl.dev/docs/mecatui/installation

Installs the mecatl package from Conda-forge using the Conda package manager.

```bash
conda install -c conda-forge mecatl
```

--------------------------------

### Create session and prompt on headless server

Source: https://mecatl.dev/docs/operating/microvm-environments

Create a session on the deployment default, then prompt it and inspect status. Replace <SESSION_ID> with the actual session ID from the create response.

```bash
curl -sS -X POST http://127.0.0.1:8081/v1/sessions \
  -H 'Content-Type: application/json' \
  -d '{}'

SESSION_ID="<SESSION_ID>"
curl -sS -N -X POST "http://127.0.0.1:8081/v1/sessions/${SESSION_ID}/prompt" \
  -H 'Content-Type: application/json' \
  -d '{"text":"Run pwd and report the execution workspace."}'

mecated microvm status
```

--------------------------------

### mecatl gRPC HarnessService Client

Source: https://mecatl.dev/docs/reference/grpc-api

Go client example demonstrating how to connect to the mecatl gRPC HarnessService, create a session, open a Converse stream, and handle permission events.

```APIDOC
## CreateSession

### Description
Creates a new session with the specified permission mode. Returns a session ID used for subsequent operations.

### Method
RPC

### Endpoint
HarnessService/CreateSession

### Parameters
#### Request Body
- **mode** (PermissionMode) - Required - The permission mode for the session. Use `PERMISSION_MODE_DEFAULT` for default behavior.

### Request Example
```json
{
  "mode": "PERMISSION_MODE_DEFAULT"
}
```

### Response
#### Success Response
- **session_id** (string) - The unique identifier for the created session.

#### Response Example
```json
{
  "session_id": "..."
}
```

## Converse

### Description
Opens a bidirectional streaming RPC for conversation. The client must send a mandatory first `Prompt` message. The server streams events back, including permission requests that can be approved or cancelled.

### Method
RPC (bidirectional stream)

### Endpoint
HarnessService/Converse

### Parameters
#### Request Body (stream)
- **kind** (oneof) - Required - The message kind. Can be `Prompt`, `ResumeApproval`, or `Cancel`.
  - **Prompt** (Prompt) - Contains `session_id` and `text` for the user prompt.
  - **ResumeApproval** (ResumeApproval) - Contains `ask_id` and `allow` to approve or deny a permission request.
  - **Cancel** (Cancel) - Empty message to abort the conversation.

### Request Example
```json
{
  "kind": {
    "prompt": {
      "session_id": "...",
      "text": "List the Go files."
    }
  }
}
```

### Response
#### Success Response (stream)
- **event** (Event) - Contains `seq`, `type`, `text`, and optional `ask` details for permission requests.

#### Response Example
```json
{
  "event": {
    "seq": 1,
    "type": "permission.ask",
    "text": "...",
    "ask": {
      "ask_id": "..."
    }
  }
}
```

## GetSession

### Description
Returns a snapshot of the session state, including session ID, state, mode, placement metadata, limits, turns, tool calls, and creation timestamp. It never returns the private EnvironmentRef or filesystem path.

### Method
RPC

### Endpoint
HarnessService/GetSession

### Parameters
#### Request Body
- **session_id** (string) - Required - The ID of the session to retrieve.

### Request Example
```json
{
  "session_id": "..."
}
```

### Response
#### Success Response
- **session_id** (string) - The session ID.
- **state** (string) - The current state of the session.
- **mode** (PermissionMode) - The permission mode.
- **placement** (object) - Bounded placement metadata.
- **limits** (object) - Session limits.
- **turns** (int) - Number of turns.
- **tool_calls** (int) - Number of tool calls.
- **created_at_unix** (int) - Creation timestamp in Unix format.

#### Response Example
```json
{
  "session_id": "...",
  "state": "...",
  "mode": "PERMISSION_MODE_DEFAULT",
  "placement": {},
  "limits": {},
  "turns": 0,
  "tool_calls": 0,
  "created_at_unix": 0
}
```
```

--------------------------------

### Install SDK and TypeScript

Source: https://mecatl.dev/docs/building/getting-started/typescript-sdk

Installs the @stacklok-oss/mecatl-sdk package and TypeScript 6.0.3 as a dev dependency with exact version.

```bash
npm install @stacklok-oss/mecatl-sdk

npm install --save-dev --save-exact typescript@6.0.3
```

--------------------------------

### Install Mecatl with Conda, Mamba, or Pixi

Source: https://mecatl.dev/docs/operating/mecated

Commands to install the Mecatl package from Conda-forge using your preferred package manager.

```bash
conda install -c conda-forge mecatl
```

```bash
mamba install -c conda-forge mecatl
```

```bash
pixi add mecatl
```

--------------------------------

### Sign in with OIDC (discovery)

Source: https://mecatl.dev/docs/mecatui/remote-servers

Enroll once with `mecatui login` and then connect with `mecatui connect`. Login opens an Authorization Code with PKCE flow in your browser and stores credentials for that server. `connect` never opens a browser.

```bash
mecatui login mecated.example.com:443

mecatui connect mecated.example.com:443
```

--------------------------------

### Launch mecatui with a theme

Source: https://mecatl.dev/docs/mecatui/themes

Launches mecatui with the mono theme. Use --list-themes to print available themes.

```bash
mecatui --theme mono
```

--------------------------------

### Start mecatui with Anthropic API key

Source: https://mecatl.dev/docs/mecatui/getting-started

Sets the ANTHROPIC_API_KEY environment variable and starts mecatui in the current directory with the Anthropic provider. The workspace is set to the current directory.

```bash
cd <PROJECT_DIRECTORY>

export ANTHROPIC_API_KEY="<ANTHROPIC_API_KEY>"

mecatui --workspace "$PWD" --default-provider anthropic
```

--------------------------------

### Connect from Deno with @stacklok-oss/mecatl-sdk/deno

Source: https://mecatl.dev/docs/building/typescript-sdk/connect

Use this snippet to connect to a gRPC daemon from Deno. Import from the Deno entry point and pass the listener's HTTP or HTTPS authority as baseUrl. Grant network access with --allow-net=mecatl.example.com when running the application. Credentials use the same headers and credentialProvider options as Node.js and Bun; for a private CA, pass its certificate through nodeOptions.ca and grant read access if loading from disk. To connect to a Unix-domain socket, pass socketPath instead of baseUrl and grant network access with --allow-net=unix:<ABSOLUTE_SOCKET_PATH>.

```typescript
import { connect } from '@stacklok-oss/mecatl-sdk/deno';

await using client = connect({
  baseUrl: 'https://mecatl.example.com',
});

const session = await client.sessions.create({});
const result = await (await session.run('Summarize this repository')).result();
console.log(result.text);
```

--------------------------------

### HookEvent JSON example

Source: https://mecatl.dev/docs/features/hooks

Example of the JSON HookEvent written to the hook's stdin. The `Input` field is phase-specific; for `PreToolUse` it contains the tool's raw arguments JSON.

```json
{

  "Phase": "PreToolUse",

  "Tool": "Shell",

  "Input": { "command": "rm -rf build" },

  "SessionID": "8867bdea940108c1dd82d13d3fb7fc61"

}
```

--------------------------------

### Create a mock provider with mockllm.New

Source: https://mecatl.dev/docs/building/extension-points/llm-provider

Creates a mock provider that scripts deterministic turns without network access. Use mockllm.NewWith to set capabilities or observe incoming requests, and Calls to inspect the stream-call count and Reset to replay the script.

```go
provider := mockllm.New(

    mockllm.ToolCallTurn(

        session.NewToolCall(

            "call-1",

            "Read",

            json.RawMessage(`{"path":"main.go"}`),

        ),

    ),

    mockllm.TextTurn("The file defines the main package."),

)
```

--------------------------------

### Connect from Node.js or Bun with connect()

Source: https://mecatl.dev/docs/building/typescript-sdk/connect

Import connect() from the Node.js and Bun entry point and pass the gRPC listener's HTTP or HTTPS authority. The example uses MECATL_URL environment variable with a default of http://127.0.0.1:8080, creates a session, runs a prompt, and closes the client in a finally block.

```typescript
import { connect } from '@stacklok-oss/mecatl-sdk/node';



const client = connect({

  baseUrl: process.env.MECATL_URL ?? 'http://127.0.0.1:8080',

});



try {

  const session = await client.sessions.create({});

  const result = await (

    await session.run('Summarize this repository')

  ).result();

  console.log(result.text);

} finally {

  await client.close();

}
```

--------------------------------

### Run headless server with mecated

Source: https://mecatl.dev/docs/operating/microvm-environments

Start a headless server with mock provider and default placement. Use --headless for unattended API use and --mock only for offline smoke testing.

```bash
mecated microvm doctor

mecated serve --headless --mock --default-placement microvm-local
```

--------------------------------

### Install the chart and wait for replicas

Source: https://mecatl.dev/docs/operating/mecak8s

Upgrades or installs the mecak8s chart from the OCI registry with the specified version and values file, then waits for the deployment rollout to complete. The default Deployment name is <RELEASE>-mecak8s.

```bash
helm upgrade --install mecak8s \

  oci://ghcr.io/stacklok/mecatl/charts/mecak8s \

  --version <VERSION> \

  --namespace mecatl \

  --values mecak8s-values.yaml

kubectl rollout status deployment/mecak8s-mecak8s --namespace mecatl
```

--------------------------------

### Start server with OIDC issuer and audience

Source: https://mecatl.dev/docs/features/caller-identity

Typical configuration using the required issuer and audience flags. The validator requires an HTTPS issuer, and configuration or initial key-fetch failure prevents the service from starting.

```bash
mecated serve \

  --oidc-issuer https://idp.example.com/realms/operators \

  --oidc-audience mecatl \

  --workspace /srv/mecatl/workspace
```
Tokens:
Raw