Skip to main content

Run mecated standalone

mecated runs Mecatl as a standalone service over gRPC and HTTP/SSE. It is a lightweight starting point when you own one server and its local state. For a shared team, mecak8s supplies Redis-backed state and Kubernetes session coordination.

Install mecated​

Homebrew installs the mecatui client and the mecated server:

brew install stacklok/tap/mecatl
mecated --version

If you manage your environment with Conda, install the Mecatl package on Conda-forge with your preferred package manager:

Package managerCommand
Condaconda install -c conda-forge mecatl
Mambamamba install -c conda-forge mecatl
Pixipixi add mecatl

Install from a release archive​

GitHub releases provide darwin and linux archives for amd64 and arm64. Each release also includes checksums, Cosign signature bundles, SBOMs, and build provenance.

Download the archive for your OS and architecture, together with its checksum, signature bundle, and provenance. The example below uses macOS on Apple Silicon; replace the filename for another platform. <VERSION> is the release number used in the asset filename.

Verify the checksum, signature, and provenance before extracting the archive:

shasum -a 256 -c checksums.txt --ignore-missing

cosign verify-blob \
  --bundle mecatl_<VERSION>_darwin_arm64.tar.gz.sigstore.json \
  --certificate-identity-regexp '^https://github.com/stacklok/mecatl/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  mecatl_<VERSION>_darwin_arm64.tar.gz

gh attestation verify mecatl_<VERSION>_darwin_arm64.tar.gz --repo stacklok/mecatl

The Cosign command verifies that a GitHub Actions workflow in the stacklok/mecatl repository signed the archive.

Each archive contains mecatui and mecated at its root, plus the license and README. Extract the verified archive, then check the binaries:

tar -xzf mecatl_<VERSION>_darwin_arm64.tar.gz
./mecatui --version
./mecated --version

Build from source​

A source build requires Go 1.27.2 or later and Task v3. From the repository root, build all executables into bin/:

task build

Prepare model access​

Follow provider setup under the account that runs the server. Then choose provider custody and storage.

Start the server​

export ANTHROPIC_API_KEY="<ANTHROPIC_API_KEY>"
mecated serve --default-provider anthropic

A command word is required: mecated serve for the network daemon, mecated acp for the ACP stdio mode. Bare mecated prints the command help and exits with a usage error.

The minimal invocation starts a loopback-only server with in-memory sessions and no authentication.

Default addresses:

ListenerDefault
gRPC127.0.0.1:8080
HTTP/SSE127.0.0.1:8081
Prometheus + admin127.0.0.1:9090

To retain sessions across restarts and authenticate local clients:

export MECATL_AUTH_TOKEN="<SERVER_BEARER_TOKEN>"
mecated serve \
  --store-dir ~/.local/share/mecatl/sessions \
  --posture auto

--log-level accepts debug, info (default), warn, or error. Startup logs the binary version with msg="mecated starting".

--store-dir enables local JSONL persistence. The path and its ancestors must be physical directories, not symlinks. On macOS, use /private/... instead of a path through the /var symlink. --auth-token requires the token on every request and can also read MECATL_AUTH_TOKEN. --posture auto permits unattended calls within configured permission rules while retaining child prompt-injection protections. Configured Ask and Deny rules still apply; project trust is a separate grant.

Before binding a non-loopback address, add TLS and caller authentication. See Secure and expose mecated.

Connect and verify​

Keep the server running, then open a second terminal:

mecatui connect 127.0.0.1:8080

The TUI header shows the connected address. Send a short request, such as "Reply with a brief greeting," and confirm a response appears. The loopback connection uses the server's model access and workspace. To work with project files, start the server with --workspace <PROJECT_DIRECTORY>.

Before exposing this instance to remote clients, secure its listeners and caller access. For a shared team, follow Try Mecatl on Kubernetes.

Server-owned session placement​

--workspace sets the server's default workspace. Clients can request the default or the no-fs profile, but cannot submit a path. ListWorktrees returns short-lived selectors for ClearSession and ForkSession; selectors expire when the server restarts. Mecatl stores the exact placement privately and reattaches it before each run. See Execution environments for the shared placement and reattachment model.

Find an operational task​

Configure providers and durable storage.

Look up server flags.

Secure listeners and caller access.

Operate and recover the instance.

Host a private daemon from an application.

Next steps​